여러 개의 MCP 도구 호출을 단일 "batch_execute" 요청으로 배치 처리하여, AI 에이전트의 오버헤드와 토큰 사용량을 줄입니다.

• 서론 (Introduction)
• BatchIt를 사용하는 이유 (Why Use BatchIt)
• 주요 기능 및 제한 사항 (Key Features & Limitations)
• 설치 및 시작하기 (Installation & Startup)
• 다단계 사용법 (Multi-Phase Usage)
• 자주 묻는 질문 (FAQ)
• 라이선스 (License)

⚠️ 공지: 개발 진행 중 (Work in Progress) 이 프로젝트는 다음과 같은 몇 가지 복잡한 과제들을 해결하기 위해 활발히 개발되고 있습니다:

• 기존 MCP 서버와의 하위 호환성 (backwards compatibility) 유지
• 멀티 커넥션 클라이언트 (Cline, Roo, Claude Desktop)와의 전송 복잡성 (transport complexities) 해결
• 초보자 친화적인 구현 (beginner-friendly implementation) 생성
  기능적으로 작동하지만, 솔루션을 정교화함에 따라 지속적인 개선과 변경이 있을 수 있습니다.

MCP BatchIt는 Model Context Protocol (MCP) 생태계 내의 간단한 애그리게이터 (aggregator) 서버입니다. 이 서버는 단 하나의 도구인 batch_execute만을 노출합니다. fetch, read_file, create_directory, write_file 등과 같은 여러 MCP 도구를 별도의 메시지로 호출하는 대신, 하나의 애그리게이터 요청으로 이들을 배치 (batch) 처리할 수 있습니다.

이를 통해 AI 에이전트 또는 LLM 대화에서의 토큰 사용량, 네트워크 오버헤드, 반복되는 컨텍스트를 획기적으로 줄일 수 있습니다.

메시지당 단일 작업 (One Action per Message) 문제: 일반적으로 LLM 또는 AI 에이전트는 한 번에 하나의 MCP 도구만 호출할 수 있어, 다단계 작업을 수행할 때 여러 번의 호출이 강제됩니다. -
과도한 왕복 (Excessive Round Trips): 10개의 별도 파일 작업은 10개의 메시지와 10개의 응답을 필요로 할 수 있습니다. -
BatchIt의 접근 방식:

• 단일 batch_execute 요청을 받습니다. -

• 백그라운드에서 실제 대상 MCP 서버 (파일 시스템 서버 등)를 생성하거나 연결합니다.

• 각 하위 작업 (sub-operation, 도구 호출)을 maxConcurrent 설정값까지 병렬로 실행합니다. -

• 만약 하나의 하위 작업이 실패하고 stopOnError가 true인 경우, 새로운 하위 작업을 중단합니다. -

• 하나의 통합된 JSON 결과를 반환합니다.

단일 “Batch Execute” 도구 (Single “Batch Execute” Tool)

• 기존 MCP 서버의 도구를 참조하는 하위 작업 목록을 지정하기만 하면 됩니다.

병렬 실행 (Parallel Execution)

• maxConcurrent에 의해 제어되는 여러 하위 작업을 동시에 실행합니다.

• maxConcurrent에 의해 제어되는 여러 하위 작업을 동시에 실행합니다.

타임아웃 및 오류 시 중단 (Timeout & Stop on Error)

• 각 하위 작업은 timeoutMs와 경쟁하며, 하나의 작업이 실패하면 나머지 작업을 건너뛸 수 있습니다.

연결 캐싱 (Connection Caching)

• 반복되는 호출에 대해 다운스트림 MCP 서버로의 동일한 연결을 재사용하며, 유휴 타임아웃(idle timeout) 이후에 종료합니다.

배치 중간 데이터 전달 불가 (No Data Passing Mid-Batch)

• 만약 하위 작업 #2가 #1의 출력에 의존한다면, 여러 번의 어그리게이터 (aggregator) 호출을 수행하십시오.

부분적 진행 불가 (No Partial Progress)

• 각 "batch_execute"의 끝에서 모든 하위 작업의 결과를 한꺼번에 받게 됩니다.

실제 MCP 서버 사용 필수 (Must Use a Real MCP Server)

• 만약 어그리게이터 자체를 생성하거나 연결하려고 하면 "tool not found" 오류가 발생합니다. 어그리게이터는 "batch_execute" 기능만 가지고 있습니다.

호출당 하나의 대상 서버 (One Target Server per Call)

• 각 어그리게이터 호출은 단일 대상 MCP 서버를 참조합니다. 여러 서버를 사용하려면 더 고급 로직을 구현하거나 별도의 호출을 수행해야 합니다.

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

BatchIt은 기본적으로 STDIO에서 시작하므로 AI 에이전트(또는 모든 MCP 클라이언트)가 이를 생성할 수 있습니다. 예시:

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

이제 어그리게이터에 JSON-RPC 요청 (tools/call 메서드, name= "batch_execute")을 보낼 수 있습니다.

Cline/Roo Code를 사용하면 Nick Baumann가 개발한 강력한 "Memory Bank" 커스텀 지침을 활용하여 문맥적 프로젝트 문서화 프레임워크를 구축할 수 있습니다.

• package.json 읽기
• 응답 대기
• README.md 읽기
• 응답 대기
• 코드 정의 목록화
• 응답 대기
• memory-bank 디렉토리 생성
• 응답 대기
• productContext.md 작성
• systemPatterns.md 작성
• techContext.md 작성
• progress.md 작성
• activeContext.md 작성
• 응답 대기 (5번의 추가 호출)

총합: 약 19개의 개별 API 호출 (13개의 작업 + 6번의 응답 대기)

실시간 출력(파일 읽기 및 문서 생성 등)에 의존하는 복잡한 다단계 작업(multi-step tasks)을 수행할 때는 프로세스를 별도의 단계(phases)로 나누어 처리해야 합니다. 이는 BatchIt이 동일한 요청 내의 하위 작업(sub-operations) 간 데이터 전달을 지원하지 않기 때문에 필요합니다.

이 초기 단계에서는 필요한 파일(예: package.json, README.md)을 읽음으로써 파일 시스템으로부터 정보를 수집합니다. 이는 파일 시스템 MCP 서버에 대한 batch_execute 호출을 통해 수행됩니다:

{
"targetServer": {
"name": "filesystem",
...

참고: 어그리게이터(aggregator)는 병렬 read_file 작업을 실행하기 위해 (npx를 통해) @modelcontextprotocol/server-filesystem을 실행합니다.

이 단계는 어그리게이터 외부에서 처리되며, 일반적으로 LLM 또는 AI 에이전트의 기능을 사용합니다:

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

이 단계는 LLM만 독점적으로 사용할 수 있는 Roo Code의 list_code_definition_names 도구를 활용합니다. 하지만 많은 MCP 서버가 유사한 기능을 제공할 수 있으므로, LLM 요청 없이도 이 프로세스를 완료하는 것이 가능합니다.

마지막 단계는 이전 단계의 데이터(파일 내용 및 코드 정의)를 결합하여 memory-bank 디렉토리에 문서를 생성합니다:

{
"targetServer": {
"name": "filesystem",
...

어그리게이터는 이러한 작업들을 순차적으로(maxConcurrent=1) 처리하여, 디렉토리를 생성하고 여러 문서 파일을 작성합니다. 결과 배열(result array)은 각 작업의 성공/실패 상태를 나타냅니다.

Q1: 하위 작업 #2가 하위 작업 #1의 결과에 의존한다면, 어그리게이터를 여러 번 호출해야 하나요?
네. BatchIt은 동일한 요청 내의 하위 작업 간에 데이터를 전달하지 않습니다. 위 예시와 같이 다단계(multi-phase) 호출을 수행해야 합니다.

Q2: 왜 가끔 “Tool create_directory not found”라는 오류가 발생하나요?
귀하의 transport 때문입니다.

실제 MCP 서버 대신 aggregator 스크립트 자체를 가리키고 있을 수 있습니다. @modelcontextprotocol/server-filesystem과 같은 것을 참조하고 있는지 확인하세요.

Q3: 동시성 (Concurrency)과 stopOnError을 함께 사용할 수 있나요?
물론입니다. 하위 작업 (sub-op) 하나가 실패하면, 새로운 하위 작업을 실행하는 것을 건너뜁니다. 이미 실행 중인 작업들은 병렬로 완료됩니다.

Q4: BatchIt는 매번 대상 서버를 다시 실행하나요?
keepAlive: false를 지정하면 그럴 수 있습니다. 하지만 정확히 동일한 targetServer.name + transport를 사용한다면, 유휴 시간 제한 (idle timeout)이 지날 때까지 연결을 캐싱(caching)합니다.

Q5: 중간에 오류가 발생하면 부분적인 결과가 반환되나요?
네. 오류 발생 전에 완료된 각 하위 작업은 실패한 하위 작업과 함께 최종 aggregator 응답에 포함됩니다. stopOnError가 true인 경우 나머지 하위 작업들은 건너뜁니다.

MIT