MCP Stdio Wrapper

MCP Stdio Wrapper 是一个小型 MCP 服务器，允许一个 MCP 客户端按需启动并检查另一个 stdio MCP 服务器。

它的作用是消除痛苦的 MCP 开发循环：一些主流 MCP 主机缓存了真实的服务器进程，因此每次代码更改后，你最终都需要刷新窗口或重启扩展主机，仅仅是为了对更改进行冒烟测试。此包装器位于真实目标服务器的前面，为你的代理提供了一个稳定的桥梁，以便在目标实现不断变化的同时进行重复的冒烟测试。

为什么存在这个项目

在以下情况下使用此项目：

• 你正在积极开发一个 stdio MCP 服务器

• 你的主 MCP 主机在每次更改后不能可靠地重新加载目标服务器

• 你仍然希望代理在开发过程中列出工具、调用工具、读取资源并检查提示词

此项目是有意设计的，范围较窄。它仅用于本地开发和冒烟测试，不用于生产流量代理。

该包装器还公开了代理可以直接发现的内置指南：

• 资源：wrapper://how-to-use

• 提示词：tool_usage_guide

Related MCP server: Multi MCP

工作原理

该包装器公开了两种模式。

默认的一次性工具：

• 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 可信发布。请参阅 发布清单 以了解初始发布序列和 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

• 后续调用必须命中同一个活动的实时目标进程

• 目标启动成本很高，以至于重复启动会掩盖真实的反馈循环

安全说明

• 此包装器启动由调用者提供的任意命令。

• 将启动参数和环境变量视为敏感信息。

• 仅将其与受信任的目标命令和受信任的本地项目一起使用。

• 不要将其公开为公共多租户服务。

文档

• 设置指南

• 工具参考

• 故障排除

• 分支策略

• 维护者指南

• 发布清单

• 模糊测试工作流

• 安全策略

• 贡献

• 更新日志

星标历史