mcporter — 安装部署及使用完全指南（二）

四、核心概念与架构

4.1 MCP 协议简介

Model Context Protocol (MCP) 是 Anthropic 提出的标准化接口，用于连接 AI 代理与外部工具、数据源和服务。它定义了三种核心交互方式：

概念	说明	类比
Tools（工具）	可执行的函数，代理调用它们完成操作	函数调用
Resources（资源）	只读数据，代理读取它们获取上下文	文件/数据库查询
Prompts（提示词）	预定义的模板，引导代理行为	系统提示词

4.2 mcporter 的架构

#mermaid-svg-yQDbpnik4zSMC66x{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-yQDbpnik4zSMC66x .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-yQDbpnik4zSMC66x .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-yQDbpnik4zSMC66x .error-icon{fill:#552222;}#mermaid-svg-yQDbpnik4zSMC66x .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-yQDbpnik4zSMC66x .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-yQDbpnik4zSMC66x .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-yQDbpnik4zSMC66x .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-yQDbpnik4zSMC66x .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-yQDbpnik4zSMC66x .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-yQDbpnik4zSMC66x .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-yQDbpnik4zSMC66x .marker{fill:#333333;stroke:#333333;}#mermaid-svg-yQDbpnik4zSMC66x .marker.cross{stroke:#333333;}#mermaid-svg-yQDbpnik4zSMC66x svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-yQDbpnik4zSMC66x p{margin:0;}#mermaid-svg-yQDbpnik4zSMC66x .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-yQDbpnik4zSMC66x .cluster-label text{fill:#333;}#mermaid-svg-yQDbpnik4zSMC66x .cluster-label span{color:#333;}#mermaid-svg-yQDbpnik4zSMC66x .cluster-label span p{background-color:transparent;}#mermaid-svg-yQDbpnik4zSMC66x .label text,#mermaid-svg-yQDbpnik4zSMC66x span{fill:#333;color:#333;}#mermaid-svg-yQDbpnik4zSMC66x .node rect,#mermaid-svg-yQDbpnik4zSMC66x .node circle,#mermaid-svg-yQDbpnik4zSMC66x .node ellipse,#mermaid-svg-yQDbpnik4zSMC66x .node polygon,#mermaid-svg-yQDbpnik4zSMC66x .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-yQDbpnik4zSMC66x .rough-node .label text,#mermaid-svg-yQDbpnik4zSMC66x .node .label text,#mermaid-svg-yQDbpnik4zSMC66x .image-shape .label,#mermaid-svg-yQDbpnik4zSMC66x .icon-shape .label{text-anchor:middle;}#mermaid-svg-yQDbpnik4zSMC66x .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-yQDbpnik4zSMC66x .rough-node .label,#mermaid-svg-yQDbpnik4zSMC66x .node .label,#mermaid-svg-yQDbpnik4zSMC66x .image-shape .label,#mermaid-svg-yQDbpnik4zSMC66x .icon-shape .label{text-align:center;}#mermaid-svg-yQDbpnik4zSMC66x .node.clickable{cursor:pointer;}#mermaid-svg-yQDbpnik4zSMC66x .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-yQDbpnik4zSMC66x .arrowheadPath{fill:#333333;}#mermaid-svg-yQDbpnik4zSMC66x .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-yQDbpnik4zSMC66x .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-yQDbpnik4zSMC66x .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-yQDbpnik4zSMC66x .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-yQDbpnik4zSMC66x .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-yQDbpnik4zSMC66x .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-yQDbpnik4zSMC66x .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-yQDbpnik4zSMC66x .cluster text{fill:#333;}#mermaid-svg-yQDbpnik4zSMC66x .cluster span{color:#333;}#mermaid-svg-yQDbpnik4zSMC66x div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-yQDbpnik4zSMC66x .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-yQDbpnik4zSMC66x rect.text{fill:none;stroke-width:0;}#mermaid-svg-yQDbpnik4zSMC66x .icon-shape,#mermaid-svg-yQDbpnik4zSMC66x .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-yQDbpnik4zSMC66x .icon-shape p,#mermaid-svg-yQDbpnik4zSMC66x .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-yQDbpnik4zSMC66x .icon-shape .label rect,#mermaid-svg-yQDbpnik4zSMC66x .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-yQDbpnik4zSMC66x .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-yQDbpnik4zSMC66x .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-yQDbpnik4zSMC66x :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 🌐 MCP 服务器
📁 配置源
⚙️ mcporter 运行时
👤 用户 / Agent
mcporter CLI
TypeScript API

createServerProxy
Agent Skill 文件
🔍 配置发现引擎
📡 传输层

stdio / HTTP / SSE
🔐 OAuth 管理器

缓存 + 刷新
👻 Keep-Alive 守护进程
~/.mcporter/mcporter.json
./config/mcporter.json
编辑器导入

Cursor / Claude / VS Code...
stdio 服务器

本地进程
HTTP 服务器

远程 API
SSE 服务器

流式推送

4.3 传输协议对比

传输协议	适用场景	优点	缺点
stdio	本地工具、命令行程序	简单、无需网络	每次调用启动新进程（除非 keep-alive）
HTTP	远程 API、云服务	可扩展、可监控	需要网络、可能需认证
SSE	流式响应、实时推送	实时性好	连接管理复杂

4.4 配置发现流程

#mermaid-svg-gSTzgKof3E5Hj8Bm{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-gSTzgKof3E5Hj8Bm .error-icon{fill:#552222;}#mermaid-svg-gSTzgKof3E5Hj8Bm .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-gSTzgKof3E5Hj8Bm .marker{fill:#333333;stroke:#333333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .marker.cross{stroke:#333333;}#mermaid-svg-gSTzgKof3E5Hj8Bm svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-gSTzgKof3E5Hj8Bm p{margin:0;}#mermaid-svg-gSTzgKof3E5Hj8Bm .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster-label text{fill:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster-label span{color:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster-label span p{background-color:transparent;}#mermaid-svg-gSTzgKof3E5Hj8Bm .label text,#mermaid-svg-gSTzgKof3E5Hj8Bm span{fill:#333;color:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .node rect,#mermaid-svg-gSTzgKof3E5Hj8Bm .node circle,#mermaid-svg-gSTzgKof3E5Hj8Bm .node ellipse,#mermaid-svg-gSTzgKof3E5Hj8Bm .node polygon,#mermaid-svg-gSTzgKof3E5Hj8Bm .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .rough-node .label text,#mermaid-svg-gSTzgKof3E5Hj8Bm .node .label text,#mermaid-svg-gSTzgKof3E5Hj8Bm .image-shape .label,#mermaid-svg-gSTzgKof3E5Hj8Bm .icon-shape .label{text-anchor:middle;}#mermaid-svg-gSTzgKof3E5Hj8Bm .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .rough-node .label,#mermaid-svg-gSTzgKof3E5Hj8Bm .node .label,#mermaid-svg-gSTzgKof3E5Hj8Bm .image-shape .label,#mermaid-svg-gSTzgKof3E5Hj8Bm .icon-shape .label{text-align:center;}#mermaid-svg-gSTzgKof3E5Hj8Bm .node.clickable{cursor:pointer;}#mermaid-svg-gSTzgKof3E5Hj8Bm .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .arrowheadPath{fill:#333333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gSTzgKof3E5Hj8Bm .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-gSTzgKof3E5Hj8Bm .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gSTzgKof3E5Hj8Bm .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster text{fill:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm .cluster span{color:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-gSTzgKof3E5Hj8Bm .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-gSTzgKof3E5Hj8Bm rect.text{fill:none;stroke-width:0;}#mermaid-svg-gSTzgKof3E5Hj8Bm .icon-shape,#mermaid-svg-gSTzgKof3E5Hj8Bm .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gSTzgKof3E5Hj8Bm .icon-shape p,#mermaid-svg-gSTzgKof3E5Hj8Bm .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-gSTzgKof3E5Hj8Bm .icon-shape .label rect,#mermaid-svg-gSTzgKof3E5Hj8Bm .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gSTzgKof3E5Hj8Bm .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-gSTzgKof3E5Hj8Bm .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-gSTzgKof3E5Hj8Bm :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
mcporter 启动
--config 或

MCPORTER_CONFIG

环境变量？
仅使用该文件
加载 ~/.mcporter/mcporter.jsonc
加载 ./config/mcporter.json
合并配置

项目覆盖家庭
导入编辑器配置

Cursor / Claude / VS Code...
展开 ${ENV} 占位符
连接池复用
就绪

---

五、配置详解

5.1 配置文件格式

在项目根目录创建 config/mcporter.json：

{
  "$schema": "https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.schema.json",
  "mcpServers": {
    "linear": {
      "description": "Linear issues",
      "baseUrl": "https://mcp.linear.app/mcp",
      "headers": {
        "Authorization": "Bearer ${LINEAR_API_KEY}"
      }
    },
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "imports": [
    "cursor",
    "claude-code",
    "claude-desktop",
    "codex",
    "windsurf",
    "opencode",
    "vscode"
  ]
}

💡 $schema 属性启用 IDE 自动补全和验证。文件支持 JSONC（允许注释）。

5.2 配置解析顺序

#mermaid-svg-ZqZf4GTOjwstVdSx{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ZqZf4GTOjwstVdSx .error-icon{fill:#552222;}#mermaid-svg-ZqZf4GTOjwstVdSx .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ZqZf4GTOjwstVdSx .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ZqZf4GTOjwstVdSx .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ZqZf4GTOjwstVdSx .marker.cross{stroke:#333333;}#mermaid-svg-ZqZf4GTOjwstVdSx svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ZqZf4GTOjwstVdSx p{margin:0;}#mermaid-svg-ZqZf4GTOjwstVdSx .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster-label text{fill:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster-label span{color:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster-label span p{background-color:transparent;}#mermaid-svg-ZqZf4GTOjwstVdSx .label text,#mermaid-svg-ZqZf4GTOjwstVdSx span{fill:#333;color:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx .node rect,#mermaid-svg-ZqZf4GTOjwstVdSx .node circle,#mermaid-svg-ZqZf4GTOjwstVdSx .node ellipse,#mermaid-svg-ZqZf4GTOjwstVdSx .node polygon,#mermaid-svg-ZqZf4GTOjwstVdSx .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ZqZf4GTOjwstVdSx .rough-node .label text,#mermaid-svg-ZqZf4GTOjwstVdSx .node .label text,#mermaid-svg-ZqZf4GTOjwstVdSx .image-shape .label,#mermaid-svg-ZqZf4GTOjwstVdSx .icon-shape .label{text-anchor:middle;}#mermaid-svg-ZqZf4GTOjwstVdSx .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ZqZf4GTOjwstVdSx .rough-node .label,#mermaid-svg-ZqZf4GTOjwstVdSx .node .label,#mermaid-svg-ZqZf4GTOjwstVdSx .image-shape .label,#mermaid-svg-ZqZf4GTOjwstVdSx .icon-shape .label{text-align:center;}#mermaid-svg-ZqZf4GTOjwstVdSx .node.clickable{cursor:pointer;}#mermaid-svg-ZqZf4GTOjwstVdSx .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ZqZf4GTOjwstVdSx .arrowheadPath{fill:#333333;}#mermaid-svg-ZqZf4GTOjwstVdSx .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ZqZf4GTOjwstVdSx .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ZqZf4GTOjwstVdSx .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ZqZf4GTOjwstVdSx .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ZqZf4GTOjwstVdSx .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ZqZf4GTOjwstVdSx .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster text{fill:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx .cluster span{color:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ZqZf4GTOjwstVdSx .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ZqZf4GTOjwstVdSx rect.text{fill:none;stroke-width:0;}#mermaid-svg-ZqZf4GTOjwstVdSx .icon-shape,#mermaid-svg-ZqZf4GTOjwstVdSx .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ZqZf4GTOjwstVdSx .icon-shape p,#mermaid-svg-ZqZf4GTOjwstVdSx .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ZqZf4GTOjwstVdSx .icon-shape .label rect,#mermaid-svg-ZqZf4GTOjwstVdSx .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ZqZf4GTOjwstVdSx .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ZqZf4GTOjwstVdSx .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ZqZf4GTOjwstVdSx :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 优先级最高
1️⃣ --config

或 MCPORTER_CONFIG
仅使用该文件
2️⃣ $XDG_CONFIG_HOME/mcporter/mcporter.jsonc
3️⃣ /config/mcporter.json
4️⃣ 合并：项目覆盖家庭
5️⃣ 导入编辑器配置
6️⃣ 本地配置优先于导入

详细规则：

1. --config <file> 或 MCPORTER_CONFIG 环境变量 → 仅使用该文件，忽略其他所有来源
2. 否则同时加载 ：
   • $XDG_CONFIG_HOME/mcporter/mcporter.json[c]（或 ~/.mcporter/mcporter.json[c]）
   • <root>/config/mcporter.json
3. 项目文件条目覆盖同名家庭文件条目
4. 导入列表随后加载，本地配置始终优先于导入

5.3 配置 CLI 命令

命令	说明	示例
mcporter config list [filter]	列出本地配置条目	mcporter config list
mcporter config list --source import	列出导入的编辑器配置	mcporter config list --source import
mcporter config get <name>	打印单个服务器的解析定义	mcporter config get linear
mcporter config add <name> [target]	持久化服务器定义	mcporter config add docs https://mcp.context7.com/mcp --scope home
mcporter config remove <name>	移除本地定义	mcporter config remove linear
mcporter config import <kind>	显示（并可复制）编辑器特定配置	mcporter config import cursor
`mcporter config login <name	url>`	完成 OAuth 认证流程
mcporter config logout	清除认证令牌	mcporter config logout
mcporter config doctor	验证配置问题	mcporter config doctor

5.4 XDG 基础目录支持

mcporter 完全遵循 XDG Base Directory Specification：

类型	环境变量	mcporter 路径	旧版回退
📁 配置	XDG_CONFIG_HOME	$XDG_CONFIG_HOME/mcporter/mcporter.json[c]	~/.mcporter/...
💾 数据	XDG_DATA_HOME	$XDG_DATA_HOME/mcporter/credentials.json	~/.mcporter/...
🗂️ 缓存	XDG_CACHE_HOME	$XDG_CACHE_HOME/mcporter/<server>/schema.json	~/.mcporter/...
📊 状态	XDG_STATE_HOME	$XDG_STATE_HOME/mcporter/daemon/...	~/.mcporter/daemon

5.5 服务器定义字段完整参考

字段	类型	说明
description	string	自由格式摘要
baseUrl / url / serverUrl	string	HTTP/HTTPS 端点
command	string	Stdio 可执行文件路径
args	string\[\]	Stdio 命令参数（数组形式优先）
cwd	string	Stdio 服务器工作目录
env	object	启动 stdio 命令时注入的环境变量
headers	object	HTTP/SSE 请求头，支持 ${VAR} 占位符
auth	string	认证类型：oauth 或 refreshable_bearer
tokenCacheDir	string	OAuth 令牌和 Schema 缓存目录
clientName	string	可选客户端标识符
protocolVersion	string	协议版本：auto、legacy、2026-07-28
chromeDevtoolsRelay	string	Chrome 扩展中继策略：prefer、require、off
oauthClientId	string	预注册 OAuth 客户端 ID
oauthClientSecretEnv	string	OAuth 客户端密钥环境变量名
oauthTokenEndpointAuthMethod	string	令牌端点认证方法
oauthRedirectUrl	string	自定义回调 URL
oauthScope	string	显式 OAuth 范围
allowedTools	string\[\]	工具白名单
blockedTools	string\[\]	工具黑名单
lifecycle	string	生命周期：keep-alive 或 ephemeral
refresh	object	令牌刷新设置（见下方）

5.6 可刷新 Bearer 令牌配置

对于需要自动刷新令牌的服务器：

{
  "mcpServers": {
    "example": {
      "command": "uvx",
      "args": ["example-mcp-server"],
      "auth": "refreshable_bearer",
      "refresh": {
        "tokenEndpoint": "https://api.example.com/oauth/token",
        "clientIdEnv": "EXAMPLE_CLIENT_ID",
        "clientSecretEnv": "EXAMPLE_CLIENT_SECRET",
        "clientAuthMethod": "client_secret_basic",
        "refreshSkewSeconds": 300,
        "accessTokenEnv": "EXAMPLE_ACCESS_TOKEN"
      }
    }
  }
}

refresh 子字段	说明
tokenEndpoint	OAuth 令牌端点 URL
clientIdEnv	存放 client_id 的环境变量名
clientSecretEnv	存放 client_secret 的环境变量名
clientAuthMethod	客户端认证方法：client_secret_basic 或 client_secret_post
refreshSkewSeconds	提前刷新秒数（默认 300s = 5 分钟）
accessTokenEnv	存放访问令牌的环境变量名

---

六、CLI 命令参考

6.1 mcporter list [server]

发现和管理 MCP 服务器。

用法	说明
mcporter list	列出所有已发现的服务器
mcporter list <server>	打印该服务器的 TypeScript 风格工具签名
mcporter list <server.tool>	仅打印该工具的签名

常用标志：

标志	说明
--brief / --signatures	仅紧凑签名
--all-parameters	显示所有可选参数
--schema	格式化打印 JSON Schema
--json	机器可读 Schema
--status	仅状态摘要
--exit-code	以退出码反映结果
--quiet	静默健康检查
--timeout <ms>	超时时间
--no-oauth	跳过 OAuth 流程

6.2 mcporter call <server.tool>

调用工具并打印响应。

参数传递方式（多种风格任选）：

风格	示例
冒号分隔	mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
等号分隔	mcporter call linear.list_issues team=ENG limit=5
函数调用	mcporter call 'linear.create_issue(title: "Bug")'
JSON 参数	mcporter call <server.tool> --args '{"limit":5}'
文件读取	mcporter call <server.tool> body=@file.md

常用标志：

标志	说明
--server <name>	显式指定服务器
--tool <name>	显式指定工具
--args <json>	JSON 格式参数
--params <json>	JSON 格式参数（别名）
--timeout <ms>	调用超时（默认 60s）
`--output text	markdown
--save-images <dir>	保存二进制图片内容
--raw-strings	原始字符串输出
--no-coerce	禁用类型强制转换
--tail-log	尾随日志输出
--no-oauth	跳过 OAuth

6.3 mcporter resource <server> [uri]

管理 MCP 资源。

用法	说明
mcporter resource <server>	列出该服务器的所有资源
mcporter resource <server> <uri>	读取特定资源

标志 ：--output auto|text|markdown|json|raw、--json、--raw

6.4 mcporter serve

将守护进程管理的 keep-alive 服务器作为 MCP 服务器暴露给其他客户端。

# stdio 模式（适用于 Claude Code、Codex 等）
mcporter serve --stdio

# HTTP 模式
mcporter serve --http 3000

# 仅暴露指定服务器
mcporter serve --http 3000 --servers chrome-devtools,playwright

端点	说明
/mcp	聚合端点，工具名以 server__tool 命名空间分隔
/mcp/<server>	单服务器端点，保留原始工具名

标志 ：--servers <csv>、--host <host>（默认 127.0.0.1）

6.5 mcporter generate-cli

为单个 MCP 服务器生成独立 CLI。

# 从配置中的服务器生成
npx mcporter generate-cli linear --bundle dist/linear.js

# 从命令生成
npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest" --bundle dist/chrome.js

# 生成 Bun 编译的二进制文件
npx mcporter generate-cli linear --compile --bundle dist/linear

标志	说明
--server <name>	从配置中指定服务器
--command <cmd>	从命令生成
--output <path>	模板输出路径
--bundle [path]	同时生成打包文件
`--bundler rolldown	bun`
--compile	生成 Bun 编译的二进制
--include-tools a,b,c	仅包含指定工具
--exclude-tools a,b,c	排除指定工具
`--runtime node	bun`
--from <artifact>	从已有 CLI 元数据重新生成
--dry-run	预览不执行

💡 每个生成的 CLI 都嵌入了再生元数据（生成器版本、解析的服务器定义、调用标志）。使用 mcporter inspect-cli <path> 查看摘要，或用 --from 重新生成。

6.6 mcporter emit-ts <server>

生成 TypeScript 类型定义和客户端。

# 仅类型定义
npx mcporter emit-ts linear --mode types --out types/linear-tools.d.ts

# 完整客户端
npx mcporter emit-ts linear --mode client --out clients/linear.ts

标志	说明
--mode types	仅 .d.ts 接口（默认）
--mode client	.d.ts + 可运行的客户端工厂
--out <path>	输出路径
--include-optional	包含所有可选字段
--types-out <path>	类型定义单独输出路径
--json	结构化摘要输出

6.7 mcporter auth <server|url>

完成 OAuth 认证流程。

# 为已配置的服务器认证
mcporter auth linear

# 为 URL 认证（自动提升为 OAuth 定义）
mcporter auth https://mcp.example.com/mcp

# 无头环境（不自动打开浏览器）
mcporter auth linear --no-browser

标志 ：--no-browser、--json

6.8 mcporter daemon

管理 Keep-Alive 守护进程。

mcporter daemon status      # 查看状态
mcporter daemon start       # 启动
mcporter daemon restart     # 重启
mcporter daemon stop        # 停止

标志 ：--log、--log-file <path>、--log-servers <csv>

6.9 退出码

码	含义
0	✅ 成功
1	❌ 调用或运行时错误

---