mcp-portal

mcp-portal

mcp-portal 是一个基于 stdio 的 Model Context Protocol 服务，可让前沿 Agent（Claude Code、Codex、Cursor 或任何 MCP 主机）将两项任务委托给使用自身配额的 Cursor CLI：有界的 bulk_read（读取明确选定的文件，并使用经验证的引文作答）和 code_write（根据参考文件和规范生成样板代码；由服务写入目标文件）。仅使用 Python 标准库——无需 Node 运行时，也不依赖 MCP SDK。

2026-09-08，composer-2.5-fast 在相同任务说明下的生成速度约为前沿模型的 5 倍（按行速率测量）。Cursor 配额与主机模型的配额分开计算。

快速开始

uvx mcp-portal

也可通过 pipx install mcp-portal / pip install mcp-portal 安装，并已列入 MCP Registry，名称为 io.github.apollion69/mcp-portal。 如需运行开发版而非正式发布版：

uvx --from git+https://github.com/apollion69/mcp-portal mcp-portal

要求：Python 3.10+，已安装并登录的 Cursor CLI（cursor-agent）。

Doctor（检查 CLI 清单，不调用模型）：

mcp-portal-doctor

按主机配置

Claude Code

claude mcp add --scope user mcp-portal -- uvx mcp-portal

Codex（~/.codex/config.toml）

[mcp_servers.mcp-portal]
command = "uvx"
args = ["mcp-portal"]
tool_timeout_sec = 150

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "mcp-portal": {
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

VS Code（.vscode/mcp.json，servers 键）

{
  "servers": {
    "mcp-portal": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

通用 mcpServers JSON

{
  "mcpServers": {
    "mcp-portal": {
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

环境变量（可选）：

变量	用途
MCP_PORTAL_HOME	缓存、回执、证据（默认值：~/.cache/mcp-portal）
MCP_PORTAL_CLI	cursor-agent / agent 的路径

工具

bulk_read

参数	必填	说明
paths	是	1–16 个文件路径（相对于 root 或绝对路径）
question	是	仅根据这些文件回答的问题
root	否	公共根目录；默认值 = paths 的最长公共父目录
model	否	覆盖模型；未指定时应用策略

返回 status、run_id、answer.findings[]（file、start、end、quote、fact）、gaps[]、metrics、model_decision。

code_write

参数	必填	说明
spec	是	要生成的内容
reference_path	是	风格/上下文参考文件
target_path	否	如果设置，服务会写入此路径
model	否	覆盖模型

返回生成的 code、可选的 bytes_written、run_id、metrics。

status

无参数。返回 CLI 路径、身份验证提示、默认模型、策略摘要、缓存位置和回执计数。

模型策略

随包附带于 model-policy.json（包数据）。默认设置：

• 优先使用 Cursor 原生模型（composer-2.5，然后是 cursor-grok-*）
• 移除 -fast 后缀（绝不自动选择 fast 变体）
• 仅在明确请求且列于 cursor-agent --list-models 时使用其他供应商的模型

如需覆盖，可编辑已安装包中的 model-policy.json，或通过 MCP_PORTAL_HOME 下的自定义文件设置策略字段（未来支持）——目前，请替换包文件，或在你的 fork 中修改 preferred。每个工具结果都包含 model_decision.reason（default_preferred、fast_suffix_stripped、cursor_native_explicit、explicit_other_vendor、requested_unavailable_fallback）。

工作原理

1. 授权 — 服务仅读取列出的路径；屏蔽类似凭据的路径和机密模式。
2. 清单 — 请求 JSON 包含每个文件的 SHA-256 哈希值。
3. 隔离 — Cursor CLI 在全新的 CURSOR_CONFIG_DIR 中运行，采用拒绝所有权限、--mode ask，并启用沙盒。
4. 验证 — bulk_read 答复中的每个 quote 都必须原样出现在引用的行范围内；无效引用会被丢弃或直接拒绝。
5. 证据 — 每次运行的目录位于 MCP_PORTAL_HOME/runs/<run_id>/，其中包含清单（哈希值、指标；不含完整源代码）。
6. 预算 — 16 个文件、合计输入 128 KiB、超时 90s、标准输入输出帧大小受限。

Windows

在 Windows 上，满足以下任一条件时，委托程序会在本地运行 Cursor CLI：

• MCP_PORTAL_CLI 指向一个可执行文件（包括测试桩），或
• 可在 PATH 中找到 cursor-agent / agent，且它是一个真实文件。

否则会回退到通过 wsl.exe 桥接运行 Ubuntu/WSL（python3 -m mcp_portal.delegate --worker）。使用 MCP_PORTAL_BACKEND=local 或 MCP_PORTAL_BACKEND=wsl 强制指定任一模式。

• 如果 CLI 在 PATH 中，MCP 配置可以使用原生 uvx mcp-portal；否则可使用 wsl.exe + uvx mcp-portal
• clients/windows/ 中的辅助脚本（delegate.ps1、parse_read.ps1）
• MCP_PORTAL_WORKER 可覆盖默认的 WSL 工作进程命令
• MCP_PORTAL_WSL_CD 用于设置 WSL 工作目录（默认值为 ~）

可选的 Claude Code 路由钩子

安装读取门禁 + 技能（通用、事务式）：

python3 -m mcp_portal.install_router prepare --client claude --python python3 \
  --state-root ~/.cache/mcp-portal/router-tx --shell bash --command-shell bash
# then apply with the printed transaction id

Agent 使用指南请参见 docs/skills/cursor-bulk-reader/SKILL.md。路由器会阻止或警告大型完整文件读取（>350 行或 >128 KiB），并引导 Agent 使用 bulk_read。

仓库级 MCP 注册辅助工具：

python3 -m mcp_portal.install plan
python3 -m mcp_portal.install apply --target claude-mcp

安全

请参见 SECURITY.md。概要：由你选择哪些文件离开本机；CLI 以只读模式运行，且工具被禁用；引用由服务端验证。不能替代良好的机密信息管理。

相关项目

有多个基于 Node 的桥接工具通过 MCP 提供 Cursor（权衡各不相同：SDK/Node 技术栈、隔离和验证机制各异）：

• lipey1/cursor-agent-mcp
• andreilungeanu/cursor-delegate-mcp
• sailay1996/cursor-agent-mcp
• ai-nuke/cursor-agent-mcp
• JaimeJunr/cursor-mcp-bridge

mcp-portal 专注于标准库 Python、哈希固定的清单、引用验证、code_write 的服务端写入、模型策略，以及优先支持 WSL 的 Windows 支持。

许可证

MIT — 请参见 LICENSE。