@zhishu_qfei/mcp-contract

QFEI 合同 MCP 的本地 stdio bridge 与安装器。目标是把 QFEI 远程 MCP 的 OAuth 2.1、动态客户端注册、PKCE、loopback callback 和 token 缓存都收敛在包内部，客户端统一只连本地 npx 命令。

为什么不用远程 OAuth 直连

• QFEI 当前远程 MCP 接入链路要求客户端自己处理 OAuth 2.1 发现、客户端注册、PKCE、浏览器回调与 token 兑换。
• Cursor、Claude Code、Codex 对远程 MCP/OAuth 的支持路径不完全一致，用户侧接入摩擦高。
• 本包把远程 MCP 变成本地 stdio MCP：
  • 客户端统一接 npx -y @zhishu_qfei/mcp-contract serve --env prod
  • OAuth 只在首次 login / install 时发生一次
  • token 过期时优先静默 refresh，失败时给出单一重登录指令

安装与使用

要求：

• Node.js 20+
• 能访问 QFEI MCP 与 OAuth 相关地址

私仓配置：

• 文档里的命令默认假设你已经在本机配置了 ~/.npmrc
• 使用者只需要配置 npm-group
• 只有发布者才需要配置 npm-hosted

推荐只对 @zhishu_qfei scope 指定私仓：

@zhishu_qfei:registry=https://nexus.qtech.cn/repository/npm-group/
always-auth=true
//nexus.qtech.cn/repository/npm-group/:_auth=<base64(username:password)>
email=<your_email>

如果只是临时试用，不想修改 ~/.npmrc，就在所有命令前显式指定 --registry：

npx --yes --registry=https://nexus.qtech.cn/repository/npm-group/ @zhishu_qfei/mcp-contract login --env dev

首次登录：

如果已经配置好 ~/.npmrc：

npx -y @zhishu_qfei/mcp-contract login --env prod

如果还没有配置 ~/.npmrc：

npx --yes --registry=https://nexus.qtech.cn/repository/npm-group/ @zhishu_qfei/mcp-contract login --env prod

会自动：

1. 发现受保护资源与授权服务器元数据
2. 动态注册客户端
3. 启动本地 loopback callback
4. 打开浏览器完成 OAuth
5. 缓存 token、OAuth 元数据与 tools/list 快照

三条主路径

Cursor

直接写入用户级配置：

npx -y @zhishu_qfei/mcp-contract install cursor --scope user --env prod

项目级配置：

npx -y @zhishu_qfei/mcp-contract install cursor --scope project --env prod

只打印配置与 deeplink：

npx -y @zhishu_qfei/mcp-contract install cursor --print-only --env prod

Claude Code

如果本机存在 claude CLI：

npx -y @zhishu_qfei/mcp-contract install claude --scope user --env prod

如果本机不存在 claude CLI，命令会打印可直接执行的 claude mcp add ... 命令和配置片段。

Codex

npx -y @zhishu_qfei/mcp-contract install codex --env prod

这条路径只给 Codex 注册本地 stdio server，不依赖 codex mcp login。

运行 bridge

客户端最终启动的本地 MCP server 是：

npx -y @zhishu_qfei/mcp-contract serve --env prod

serve 行为：

• 启动时读取本地缓存的 tool schema
• 如果 token 过期且可 refresh，则静默 refresh
• 如果 token 失效但本地仍有 tool cache，工具仍可暴露，调用时会要求重新登录
• 如果既没有有效 token 也没有 tool cache，会直接失败

诊断与登出

诊断：

npx -y @zhishu_qfei/mcp-contract doctor --env prod

会输出：

• 本地配置目录
• 受保护资源发现地址
• 远程 MCP 地址
• 本地 session 是否存在
• token 状态
• tool cache 数量
• 受保护资源与远端 initialize 是否可达

清理缓存：

npx -y @zhishu_qfei/mcp-contract logout

默认地址

prod

• 受保护资源发现：http://mcp.qfei.cn/.well-known/oauth-protected-resource
• MCP server：http://mcp.qfei.cn/mcp-servers/clm-contract

dev

• 受保护资源发现：https://mcp.qtech.cn/.well-known/oauth-protected-resource
• MCP server：https://mcp.qtech.cn/mcp-servers/contract-group

可通过环境变量覆盖：

• QFEI_MCP_CONFIG_DIR
• QFEI_MCP_PROD_PROTECTED_RESOURCE_URL
• QFEI_MCP_PROD_SERVER_URL
• QFEI_MCP_DEV_PROTECTED_RESOURCE_URL
• QFEI_MCP_DEV_SERVER_URL

常见问题

| 症状 | 处理方式 | | --- | --- | | 浏览器完成授权后 CLI 无响应 | 检查本机 loopback 端口是否被代理/防火墙拦截 | | No saved session exists | 先执行 npx -y @zhishu_qfei/mcp-contract login --env prod | | No refresh token is available | 重新执行 login 获取新 token | | Cursor 已存在同名配置冲突 | 加 --force 覆盖，或先手工清理 .cursor/mcp.json 中的 qfei-contract | | doctor 显示 protectedResourceReachable=false | 先排查网络、代理、DNS 或内网连通性 |

高级手工 OAuth / 排障参考见 docs/manual-oauth-troubleshooting.md。