MCP Stdio 래퍼

MCP Stdio 래퍼는 하나의 MCP 클라이언트가 요청 시 다른 stdio MCP 서버를 실행하고 검사할 수 있게 해주는 작은 MCP 서버입니다.

이 도구의 역할은 고통스러운 MCP 개발 루프를 제거하는 것입니다. 일부 주류 MCP 호스트는 실제 서버 프로세스를 캐싱하므로, 코드 변경 후 변경 사항을 스모크 테스트하기 위해 매번 창을 새로 고치거나 확장 호스트를 다시 시작해야 합니다. 이 래퍼는 실제 대상 서버 앞에 위치하여 대상 구현이 계속 변경되는 동안 에이전트에게 반복적인 스모크 테스트를 위한 안정적인 가교를 제공합니다.

이 프로젝트가 존재하는 이유

다음과 같은 경우 이 프로젝트를 사용하세요:

• stdio MCP 서버를 활발히 개발 중인 경우

• 메인 MCP 호스트가 변경 후 대상 서버를 안정적으로 다시 로드하지 않는 경우

• 개발 전반에 걸쳐 에이전트가 도구를 나열하고, 도구를 호출하고, 리소스를 읽고, 프롬프트를 검사하기를 원하는 경우

이 프로젝트는 의도적으로 좁은 범위를 가집니다. 프로덕션 트래픽 프록시가 아닌 로컬 개발 및 스모크 테스트용입니다.

또한 래퍼는 에이전트가 직접 발견할 수 있는 내장 가이드를 노출합니다:

• 리소스: wrapper://how-to-use

• 프롬프트: tool_usage_guide

Related MCP server: Multi MCP

작동 방식

래퍼는 두 가지 모드를 노출합니다.

기본 일회성(one-shot) 도구:

• stdio_mcp_list_tools

• stdio_mcp_call_tool

• stdio_mcp_list_resources

• stdio_mcp_read_resource

• stdio_mcp_list_prompts

• stdio_mcp_get_prompt

각 일회성 브리지 호출은:

1. 대상 stdio MCP 서버를 실행합니다.

2. 하나의 MCP 작업을 수행합니다.

3. 결과를 반환합니다.

4. 대상 프로세스를 닫습니다.

선택적 세션 도구:

• stdio_mcp_open_session

• stdio_mcp_get_session

• stdio_mcp_close_session

• stdio_mcp_session_list_tools

• stdio_mcp_session_call_tool

• stdio_mcp_session_list_resources

• stdio_mcp_session_read_resource

• stdio_mcp_session_list_prompts

• stdio_mcp_session_get_prompt

즉:

• 일회성 스모크 테스트당 깨끗한 대상 프로세스

• 다단계 검증을 위한 명시적인 단기 세션 옵션

• 숨겨진 캐싱 동작 없음

• 실패 시 대상 stderr이 표시되므로 디버깅이 더 쉬움

빠른 시작

저장소를 복제하고 종속성을 설치하세요:

nvm use
npm install

래퍼를 시작하세요:

npm start

게시된 패키지는 다음을 사용하여 직접 실행할 수도 있습니다:

npx mcp-stdio-wrapper

패키지는 https://www.npmjs.com/package/mcp-stdio-wrapper에 게시되어 있습니다.

이 저장소는 GitHub Actions에서 npm 신뢰 게시(trusted publishing)를 위해 설정되었습니다. 초기 게시 순서 및 OIDC 신뢰 게시 핸드오프는 게시 체크리스트를 참조하세요.

메인 MCP 클라이언트를 이 래퍼로 지정한 다음, 다음과 같은 실행 입력을 사용하여 브리지 도구 중 하나를 사용하세요:

{
  "command": "node",
  "args": ["C:\\path\\to\\your-mcp\\dist\\index.js"],
  "cwd": "C:\\path\\to\\your-mcp",
  "inheritParentEnv": true,
  "env": {
    "EXAMPLE_ENV": "value"
  },
  "startupTimeoutMs": 30000,
  "operationTimeoutMs": 30000
}

그런 다음 에이전트에게 다음을 요청하세요:

• 실제 대상 서버에서 도구 나열

• 코드 변경 후 대상 도구 하나 호출

• 리소스 읽기 또는 프롬프트 확인

초기 검사 및 작은 상태 비저장 호출에는 일회성 모드를 사용하세요. 대상이 jobId 스타일 핸들을 반환하거나, 호출 간 메모리 내 상태를 기대하거나, 단순히 시작 비용이 많이 드는 경우, 먼저 명시적 세션을 열고 stdio_mcp_session_* 도구를 사용한 후 닫으세요.

도구 인터페이스

공통 실행 필드:

• command: 대상 실행 파일

• args: 대상 명령 인수

• cwd: 선택적 대상 작업 디렉터리

• inheritParentEnv: true인 경우, 래퍼 프로세스 환경을 대상 실행에 병합

• env: 추가 대상 환경 변수

• startupTimeoutMs: 선택적 일회성 시작 및 MCP 초기화 시간 제한

• operationTimeoutMs: 선택적 일회성 작업 시간 제한

• timeoutMs: 두 단계 모두에 대한 레거시 일회성 바로가기; 세션 도구는 여전히 timeoutMs를 사용함

브리지 작업:

• stdio_mcp_list_tools: 대상 도구 검사

• stdio_mcp_call_tool: 대상 도구 하나 호출

• stdio_mcp_list_resources: 대상 리소스 검사

• stdio_mcp_read_resource: 대상 리소스 하나 읽기

• stdio_mcp_list_prompts: 대상 프롬프트 검사

• stdio_mcp_get_prompt: 대상 프롬프트 정의 하나 가져오기

세션 작업:

• stdio_mcp_open_session: 대상 프로세스 하나를 실행하고 여러 작업을 위해 유지

• stdio_mcp_get_session: 상태, 타임스탬프, pid, 종료 코드 및 stderr 꼬리와 같은 세션 진단 검사

• stdio_mcp_close_session: 라이브 또는 터미널 세션을 닫고 기록 제거

• stdio_mcp_session_list_tools: 기존 세션을 통해 도구 검사

• stdio_mcp_session_call_tool: 기존 세션을 통해 대상 도구 하나 호출

• stdio_mcp_session_list_resources: 기존 세션을 통해 리소스 검사

• stdio_mcp_session_read_resource: 기존 세션을 통해 대상 리소스 하나 읽기

• stdio_mcp_session_list_prompts: 기존 세션을 통해 프롬프트 검사

• stdio_mcp_session_get_prompt: 기존 세션을 통해 대상 프롬프트 정의 하나 가져오기

래퍼 가이드 표면:

• wrapper://how-to-use: 일반 텍스트 사용 가이드

• tool_usage_guide: 동일한 지침의 프롬프트 형식

세션 모드는 다음과 같은 경우에 더 적합합니다:

• 대상이 jobId와 같은 지연된 핸들을 반환하는 경우

• 후속 호출이 동일한 라이브 대상 프로세스에 도달해야 하는 경우

• 대상 시작 비용이 너무 커서 반복하면 실제 피드백 루프가 가려지는 경우

안전 참고 사항

• 이 래퍼는 호출자가 제공한 임의의 명령을 실행합니다.

• 실행 인수와 환경 변수를 민감하게 취급하세요.

• 신뢰할 수 있는 대상 명령 및 신뢰할 수 있는 로컬 프로젝트에서만 사용하세요.

• 이를 공개 다중 테넌트 서비스로 노출하지 마세요.

문서

• 설정 가이드

• 도구 참조

• 문제 해결

• 브랜치 전략

• 유지 관리자 가이드

• 게시 체크리스트

• 퍼징 워크플로

• 보안 정책

• 기여

• 변경 로그

스타 기록