Envoltorio Stdio para MCP

MCP Stdio Wrapper es un pequeño servidor MCP que permite a un cliente MCP iniciar e inspeccionar otro servidor MCP stdio bajo demanda.

Su función es eliminar un ciclo de desarrollo MCP tedioso: algunos hosts MCP convencionales almacenan en caché el proceso del servidor real, por lo que después de cada cambio de código terminas actualizando la ventana o reiniciando el host de la extensión solo para realizar pruebas de humo del cambio. Este envoltorio se sitúa frente al servidor de destino real y le da a tu agente un puente estable para pruebas de humo repetidas mientras la implementación de destino sigue cambiando debajo de él.

Por qué existe esto

Utiliza este proyecto cuando:

• estés desarrollando activamente un servidor MCP stdio

• tu host MCP principal no recargue de forma fiable el servidor de destino después de cada cambio

• aún desees que un agente liste herramientas, llame a herramientas, lea recursos e inspeccione prompts durante el desarrollo

Este proyecto es intencionalmente limitado. Es para desarrollo local y pruebas de humo, no para el proxy de tráfico de producción.

El envoltorio también expone una guía integrada que los agentes pueden descubrir directamente:

• recurso: wrapper://how-to-use

• prompt: tool_usage_guide

Related MCP server: Multi MCP

Cómo funciona

El envoltorio expone dos modos.

Herramientas de un solo uso (one-shot) predeterminadas:

• stdio_mcp_list_tools

• stdio_mcp_call_tool

• stdio_mcp_list_resources

• stdio_mcp_read_resource

• stdio_mcp_list_prompts

• stdio_mcp_get_prompt

Cada llamada de puente de un solo uso:

1. inicia el servidor MCP stdio de destino

2. realiza una operación MCP

3. devuelve el resultado

4. cierra el proceso de destino

Herramientas de sesión opcionales:

• 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

Esto significa:

• un proceso de destino limpio por cada prueba de humo de un solo uso

• una opción de sesión explícita de corta duración para validación de varios pasos

• sin comportamiento de caché oculto

• depuración más sencilla porque el stderr del destino se muestra en caso de error

Inicio rápido

Clona el repositorio e instala las dependencias:

nvm use
npm install

Inicia el envoltorio:

npm start

El paquete publicado también se puede ejecutar directamente con:

npx mcp-stdio-wrapper

El paquete está publicado en https://www.npmjs.com/package/mcp-stdio-wrapper.

Este repositorio está configurado para la publicación confiable de npm desde GitHub Actions. Consulta la Lista de verificación de publicación para la secuencia de publicación inicial y el traspaso de publicación confiable OIDC.

Apunta tu cliente MCP principal a este envoltorio, luego usa una de las herramientas de puente con una entrada de inicio como:

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

Luego pídele a tu agente que:

• liste las herramientas del servidor de destino real

• llame a una herramienta de destino después de cada cambio de código

• verifique las lecturas de recursos o los prompts

Usa el modo de un solo uso para la inspección inicial y llamadas pequeñas sin estado. Si el destino devuelve identificadores de estilo jobId, espera un estado en memoria entre llamadas o simplemente tiene un inicio costoso, abre una sesión explícita primero y luego usa las herramientas stdio_mcp_session_* antes de cerrarla.

Superficie de herramientas

Campos de inicio comunes:

• command: ejecutable de destino

• args: argumentos del comando de destino

• cwd: directorio de trabajo de destino opcional

• inheritParentEnv: cuando es true, fusiona el entorno del proceso del envoltorio en el inicio del destino

• env: variables de entorno de destino adicionales

• startupTimeoutMs: tiempo de espera opcional de inicio e inicialización MCP de un solo uso

• operationTimeoutMs: tiempo de espera opcional de operación de un solo uso

• timeoutMs: atajo heredado de un solo uso para ambas fases; las herramientas de sesión aún usan timeoutMs

Operaciones de puente:

• stdio_mcp_list_tools: inspeccionar herramientas de destino

• stdio_mcp_call_tool: llamar a una herramienta de destino

• stdio_mcp_list_resources: inspeccionar recursos de destino

• stdio_mcp_read_resource: leer un recurso de destino

• stdio_mcp_list_prompts: inspeccionar prompts de destino

• stdio_mcp_get_prompt: obtener una definición de prompt de destino

Operaciones de sesión:

• stdio_mcp_open_session: iniciar un proceso de destino y mantenerlo activo para múltiples operaciones

• stdio_mcp_get_session: inspeccionar diagnósticos de sesión como estado, marcas de tiempo, pid, código de salida y cola de stderr

• stdio_mcp_close_session: cerrar una sesión activa o terminal y eliminar su registro

• stdio_mcp_session_list_tools: inspeccionar herramientas a través de una sesión existente

• stdio_mcp_session_call_tool: llamar a una herramienta de destino a través de una sesión existente

• stdio_mcp_session_list_resources: inspeccionar recursos a través de una sesión existente

• stdio_mcp_session_read_resource: leer un recurso de destino a través de una sesión existente

• stdio_mcp_session_list_prompts: inspeccionar prompts a través de una sesión existente

• stdio_mcp_session_get_prompt: obtener una definición de prompt de destino a través de una sesión existente

Superficies de guía del envoltorio:

• wrapper://how-to-use: guía de uso en texto plano

• tool_usage_guide: forma de prompt de las mismas instrucciones

El modo de sesión es la mejor opción cuando:

• el destino devuelve identificadores diferidos como jobId

• las llamadas de seguimiento deben llegar al mismo proceso de destino activo

• el inicio del destino es lo suficientemente costoso como para que repetirlo oscurezca el ciclo de retroalimentación real

Notas de seguridad

• Este envoltorio inicia comandos arbitrarios proporcionados por el llamador.

• Trata los argumentos de inicio y las variables de entorno como confidenciales.

• Úsalo solo con comandos de destino confiables y proyectos locales confiables.

• No expongas esto como un servicio público multiinquilino.

Documentación

• Guía de configuración

• Referencia de herramientas

• Solución de problemas

• Estrategia de ramificación

• Guía del mantenedor

• Lista de verificación de publicación

• Flujo de trabajo de fuzzing

• Política de seguridad

• Contribución

• Registro de cambios

Historial de estrellas