{"_id":"@iflow-mcp/ryanjoachim-mcp-batchit","_rev":"2-7a3650a46e35d968d3975495be29f91f","name":"@iflow-mcp/ryanjoachim-mcp-batchit","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@iflow-mcp/ryanjoachim-mcp-batchit","version":"1.0.0","keywords":["mcp","modelcontextprotocol","batch","operations","ai","llm","agent","filesystem","aggregator"],"author":{"name":"Ryan Joachim"},"license":"MIT","_id":"@iflow-mcp/ryanjoachim-mcp-batchit@1.0.0","maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"homepage":"https://github.com/ryanjoachim/mcp-batchit#readme","bugs":{"url":"https://github.com/ryanjoachim/mcp-batchit/issues"},"bin":{"iflow-mcp_ryanjoachim-mcp-batchit":"build/index.js"},"dist":{"shasum":"36ab97afd947af4c58a1dacdbcee04efae3fb6f7","tarball":"https://registry.npmjs.org/@iflow-mcp/ryanjoachim-mcp-batchit/-/ryanjoachim-mcp-batchit-1.0.0.tgz","fileCount":6,"integrity":"sha512-eOXRYrwBIyAj2VQABZctbj4KiUeLH0b+u7OWAeMkcz2Pd7l5siBlqDoR/+4Q5m7/4ouM91DuhV9n9H2uvUW/vg==","signatures":[{"sig":"MEYCIQDczNJ9Z0rw0eZ2+JKIdity8aKuejHxF/a8s+9mhTC81AIhAMRJzMQXrDWlRBM1jIWJStjP5gu3lyaRpe2YbrGkzM7c","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44792},"main":"build/index.js","type":"module","_from":"file:/app/auto-mcp-upload/data/9236/iflow-mcp-ryanjoachim-mcp-batchit-1.0.0.tgz","types":"build/index.d.ts","config":{"run-script":{"build":"npm run build"}},"scripts":{"lint":"eslint src --ext .ts","test":"jest","build":"tsc","clean":"rimraf build","watch":"tsc --watch","prepare":"npm run build"},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"_resolved":"/app/auto-mcp-upload/data/9236/iflow-mcp-ryanjoachim-mcp-batchit-1.0.0.tgz","_integrity":"sha512-eOXRYrwBIyAj2VQABZctbj4KiUeLH0b+u7OWAeMkcz2Pd7l5siBlqDoR/+4Q5m7/4ouM91DuhV9n9H2uvUW/vg==","repository":{"url":"git+https://github.com/ryanjoachim/mcp-batchit.git","type":"git"},"_npmVersion":"11.6.2","description":"Batch multiple MCP tool calls into a single request—reducing overhead and token usage for AI agents","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.4.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","rimraf":"^5.0.5","ts-jest":"^29.1.1","ts-node":"^10.9.2","typescript":"^5.7.2","@types/jest":"^29.5.11","@types/node":"^22.8.0"},"_npmOperationalInternal":{"tmp":"tmp/ryanjoachim-mcp-batchit_1.0.0_1770973671665_0.4466008732819702","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@iflow-mcp/ryanjoachim-mcp-batchit","version":"1.0.1","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":{"iflow-mcp_ryanjoachim-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"],"author":{"name":"Ryan Joachim"},"repository":{"type":"git","url":"git+https://github.com/ryanjoachim/mcp-batchit.git"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.4.0","zod":"^3.25.76"},"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"},"_id":"@iflow-mcp/ryanjoachim-mcp-batchit@1.0.1","bugs":{"url":"https://github.com/ryanjoachim/mcp-batchit/issues"},"homepage":"https://github.com/ryanjoachim/mcp-batchit#readme","_integrity":"sha512-xe7rs8pDj7jP5UPuApg95T9Obeq8PHluMX5pCYVnp+aQgw+k3wZBeOUCn88xyiYcjKPUfMRRSeFtB+ABQgFqrQ==","_resolved":"/app/auto-mcp-upload/data/9236/iflow-mcp-ryanjoachim-mcp-batchit-1.0.1.tgz","_from":"file:/app/auto-mcp-upload/data/9236/iflow-mcp-ryanjoachim-mcp-batchit-1.0.1.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-xe7rs8pDj7jP5UPuApg95T9Obeq8PHluMX5pCYVnp+aQgw+k3wZBeOUCn88xyiYcjKPUfMRRSeFtB+ABQgFqrQ==","shasum":"902e491a59bf1b9c7fd662439b5763a200801869","tarball":"https://registry.npmjs.org/@iflow-mcp/ryanjoachim-mcp-batchit/-/ryanjoachim-mcp-batchit-1.0.1.tgz","fileCount":6,"unpackedSize":44864,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC7Wt3QfAj0jSjH6UEY8soYFVkgvsXuohJpmoMMv0uiwAiA6uBGfS4+fCaHZ46uK5dwlV9S2EyJNh8mqQZcO93XipQ=="}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ryanjoachim-mcp-batchit_1.0.1_1770973949956_0.8297654848971925"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-13T09:07:51.555Z","modified":"2026-02-13T09:12:30.276Z","1.0.0":"2026-02-13T09:07:51.798Z","1.0.1":"2026-02-13T09:12:30.104Z"},"bugs":{"url":"https://github.com/ryanjoachim/mcp-batchit/issues"},"author":{"name":"Ryan Joachim"},"license":"MIT","homepage":"https://github.com/ryanjoachim/mcp-batchit#readme","keywords":["mcp","modelcontextprotocol","batch","operations","ai","llm","agent","filesystem","aggregator"],"repository":{"type":"git","url":"git+https://github.com/ryanjoachim/mcp-batchit.git"},"description":"Batch multiple MCP tool calls into a single request—reducing overhead and token usage for AI agents","maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"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"}