十、MCP 桥接模式mcporter serve将守护进程管理的 keep-alive 服务器重新暴露为一个统一的 MCP 服务器让不支持 HTTP 的客户端也能使用。10.1 stdio 桥接mcporter serve--stdio适用于Claude Code、Codex等仅支持 stdio 的客户端。所有 keep-alive 服务器的工具以server__tool的命名空间形式暴露。10.2 HTTP 桥接mcporter serve--http3000端点说明http://127.0.0.1:3000/mcp聚合端点工具名chrome-devtools__list_pageshttp://127.0.0.1:3000/mcp/server单服务器端点保留原始工具名10.3 桥接架构 mcporter serve️ MCP 客户端 Keep-Alive 守护进程Chrome DevToolsPlaywrightLinear APIClaude Code(stdio)自定义 Agent(HTTP)--stdio--http 300010.4 仅暴露指定服务器mcporter serve--http3000--serverschrome-devtools,playwright10.5 Chrome DevTools 扩展中继当使用chrome-devtools-mcp --autoConnect时Chrome 的远程调试握手可能每次会话都弹出 “Allow remote debugging?” 对话框。如果同一主机上配对了 OpenClaw Chrome 扩展中继mcporter 可以使用扩展支持的 Chrome 控制路径代替。配置选项策略行为prefer默认优先使用 v2 扩展中继失败时回退到原始 Chrome--autoConnectrequire强制使用 v2 扩展中继任何失败都直接报错off禁用中继探测使用原始 auto-connect{ mcpServers: { chrome-devtools: { command: npx, args: [-y, chrome-devtools-mcplatest, --autoConnect], lifecycle: keep-alive, chromeDevtoolsRelay: require } } }十一、代理技能模式11.1 核心理念推荐为每个 MCP 服务器或工作流编写一个小型技能文件而非一个通用技能。一个通用技能必须教会代理如何发现、选择和调用每个配置的服务器——这重现了 mcporter 试图避免的大型 Schema 上下文问题。per-server 技能保持精简让技能作者描述该服务器的安全、有用的工作流。11.2 推荐工作流1. 添加/导入 MCP 服务器2. 检查工具表面3. 编写小型技能文件4. 调用相关工具5. 需要分享生成专用 CLI11.3 技能文件示例--- name: docs-mcp description: Fetch package and framework docs through the configured docs MCP server. --- # Docs MCP Use npx mcporter call docs.resolve-library-id querytask libraryNamename to resolve a package, then call npx mcporter call docs.query-docs ... with the resolved ID and docs query.11.4 完整步骤示例# 1. 添加 MCP 服务器npx mcporter configadddocs https://mcp.context7.com/mcp--scopehome# 2. 检查工具表面npx mcporter list docs--briefnpx mcporter list docs--schema# 3. 编写技能文件见上方示例# 4. 在 Agent 中使用技能文件# 5. 对于可分享工作流生成专用 CLInpx mcporter generate-cli docs--bundledist/docs-mcp.js11.5 工具过滤使用allowedTools或blockedTools限制暴露给代理的工具{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], allowedTools: [search_repositories, get_file_contents] } } }十二、TypeScript 运行时 API12.1 创建服务器代理推荐createServerProxy()将 MCP 工具名映射为 camelCase 方法自动应用 JSON Schema 默认值验证必填参数返回带有.text()、.markdown()、.json()、.images()、.content()辅助方法的CallResult。import{createServerProxy}frommcporter;constproxyawaitcreateServerProxy(linear);constresultawaitproxy.createIssue({title:Bug report,team:ENG,});// 多种输出格式console.log(result.text());// 纯文本console.log(result.markdown());// Markdownconsole.log(result.json());// JSONconsole.log(result.images());// 图片数组console.log(result.content());// 原始内容12.2 一次性调用callOnce()处理单次调用和清理适合脚本场景import{callOnce}frommcporter;constresultawaitcallOnce(linear,createIssue,{title:Bug report,team:ENG,});console.log(result.text());12.3 底层运行时createRuntime()当你需要显式控制服务器定义、连接复用或多个调用时import{createRuntime}frommcporter;construntimeawaitcreateRuntime({servers:[{name:context7,command:{kind:http,url:newURL(https://mcp.context7.com/mcp)}}],});try{consttoolsawaitruntime.listTools(context7);console.log(tools.map((tool)tool.name));}finally{awaitruntime.close();}12.4 API 对比API适用场景连接管理createServerProxy()大多数场景类型友好的方法调用自动管理callOnce()单次调用脚本自动创建和关闭createRuntime()复杂场景需要精细控制手动runtime.close()十三、日志与诊断13.1 守护进程日志# 启动守护进程并记录日志mcporter daemon start--log# 指定日志文件mcporter daemon start--log--log-file /path/to/log# 限制日志范围到特定服务器mcporter daemon start--log--log-servers chrome-devtools,playwright13.2 环境变量日志级别# 查看结构化连接决策日志MCPORTER_LOG_LEVELinfo mcporter list13.3 调试挂起调用当mcporter call打印了工具响应但进程永不退出时通常是 Node 仍有活跃句柄在等待最常见的是子进程 MCP 服务器保持 stdio 传输存活。快速检查清单在 tmux 中运行— 启动命令在 tmux 中这样即使 Cursor 或其他代理超时你也能检查面板内容启用挂起诊断— 设置MCPORTER_DEBUG_HANG1检查句柄列表— 查找ChildProcess (pid…)条目捕获面板输出—tmux capture-pane -p -t session -S -200使用--timeout— 如果工具本身挂起设置超时快速失败限制 OAuth 等待—--oauth-timeout ms或MCPORTER_OAUTH_TIMEOUT_MS示例诊断会话tmux new-session-d-smcphangcd /path/to/project MCPORTER_DEBUG_HANG1 mcporter call chrome-devtools list_pagessleep5tmux capture-pane-p-tmcphang-S-200典型诊断输出[mcporter] [debug] after call (object result): 6 active handle(s), 0 request(s) [mcporter] [debug] handle ChildProcess (pid78480) [mcporter] [debug] beginning runtime.close() [mcporter] [debug] after runtime.close: 6 active handle(s), 0 request(s) [mcporter] [debug] forcibly killed child pid78480 (runtime.finally) CLI 默认在清理后强制process.exit(0)防止 Node 在泄漏句柄上挂起。调试时设置MCPORTER_NO_FORCE_EXIT1保持进程存活。13.4 Stdio 服务器日志Stdio 服务器的 stderr 输出默认被抑制。设置以下环境变量查看MCPORTER_STDIO_LOGS1mcporter callserver.tool当子进程以非零状态退出时其日志也会自动显示。十四、最佳实践14.1 项目 vs 机器层配置 CI/CD 项目层纳入版本控制config/mcporter.json$schema 引用${LINEAR_API_KEY}环境变量占位符️ 机器层不纳入版本控制~/.mcporter/mcporter.jsonOAuth 令牌~/.mcporter/credentials.json~/.mcporter/local.json机器特定配置--config config/mcporter.json14.2 配置管理清单实践说明✅ 版本控制将config/mcporter.json纳入版本控制✅ 敏感数据使用环境变量${LINEAR_API_KEY}而非内联密钥✅ 预注册 OAuth配置中存储公开的oauthClientId使用oauthClientSecretEnv指向本地环境变量✅ 机器特定配置放在~/.mcporter/local.json使用--config指定✅ CI 环境始终传递--config config/mcporter.json确保确定性行为❌ 不提交令牌OAuth 令牌保留在~/.mcporter/...或XDG_*_HOME/mcporter/...绝不纳入仓库14.3 安全建议非 HTTPS 端点仅在内网使用--allow-http生产环境始终使用 HTTPSStdio 命令确认首次遇到新 stdio 命令时mcporter 会打印确认摘要仔细审查工具白名单对于暴露敏感操作的服务器使用allowedTools限制可用工具令牌刷新使用refreshable_bearer自动管理令牌生命周期避免手动更新十五、故障排除15.1 常见问题速查问题原因解决方案环境占位符缺失配置中使用了${VAR}但环境变量未设置添加环境变量或使用${VAR:-fallback}提供默认值配置来源不明不确定服务器从哪个配置文件加载mcporter config get name显示服务器来源和完整路径导入冲突多个编辑器配置了同名服务器重新排序imports数组或设为[]禁用所有导入OAuth 问题浏览器流程失败或无头环境mcporter auth name --no-browser在无头环境完成认证守护进程问题连接状态异常mcporter daemon status查看状态mcporter daemon restart重启调用挂起子进程未正确退出使用--timeout或MCPORTER_DEBUG_HANG1诊断EADDRINUSE端口localhost:3334被占用检查是否有其他 mcporter 实例在运行15.2 诊断命令速查# 查看 mcporter 版本mcporter--version# 查看服务器来源和配置mcporter config getserver-name# 查看守护进程状态mcporter daemon status# 启用挂起诊断MCPORTER_DEBUG_HANG1mcporter callserver.tool# 查看 stdio 服务器日志MCPORTER_STDIO_LOGS1mcporter callserver.tool# 结构化日志输出MCPORTER_LOG_LEVELinfo mcporter list# 验证配置mcporter config doctor