MCP BatchIt

Agrupe múltiples llamadas de herramientas MCP en una única solicitud "batch_execute", lo que reduce la sobrecarga y el uso de tokens para los agentes de IA.

Tabla de contenido

1. Introducción

2. ¿Por qué usar BatchIt?

3. Características y limitaciones clave

4. Instalación y puesta en marcha

5. Uso multifásico

   • Fases de implementación

     • Recopilación de información

     • Paso solo para LLM (definiciones de códigos de lista)

     • Creación de documentos

6. Preguntas frecuentes

7. Licencia

Related MCP server: OpenAI-Compatible MCP Gateway

Introducción

⚠️ AVISO: Trabajo en progreso

Este proyecto se está desarrollando activamente para abordar varios desafíos complejos:

• Mantener la compatibilidad con versiones anteriores de los servidores MCP existentes

• Resolución de complejidades de transporte con clientes multiconexión (Cline, Roo, Claude Desktop)

• Creación de una implementación fácil de usar para principiantes

Si bien es funcional, se esperan mejoras y cambios constantes a medida que perfeccionamos la solución.

MCP BatchIt es un servidor agregador simple en el ecosistema del Protocolo de Contexto de Modelo (MCP) . Expone una sola herramienta: batch_execute . En lugar de llamar a varias herramientas MCP (como fetch , read_file , create_directory , write_file , etc.) en mensajes separados , puede procesarlas en una sola solicitud de agregador.

Esto reduce drásticamente el uso de tokens, la sobrecarga de la red y el contexto repetido en su agente de IA o conversación LLM.

¿Por qué usar BatchIt?

• Problema de una acción por mensaje : normalmente, un agente LLM o AI solo puede llamar a una única herramienta MCP a la vez, lo que obliga a realizar múltiples llamadas para tareas de varios pasos.

• Viajes de ida y vuelta excesivos : 10 operaciones de archivos independientes pueden requerir 10 mensajes → 10 respuestas.

• El enfoque de BatchIt :

  1. Toma una sola solicitud batch_execute .

  2. Genera (o se conecta a) el servidor MCP de destino real (como un servidor de sistema de archivos) detrás de escena.

  3. Ejecuta cada suboperación (llamada de herramienta) en paralelo hasta maxConcurrent .

  4. Si una suboperación falla y stopOnError es verdadero, detiene las nuevas suboperaciones.

  5. Devuelve un resultado JSON consolidado.

Características y limitaciones clave

Características

1. Herramienta única de "Ejecución por lotes"

   • Simplemente especifica una lista de suboperaciones que hagan referencia a las herramientas de tu servidor MCP existente.

2. Ejecución paralela

   • Ejecute múltiples suboperaciones a la vez, controladas por maxConcurrent .

3. Tiempo de espera y detención en caso de error

   • Cada suboperación tiene un timeoutMs y puedes omitir las operaciones restantes si una falla.

4. Almacenamiento en caché de conexión

   • Reutiliza la misma conexión con el servidor MCP descendente para llamadas repetidas y se cierra después de un tiempo de espera inactivo.

Limitaciones

1. No hay transferencia de datos a mitad del lote

   • Si la suboperación n.° 2 depende de la salida de n.° 1, realice múltiples llamadas al agregador.

2. No hay progreso parcial

   • Obtendrás los resultados de todas las suboperaciones juntos al final de cada “batch_execute”.

3. Debe utilizar un servidor MCP real

   • Si inicias o te conectas al agregador, verás el mensaje "herramienta no encontrada". El agregador solo tiene "batch_execute".

4. Un servidor de destino por llamada

   • Cada llamada al agregador hace referencia a un único servidor MCP de destino. Si desea varios servidores, deberá utilizar una lógica más avanzada o realizar llamadas independientes.

Instalación y puesta en marcha

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

BatchIt se inicia en STDIO por defecto para que tu agente de IA (o cualquier cliente MCP) pueda generarlo. Por ejemplo:

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

Ahora puedes enviarle solicitudes JSON-RPC ( tools/call , name= "batch_execute" ).

BANCO DE MEMORIA

Al utilizar Cline/Roo Code, puede crear un marco de documentación de proyecto contextual aprovechando las potentes instrucciones personalizadas "Memory Bank" desarrolladas por Nick Baumann.

Ver la documentación del banco de memoria

Enfoque tradicional (19+ llamadas):

1. Leer paquete.json

2. Esperar respuesta

3. Leer README.md

4. Esperar respuesta

5. Definiciones de códigos de lista

6. Esperar respuesta

7. Crear directorio de banco de memoria

8. Esperar respuesta

9. Escribe productContext.md

10. Escribe systemPatterns.md

11. Escribe techContext.md

12. Escribir progreso.md

13. Escribe activeContext.md

14. Esperar respuestas (5 llamadas más)

Total: ~19 llamadas API independientes (13 operaciones + 6 esperas de respuesta)

Enfoque BatchIt (1-3 llamadas)

Uso multifásico

Al trabajar con tareas complejas de varios pasos que dependen de la salida en tiempo real (como la lectura de archivos y la generación de documentación), deberá gestionar el proceso en fases distintas. Esto es necesario porque BatchIt no admite la transferencia de datos entre suboperaciones dentro de la misma solicitud.

Fases de implementación

Recopilación de información

En esta fase inicial, recopilamos información del sistema de archivos leyendo los archivos necesarios (p. ej., package.json , README.md ). Esto se logra mediante una llamada batch_execute al servidor MCP del sistema de archivos:

{
  "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
  }
}

Nota : El agregador genera @modelcontextprotocol/server-filesystem (a través de npx ) para ejecutar operaciones read_file paralelas.

Paso solo para LLM (definiciones de códigos de lista)

Esta fase implica el procesamiento fuera del agregador, generalmente utilizando capacidades de agente LLM o AI:

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

Este paso utiliza la herramienta list_code_definition_names de Roo Code, disponible exclusivamente para LLM. Sin embargo, tenga en cuenta que muchos servidores MCP ofrecen una funcionalidad similar, lo que permite completar este proceso sin solicitudes LLM.

Creación de documentos

La fase final combina datos de los pasos anteriores (contenido de archivos y definiciones de código) para generar documentación en el directorio 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 Product Context\\n\\n## Purpose\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/systemPatterns.md",
        "content": "# MCP BatchIt System Patterns\\n\\n## Architecture Overview\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/techContext.md",
        "content": "# MCP BatchIt Technical Context\\n\\n## Technology Stack\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/progress.md",
        "content": "# MCP BatchIt Progress Status\\n\\n## Completed Features\\n..."
      }
    },
    {
      "tool": "write_file",
      "arguments": {
        "path": "C:/Users/Chewy/Documents/GitHub/ryanjoachim/mcp-batchit/memory-bank/activeContext.md",
        "content": "# MCP BatchIt Active Context\\n\\n## Current Status\\n..."
      }
    }
  ],
  "options": {
    "maxConcurrent": 1,
    "stopOnError": true,
    "timeoutMs": 30000
  }
}

El agregador procesa estas operaciones secuencialmente ( maxConcurrent=1 ), creando el directorio y escribiendo múltiples archivos de documentación. La matriz de resultados indica el estado de éxito/fracaso de cada operación.

Preguntas frecuentes

P1: ¿Necesito varias llamadas al agregador si la suboperación n.º 2 depende de los resultados de la suboperación n.º 1? Sí. BatchIt no transfiere datos entre suboperaciones en la misma solicitud. Se realizan llamadas multifase (como en el ejemplo anterior).

P2: ¿Por qué a veces me aparece el mensaje "Herramienta create_directory no encontrada"? Porque tu transport podría estar apuntando al script del agregador en lugar del servidor MCP real. Asegúrate de hacer referencia a algo como @modelcontextprotocol/server-filesystem .

P3: ¿Puedo usar concurrencia y stopOnError? Por supuesto. Si una suboperación falla, omitimos el lanzamiento de nuevas suboperaciones. Las que ya se están ejecutando finalizan en paralelo.

P4: ¿BatchIt reinicia el servidor de destino cada vez? Puede hacerlo si se especifica keepAlive: false . Pero si se usa el mismo targetServer.name + transport , almacena en caché la conexión hasta que transcurra un tiempo de espera inactivo.

P5: ¿Se devuelven resultados parciales si se produce un error a mitad de proceso? Sí. Cada suboperación finalizada antes del error se incluye en la respuesta final del agregador, junto con la suboperación fallida. Las suboperaciones restantes se omiten si stopOnError es verdadero.

Licencia

Instituto Tecnológico de Massachusetts (MIT)