{"_id":"@mseep/mcp-batchit","name":"@mseep/mcp-batchit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@mseep/mcp-batchit","version":"1.0.0","description":"Batch multiple MCP tool calls into a single request—reducing overhead and token usage for AI agents","main":"build/index.js","type":"module","types":"build/index.d.ts","bin":{"mcp-batchit":"build/index.js"},"scripts":{"build":"tsc","prepare":"npm run build","watch":"tsc --watch","test":"jest","lint":"eslint src --ext .ts","clean":"rimraf build"},"config":{"run-script":{"build":"npm run build"}},"keywords":["mcp","modelcontextprotocol","batch","operations","ai","llm","agent","filesystem","aggregator","mseep","mcp-server"],"author":{"name":"Ryan Joachim"},"repository":{"type":"git","url":"git+https://github.com/ryanjoachim/mcp-batchit.git"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.4.0"},"devDependencies":{"@types/jest":"^29.5.11","@types/node":"^22.8.0","jest":"^29.7.0","rimraf":"^5.0.5","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.7.2"},"publisher":"mseep","_id":"@mseep/mcp-batchit@1.0.0","gitHead":"5870243813342a77c96c478468e821d4260d470e","bugs":{"url":"https://github.com/ryanjoachim/mcp-batchit/issues"},"homepage":"https://github.com/ryanjoachim/mcp-batchit#readme","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-17exFsLkuzjYu+W8ITsWvoHnpFxIzwo0+Le+WtO6ZKMh8JD5PA8q97PsdXnehNlPyZWTYaSqPX9c9jdvj0dRMw==","shasum":"eb496dfd9d06c33dae6a211147f29c0ee324df2f","tarball":"https://registry.npmjs.org/@mseep/mcp-batchit/-/mcp-batchit-1.0.0.tgz","fileCount":6,"unpackedSize":45055,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIESKeiujCjHNznRS8Se699evw1rnxkt/qS0/7ZCX2ugfAiEA3smFeQL/iMxIMHV8cNXhrsN7q2CzBpW0b9DU6tkDe6w="}]},"_npmUser":{"name":"skydeckai","email":"support@skydeck.ai"},"directories":{},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-batchit_1.0.0_1744833402986_0.9649882702727111"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-16T19:56:42.845Z","1.0.0":"2025-04-16T19:56:43.205Z","modified":"2025-04-16T19:56:43.487Z"},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"description":"Batch multiple MCP tool calls into a single request—reducing overhead and token usage for AI agents","homepage":"https://github.com/ryanjoachim/mcp-batchit#readme","keywords":["mcp","modelcontextprotocol","batch","operations","ai","llm","agent","filesystem","aggregator","mseep","mcp-server"],"repository":{"type":"git","url":"git+https://github.com/ryanjoachim/mcp-batchit.git"},"author":{"name":"Ryan Joachim"},"bugs":{"url":"https://github.com/ryanjoachim/mcp-batchit/issues"},"license":"MIT","readme":"\n<div align=\"center\">\n\n# MCP BatchIt\n\n**Batch multiple MCP tool calls into a single \"batch_execute\" request—reducing overhead and token usage for AI agents.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n</div>\n\n---\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Why Use BatchIt](#why-use-batchit)\n3. [Key Features & Limitations](#key-features--limitations)\n4. [Installation & Startup](#installation--startup)\n5. [Multi-Phase Usage](#multi-phase-usage)\n   - [Implementation Phases](#implementation-phases)\n     - [Information Gathering](#information-gathering)\n     - [LLM‐Only Step (List Code Definitions)](#llm-only-step-list-code-definitions)\n     - [Document Creation](#document-creation)\n6. [FAQ](#faq)\n7. [License](#license)\n\n---\n\n## Introduction\n> ⚠️ **NOTICE: Work in Progress**\n>\n> This project is actively being developed to address several complex challenges:\n> - Maintaining backwards compatibility with existing MCP servers\n> - Resolving transport complexities with multi-connection clients (Cline, Roo, Claude Desktop)\n> - Creating a beginner-friendly implementation\n>\n> While functional, expect ongoing improvements and changes as we refine the solution.\n\n**MCP BatchIt** is a simple aggregator server in the [Model Context Protocol (MCP)](https://modelcontext.ai/) ecosystem. It exposes just **one** tool: **`batch_execute`**. Rather than calling multiple MCP tools (like `fetch`, `read_file`, `create_directory`, `write_file`, etc.) in **separate** messages, you can **batch** them together in one aggregator request.\n\nThis dramatically reduces token usage, network overhead, and repeated context in your AI agent or LLM conversation.\n\n---\n\n## Why Use BatchIt\n\n- **One Action per Message** Problem:\n  Normally, an LLM or AI agent can only call a single MCP tool at a time, forcing multiple calls for multi-step tasks.\n\n- **Excessive Round Trips**:\n  10 separate file operations might require 10 messages → 10 responses.\n\n- **BatchIt’s Approach**:\n  1. Takes a single `batch_execute` request.\n  2. Spawns (or connects to) the actual target MCP server (like a filesystem server) behind the scenes.\n  3. Runs each sub-operation (tool call) in parallel up to `maxConcurrent`.\n  4. If one sub-op fails and `stopOnError` is true, it halts new sub-ops.\n  5. Returns one consolidated JSON result.\n\n---\n\n## Key Features & Limitations\n\n### Features\n\n1. **Single “Batch Execute” Tool**\n   - You simply specify a list of sub‐ops referencing your existing MCP server’s tools.\n\n2. **Parallel Execution**\n   - Run multiple sub-ops at once, controlled by `maxConcurrent`.\n\n3. **Timeout & Stop on Error**\n   - Each sub-op races a `timeoutMs`, and you can skip remaining ops if one fails.\n\n4. **Connection Caching**\n   - Reuses the same connection to the downstream MCP server for repeated calls, closing after an idle timeout.\n\n### Limitations\n\n1. **No Data Passing Mid-Batch**\n   - If sub-op #2 depends on #1’s output, do multiple aggregator calls.\n2. **No Partial Progress**\n   - You get all sub-ops’ results together at the end of each “batch_execute.”\n3. **Must Use a Real MCP Server**\n   - If you spawn or connect to the aggregator itself, you’ll see “tool not found.” The aggregator only has “batch_execute.”\n4. **One Target Server per Call**\n   - Each aggregator call references a single target MCP server. If you want multiple servers, you’d do more advanced logic or separate calls.\n\n---\n\n## Installation & Startup\n\n```bash\ngit clone https://github.com/ryanjoachim/mcp-batchit.git\ncd mcp-batchit\nnpm install\nnpm run build\nnpm start\n```\n\nBatchIt starts on **STDIO** by default so your AI agent (or any MCP client) can spawn it. For example:\n\n```\nmcp-batchit is running on stdio. Ready to batch-execute!\n```\n\nYou can now send JSON-RPC requests (`tools/call` method, `name= \"batch_execute\"`) to it.\n\n---\n\n## MEMORY BANK\n\nUsing Cline/Roo Code, you can build a framework of contextual project documentation by leveraging the powerful \"Memory Bank\" custom instructions developed by Nick Baumann.\n\n[View Memory Bank Documentation](https://github.com/nickbaumann98/cline_docs/blob/main/prompting/custom%20instructions%20library/cline-memory-bank.md)\n\n#### Traditional Approach (19+ calls):\n\n1. Read package.json\n2. Wait for response\n3. Read README.md\n4. Wait for response\n5. List code definitions\n6. Wait for response\n7. Create memory-bank directory\n8. Wait for response\n9. Write productContext.md\n10. Write systemPatterns.md\n11. Write techContext.md\n12. Write progress.md\n13. Write activeContext.md\n14. Wait for responses (5 more calls)\n\nTotal: ~19 separate API calls (13 operations + 6 response waits)\n\n#### BatchIt Approach (1-3 calls)\n\n### Multi-Phase Usage\n\nWhen working with complex multi-step tasks that depend on real-time output (such as reading files and generating documentation), you'll need to handle the process in distinct phases. This is necessary because **BatchIt** doesn't support data passing between sub-operations within the same request.\n\n### Implementation Phases\n\n#### Information Gathering\n\nIn this initial phase, we gather information from the filesystem by reading necessary files (e.g., `package.json`, `README.md`). This is accomplished through a **batch_execute** call to the filesystem MCP server:\n\n```jsonc\n{\n  \"targetServer\": {\n    \"name\": \"filesystem\",\n    \"serverType\": {\n      \"type\": \"filesystem\",\n      \"config\": {\n        \"rootDirectory\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit\"\n      }\n    },\n    \"transport\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd.exe\",\n      \"args\": [\n        \"/c\",\n        \"npx\",\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit\"\n      ]\n    }\n  },\n  \"operations\": [\n    {\n      \"tool\": \"read_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/package.json\"\n      }\n    },\n    {\n      \"tool\": \"read_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/README.md\"\n      }\n    }\n  ],\n  \"options\": {\n    \"maxConcurrent\": 2,\n    \"stopOnError\": true,\n    \"timeoutMs\": 30000\n  }\n}\n```\n\n**Note**: The aggregator spawns `@modelcontextprotocol/server-filesystem` (via `npx`) to execute parallel `read_file` operations.\n\n#### LLM‐Only Step (List Code Definitions)\n\nThis phase involves processing outside the aggregator, typically using LLM or AI agent capabilities:\n\n```typescript\n<list_code_definition_names>\n<path>src</path>\n</list_code_definition_names>\n```\n\nThis step utilizes Roo Code's `list_code_definition_names` tool, which is exclusively available to LLMs. However, note that many MCP servers can provide similar functionality, making it possible to complete this process without LLM requests.\n\n#### Document Creation\n\nThe final phase combines data from previous steps (file contents and code definitions) to generate documentation in the `memory-bank` directory:\n\n```jsonc\n{\n  \"targetServer\": {\n    \"name\": \"filesystem\",\n    \"serverType\": {\n      \"type\": \"filesystem\",\n      \"config\": {\n        \"rootDirectory\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit\"\n      }\n    },\n    \"transport\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd.exe\",\n      \"args\": [\n        \"/c\",\n        \"npx\",\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit\"\n      ]\n    }\n  },\n  \"operations\": [\n    {\n      \"tool\": \"create_directory\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank\"\n      }\n    },\n    {\n      \"tool\": \"write_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/productContext.md\",\n        \"content\": \"# MCP BatchIt Product Context\\\\n\\\\n## Purpose\\\\n...\"\n      }\n    },\n    {\n      \"tool\": \"write_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/systemPatterns.md\",\n        \"content\": \"# MCP BatchIt System Patterns\\\\n\\\\n## Architecture Overview\\\\n...\"\n      }\n    },\n    {\n      \"tool\": \"write_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/techContext.md\",\n        \"content\": \"# MCP BatchIt Technical Context\\\\n\\\\n## Technology Stack\\\\n...\"\n      }\n    },\n    {\n      \"tool\": \"write_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/progress.md\",\n        \"content\": \"# MCP BatchIt Progress Status\\\\n\\\\n## Completed Features\\\\n...\"\n      }\n    },\n    {\n      \"tool\": \"write_file\",\n      \"arguments\": {\n        \"path\": \"C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/activeContext.md\",\n        \"content\": \"# MCP BatchIt Active Context\\\\n\\\\n## Current Status\\\\n...\"\n      }\n    }\n  ],\n  \"options\": {\n    \"maxConcurrent\": 1,\n    \"stopOnError\": true,\n    \"timeoutMs\": 30000\n  }\n}\n```\n\nThe aggregator processes these operations sequentially (`maxConcurrent=1`), creating the directory and writing multiple documentation files. The result array indicates the success/failure status of each operation.\n\n---\n\n## FAQ\n\n**Q1: Do I need multiple aggregator calls if sub-op #2 depends on sub-op #1’s results?**\n**Yes.** BatchIt doesn’t pass data between sub-ops in the same request. You do multi-phase calls (like the example above).\n\n**Q2: Why do I get “Tool create_directory not found” sometimes?**\nBecause your `transport` might be pointing to the aggregator script itself instead of the real MCP server. Make sure you reference something like `@modelcontextprotocol/server-filesystem`.\n\n**Q3: Can I do concurrency plus stopOnError?**\nAbsolutely. If a sub-op fails, we skip launching new sub-ops. Already-running ones finish in parallel.\n\n**Q4: Does BatchIt re-spawn the target server each time?**\nIt *can* if you specify `keepAlive: false`. But if you use the same exact `targetServer.name + transport`, it caches the connection until an idle timeout passes.\n\n**Q5: Are partial results returned if an error occurs in the middle?**\nYes. Each sub-op that finished prior to the error is included in the final aggregator response, along with the failing sub-op. Remaining sub-ops are skipped if `stopOnError` is true.\n\n---\n\n## License\n\n**MIT**\n","readmeFilename":"README.md","_rev":"1-893a0f01cabf6dd91f310218e2b4b1d5"}