Mcporter Bridge

麦克波特大桥

暴露你的本地 MCPorter 注册表作为一个稳定的MCP服务器，用于编码客户端。

mcporter-bridge 是一个小型的FastMCP服务器，可以将您现有的 mcporter 为Codex、Claude Code、Cline和Cursor等客户端设置一个可重用的入口点。

为什么

如果你使用多个编码客户端，你的MCP设置通常会很快分裂：

• Codex有一种配置格式
• 克劳德代码还有另一个
• Cline和Cursor添加自己的
• mcporter 已经知道您的真实服务器注册表、身份验证状态和运行时

mcporter-bridge 保持 mcporter 作为事实的来源，它为客户端提供了一个稳定的MCP服务器，而不是另一堆重复的配置。

它的作用

• 阅读您的本地 mcporter 运行时注册表
• 列出已配置的MCP服务器及其运行状况
• 检查特定服务器及其工具模式
• 通过调用任何已配置服务器上的任何工具 mcporter
• 延迟加载：按需激活/停用重型MCP以保存上下文
• 可选地暴露本地 agent-reach 诊断作为辅助工具

这不是传输代理，也不是企业网关。它是客户集成的本地第一桥梁。

工具

核心工具

Lazy Loading Tools (按需加载)

实用工具

所有工具返回结构化输出，包括：

• ok
• timed_out
• command
• timeout_ms
• returncode
• stdout
• stderr
• parsed_json

安装

点

pip install mcporter-bridge

pipx

pipx install mcporter-bridge

安装后，您将收到两个命令：

• mcporter-bridge 运行MCP服务器
• mcporter-bridge-config 生成或安装客户端代码段

本地开发

git clone https://github.com/Citrus086/mcporter-bridge.git
cd mcporter-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

需求

• mcporter 已安装并可用于 PATH
• 本地至少有一个已配置的MCP服务器 mcporter 注册表

可选：

快速检查

mcporter-bridge

在另一个shell中：

mcporter list --stdio "python3 -m mcporter_bridge" --json

客户端设置

现成的模板已上线 示例/.

法典

将此添加到 ~/.codex/config.toml:

[mcp_servers.mcporter-bridge]
type = "stdio"
command = "python3"
args = ["-m", "mcporter_bridge"]
startup_timeout_ms = 30000

或者自动安装：

mcporter-bridge-config install --client codex

笔记：

• OpenAI的文档证实，Codex从 ~/.codex/config.toml 使用 mcp_servers. MCP服务器的结构。
• 这里的stdio表单也会在本地进行验证 codex mcp add --help，接受 codex mcp add -- 用于stdio服务器。

克劳德代码/克劳德桌面

将此添加到您的MCP配置中：

{
  "mcpServers": {
    "mcporter-bridge": {
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

使用默认值自动安装 ~/.claude.json 路径：

mcporter-bridge-config install --client claude

笔记：

• Anthropic的Claude Code文档证实，用户范围的MCP服务器位于 ~/.claude.json.
• 相同的文档显示了存储在中的项目范围的服务器 .mcp.json 在项目的根。
• 文档中的JSON形状使用 mcpServers 和 command, args，以及 env 用于stdio服务器。

克莱恩

使用相同的stdio形状：

{
  "mcpServers": {
    "mcporter-bridge": {
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

生成代码段：

mcporter-bridge-config snippet --client cline

写入显式配置路径：

mcporter-bridge-config install --client cline --config-path /path/to/mcp.json

笔记：

• Cline的文档确认MCP设置存储在 cline_mcp_settings.json.
• 对于本地stdio服务器，记录的JSON形状使用 mcpServers 和 command, args, env, alwaysAllow，以及 disabled.
• Cline的文档使用 type 用于远程传输配置，例如 streamableHttp，但在本地stdio示例中没有，因此网桥不会发出 type 为了克莱恩。

光标

光标使用 mcp.json 和 mcpServers，对于stdio服务器，网桥会发出 type: "stdio" 明确地。

全局配置示例：

{
  "mcpServers": {
    "mcporter-bridge": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

安装到默认全局路径：

mcporter-bridge-config install --client cursor

或者写入显式配置路径：

mcporter-bridge-config install --client cursor --config-path /path/to/mcp.json

配置助手

打印片段：

mcporter-bridge-config snippet --client codex

自定义启动器：

mcporter-bridge-config snippet \
  --client claude \
  --python-command /opt/homebrew/bin/python3.13 \
  --module-name mcporter_bridge

直接安装到配置文件中：

mcporter-bridge-config install --client codex
mcporter-bridge-config install --client claude

更新现有配置文件时，助手会使用 .bak 后缀优先。

示例提示

• "列出所有可用的 MCP 服务器"
• "查看 xiaohongshu 服务器的工具"
• "调用 xiaohongshu 的 check_login_status"
• "激活 playwright 浏览器工具"
• "查看 xiaohongshu 的原始工具定义（raw=true）"

Lazy Loading (按需加载)

大型 MCP 如 chrome-devtools (29 tools) 或 playwright (22 tools) 会消耗大量上下文。默认保持未加载状态，需要时再激活。

MCP 类型

• 小 - 小型 MCP，通常已加载，可直接使用
• 重 - 大型 MCP，默认未加载，需先激活

设置

1. 创建 heavy MCP 目录：

mkdir -p ~/.mcporter/heavy/available

1. 将大型 MCP 从 mcporter.json 移到单独文件：

# 示例：将 playwright 移到 heavy
echo '{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "description": "浏览器自动化",
      "tags": ["浏览器"]
    }
  }
}' > ~/.mcporter/heavy/available/playwright.json

1. 从主 mcporter.json 中移除该 MCP。

工作流程

1. mcporter_list_servers()
   ↓ 返回 active（已加载）和 available（可激活）两个列表
   ↓ 需要的 MCP 在 available 中？
2. mcporter_activate_mcp(name="playwright")
   ↓
3. mcporter_list_servers()  # 确认已出现在 active 列表
   ↓
4. 使用 playwright 工具...
   ↓
5. mcporter_deactivate_mcp(name="playwright")  # 用完即释放

这让上游 LLM 能够自我管理上下文，按需加载/卸载大型 MCP。

Server Descriptions (服务器描述)

mcporter-bridge 会为每个 MCP 服务器提供功能描述，帮助 LLM 了解每个服务是干什么的。

描述来源（优先级从高到低）

1. 用户配置 - 在 ~/.mcporter/mcporter.json 中添加
2. 内置映射 - 常见 MCP 的预设描述
3. 名字推断 - 从服务器名称猜测功能

在 mcporter.json 中配置描述

{
  "mcpServers": {
    "my-custom-mcp": {
      "command": "...",
      "args": [...],
      "description": "自定义 MCP 的功能描述",
      "tags": ["标签1", "标签2"],
      "best_for": "最适合的使用场景"
    }
  }
}

内置描述的常见 MCP

名字推断规则

如果服务器不在内置列表中，会从名称推断：

• 包含 search → 搜索相关
• 包含 browser / chrome → 浏览器相关
• 包含 github / git → 代码仓库相关
• 包含 xiaohongshu → 小红书相关
• ...

环境变量

• MCPORTER_BRIDGE_MCPORTER_BIN：覆盖 mcporter 二进制路径
• MCPORTER_BRIDGE_MAX_OUTPUT_CHARS：cap捕获stdout/stderr长度

Troubleshooting / 一个跨三层的隐蔽 bug

如果你在 macOS + Anaconda Python 环境下遇到 ModuleNotFoundError: No module named mcporter_bridge，或者 Claude 一直报 Failed to reconnect，问题可能来自一个跨三层的隐蔽 bug：

pip 写入 .pth 文件
    ↓
macOS 自动给该文件打上 UF_HIDDEN flag（因为父目录 .venv 被标记为隐藏）
    ↓
Anaconda Python 的 site.py 读取 .pth 时，检测到 UF_HIDDEN 就直接跳过
    ↓
Editable install 失效，import mcporter_bridge 失败

这会导致 python3 -m mcporter_bridge 直接起不来进程，Claude 等 MCP 客户端自然无法重连。

我们已经做的修复

• __main__.py 里加了 引导回退：如果模块加载失败，会自动探测 src/ 目录并注入 sys.path。
• mcporter-bridge-config 在生成客户端配置时，自动检测 editable install 并写入 PYTHONPATH，同时写入 FASTMCP_SHOW_SERVER_BANNER=false 保证 stdio 干净。
• show_banner=False：确保 FastMCP 的启动 banner 不会污染 stdio 的 JSON-RPC 输出。

临时 workaround

如果你不想重新安装，可以手动去掉 hidden flag：

chflags nohidden /path/to/your/.venv/lib/python3.12/site-packages/_mcporter_bridge.pth

或者直接给 Claude/Codex 等客户端的 env 加上：

"env": {
  "PYTHONPATH": "/absolute/path/to/mcporter-bridge/src",
  "FASTMCP_SHOW_SERVER_BANNER": "false"
}

这个 bug 的诡异之处在于：pip、macOS、Python 三层单独看都没错，但串在一起就把 editable install 干掉了。更让人意外的是，我们项目的 build backend hatchling 目前并不支持 symlink editable mode，所以即使想绕过 .pth 文件也做不到——它只能生成 .pth 文件。目前 Python 和 macOS 官方 issue tracker 里似乎还没有人专门报告这一现象。

路线图

• 通用MCP的高级便利工具
• 可选工具allolists/denylists
• 更多特定于客户端的路径发现
• 更丰富的身份验证和诊断助手

许可证

麻省理工学院