MCP 服务器

MCP BatchIt

一个简单的聚合服务器，允许将多个 MCP 工具调用批量处理成单个请求，从而减少 AI 代理的 token 使用量和网络开销。

远程shell执行

AI集成系统

README

<div align="center">

# MCP BatchIt

**将多个 MCP 工具调用批处理到单个“batch_execute”请求中，从而减少 AI 代理的开销和令牌使用量。**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

---

## 目录

1. [简介](#introduction)
2. [为什么使用 BatchIt](#why-use-batchit)
3. [主要特性和限制](#key-features--limitations)
4. [安装和启动](#installation--startup)
5. [多阶段使用](#multi-phase-usage)
   - [实施阶段](#implementation-phases)
     - [信息收集](#information-gathering)
     - [仅 LLM 步骤（列出代码定义）](#llm-only-step-list-code-definitions)
     - [文档创建](#document-creation)
6. [常见问题解答](#faq)
7. [许可证](#license)

---

## 简介
> ⚠️ **注意：正在进行中**
>
> 该项目正在积极开发中，以解决几个复杂的挑战：
> - 保持与现有 MCP 服务器的向后兼容性
> - 解决多连接客户端（Cline、Roo、Claude Desktop）的传输复杂性
> - 创建一个对初学者友好的实现
>
> 虽然功能正常，但随着我们完善解决方案，预计会有持续的改进和更改。

**MCP BatchIt** 是 [模型上下文协议 (MCP)](https://modelcontext.ai/) 生态系统中的一个简单聚合服务器。它只公开**一个**工具：**`batch_execute`**。您可以将多个 MCP 工具（如 `fetch`、`read_file`、`create_directory`、`write_file` 等）**批量**组合到一个聚合器请求中，而不是在**单独**的消息中调用它们。

这大大减少了 AI 代理或 LLM 对话中的令牌使用量、网络开销和重复上下文。

---

## 为什么使用 BatchIt

- **每个消息一个操作**问题：
  通常，LLM 或 AI 代理一次只能调用一个 MCP 工具，这迫使多步骤任务需要多次调用。

- **过多的往返**:
  10 个单独的文件操作可能需要 10 条消息 → 10 个响应。

- **BatchIt 的方法**:
  1. 接受单个 `batch_execute` 请求。
  2. 在后台生成（或连接到）实际的目标 MCP 服务器（如文件系统服务器）。
  3. 并行运行每个子操作（工具调用），最多 `maxConcurrent` 个。
  4. 如果一个子操作失败并且 `stopOnError` 为 true，它将停止新的子操作。
  5. 返回一个合并的 JSON 结果。

---

## 主要特性和限制

### 特性

1. **单个“批量执行”工具**
   - 您只需指定一个子操作列表，引用您现有 MCP 服务器的工具。

2. **并行执行**
   - 一次运行多个子操作，由 `maxConcurrent` 控制。

3. **超时和错误时停止**
   - 每个子操作竞争一个 `timeoutMs`，如果一个操作失败，您可以跳过剩余的操作。

4. **连接缓存**
   - 为重复调用重用与下游 MCP 服务器的相同连接，并在空闲超时后关闭。

### 限制

1. **批处理期间不传递数据**
   - 如果子操作 #2 依赖于 #1 的输出，请进行多次聚合器调用。
2. **没有部分进度**
   - 您将在每个“batch_execute”结束时一起获得所有子操作的结果。
3. **必须使用真正的 MCP 服务器**
   - 如果您生成或连接到聚合器本身，您将看到“找不到工具”。聚合器只有“batch_execute”。
4. **每次调用一个目标服务器**
   - 每个聚合器调用引用一个目标 MCP 服务器。如果您想要多个服务器，您需要进行更高级的逻辑或单独的调用。

---

## 安装和启动

```bash
git clone https://github.com/ryanjoachim/mcp-batchit.git
cd mcp-batchit
npm install
npm run build
npm start

BatchIt 默认在 STDIO 上启动，因此您的 AI 代理（或任何 MCP 客户端）可以生成它。例如：

mcp-batchit is running on stdio. Ready to batch-execute!

您现在可以向它发送 JSON-RPC 请求（tools/call 方法，name= "batch_execute"）。

记忆库

使用 Cline/Roo 代码，您可以通过利用 Nick Baumann 开发的强大的“记忆库”自定义指令来构建上下文项目文档框架。

查看记忆库文档

传统方法（19+ 次调用）：

读取 package.json
等待响应
读取 README.md
等待响应
列出代码定义
等待响应
创建 memory-bank 目录
等待响应
写入 productContext.md
写入 systemPatterns.md
写入 techContext.md
写入 progress.md
写入 activeContext.md
等待响应（5 次更多调用）

总计：~19 个单独的 API 调用（13 个操作 + 6 个响应等待）

BatchIt 方法（1-3 次调用）

多阶段使用

当处理依赖于实时输出的复杂多步骤任务（例如读取文件和生成文档）时，您需要以不同的阶段处理该过程。这是必要的，因为 BatchIt 不支持在同一请求中的子操作之间传递数据。

实施阶段

信息收集

在此初始阶段，我们通过读取必要的文件（例如，package.json、README.md）从文件系统中收集信息。这是通过对文件系统 MCP 服务器的 batch_execute 调用完成的：

{
  "targetServer": {
    "name": "filesystem",
    "serverType": {
      "type": "filesystem",
      "config": {
        "rootDirectory": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit"
      }
    },
    "transport": {
      "type": "stdio",
      "command": "cmd.exe",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit"
      ]
    }
  },
  "operations": [
    {
      "tool": "read_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/package.json"
      }
    },
    {
      "tool": "read_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/README.md"
      }
    }
  ],
  "options": {
    "maxConcurrent": 2,
    "stopOnError": true,
    "timeoutMs": 30000
  }
}

注意: 聚合器生成 @modelcontextprotocol/server-filesystem（通过 npx）来执行并行 read_file 操作。

仅 LLM 步骤（列出代码定义）

此阶段涉及在聚合器外部进行处理，通常使用 LLM 或 AI 代理功能：

<list_code_definition_names>
<path>src</path>
</list_code_definition_names>

此步骤利用 Roo Code 的 list_code_definition_names 工具，该工具仅适用于 LLM。但是，请注意，许多 MCP 服务器可以提供类似的功能，从而可以无需 LLM 请求即可完成此过程。

文档创建

最后阶段结合了先前步骤中的数据（文件内容和代码定义）以在 memory-bank 目录中生成文档：

{
  "targetServer": {
    "name": "filesystem",
    "serverType": {
      "type": "filesystem",
      "config": {
        "rootDirectory": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit"
      }
    },
    "transport": {
      "type": "stdio",
      "command": "cmd.exe",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit"
      ]
    }
  },
  "operations": [
    {
      "tool": "create_directory",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank"
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/productContext.md",
        "content": "# MCP BatchIt 产品上下文\\n\\n## 目的\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/systemPatterns.md",
        "content": "# MCP BatchIt 系统模式\\n\\n## 架构概述\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/techContext.md",
        "content": "# MCP BatchIt 技术上下文\\n\\n## 技术栈\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/progress.md",
        "content": "# MCP BatchIt 进度状态\\n\\n## 已完成的功能\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/activeContext.md",
        "content": "# MCP BatchIt 活动上下文\\n\\n## 当前状态\\n..."
      }
    }
  ],
  "options": {
    "maxConcurrent": 1,
    "stopOnError": true,
    "timeoutMs": 30000
  }
}

聚合器按顺序处理这些操作 (maxConcurrent=1)，创建目录并写入多个文档文件。结果数组指示每个操作的成功/失败状态。

常见问题解答

Q1：如果子操作 #2 依赖于子操作 #1 的结果，我是否需要多次聚合器调用？ 是的。 BatchIt 不在同一请求中的子操作之间传递数据。您进行多阶段调用（如上面的示例）。

Q2：为什么我有时会收到“找不到工具 create_directory”？ 因为您的 transport 可能指向聚合器脚本本身，而不是真正的 MCP 服务器。确保您引用类似 @modelcontextprotocol/server-filesystem 的内容。

Q3：我可以同时进行并发和 stopOnError 吗？ 当然可以。如果一个子操作失败，我们将跳过启动新的子操作。已经在运行的子操作将并行完成。

Q4：BatchIt 每次都会重新生成目标服务器吗？ 如果您指定 keepAlive: false，则可以。但是，如果您使用完全相同的 targetServer.name + transport，它会缓存连接，直到经过空闲超时。

Q5：如果在中间发生错误，是否会返回部分结果？ 是的。在错误发生之前完成的每个子操作都包含在最终的聚合器响应中，以及失败的子操作。如果 stopOnError 为 true，则跳过剩余的子操作。

许可证

MIT