{
  "canonical_name": "steipete/mcporter",
  "compilation_id": "pack_e7a3a3fe5cb94751ad28363cffa53c46",
  "created_at": "2026-05-19T06:59:43.556582+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `npx mcporter` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "npx mcporter",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_a55269f9ca2542328650c549e97cc6af"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_f80b020c2b312fdf2765a36af7de01a9",
    "canonical_name": "steipete/mcporter",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/steipete/mcporter",
    "slug": "mcporter",
    "source_packet_id": "phit_0a703ff64ce044c594eb23ab7a9176ba",
    "source_validation_id": "dval_294a3b2a7aa64f6797760813f127ea78"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
    "github_forks": null,
    "github_stars": null,
    "one_liner_en": "MCPorter 🧳 - Call MCPs from TypeScript or as CLI",
    "one_liner_zh": "MCPorter 🧳 - Call MCPs from TypeScript or as CLI",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "high",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:code, git, cli"
    },
    "target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
    "title_en": "mcporter",
    "title_zh": "mcporter 能力包",
    "visible_tags": [
      {
        "label_en": "Browser Agents",
        "label_zh": "浏览器 Agent",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-browser-agents",
        "type": "product_domain"
      },
      {
        "label_en": "Web Task Automation",
        "label_zh": "网页任务自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-web-task-automation",
        "type": "user_job"
      },
      {
        "label_en": "Browser Automation",
        "label_zh": "浏览器自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-browser-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Node-based Workflow",
        "label_zh": "节点式流程编排",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-node-based-workflow",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Evaluation Suite",
        "label_zh": "评测体系",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-evaluation-suite",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_0a703ff64ce044c594eb23ab7a9176ba",
  "page_model": {
    "artifacts": {
      "artifact_slug": "mcporter",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "npx mcporter",
          "label": "Node.js / npx · 官方安装入口",
          "source": "https://github.com/steipete/mcporter#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 mcp_host的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "MCPorter 🧳 - Call MCPs from TypeScript or as CLI"
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "mcp_host, claude, claude_code, cursor",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "mcp_config, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "high",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
            "category": "配置坑",
            "evidence": [
              "capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor"
            ],
            "severity": "medium",
            "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
            "title": "可能修改宿主 AI 配置",
            "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout",
            "category": "配置坑",
            "evidence": [
              "community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout",
            "user_impact": "可能影响升级、迁移或版本选择。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`daemonIdleTimeoutMs` missing?",
            "category": "配置坑",
            "evidence": [
              "community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：`daemonIdleTimeoutMs` missing?",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...",
            "category": "运行坑",
            "evidence": [
              "social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit"
            ],
            "severity": "medium",
            "suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。",
            "title": "社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit",
            "user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add `mcporter vault set <server>` to seed credentials non-interactively",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_b63d0f3f42e046488953064089bf8025 | https://github.com/openclaw/mcporter/issues/156 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Add `mcporter vault set <server>` to seed credentials non-interactively",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_2d76f84533e8406d965b1762634996dd | https://github.com/openclaw/mcporter/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows",
            "user_impact": "可能影响升级、迁移或版本选择。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCPorter not using OAuth credentials",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_2705d784929e4996bcb34f3a71543ed7 | https://github.com/openclaw/mcporter/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：MCPorter not using OAuth credentials",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_78f73e8e0c9d4cca9e886fa2d89ef296 | https://github.com/openclaw/mcporter/issues/158 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocations",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_9439129321d048dabb2ad6f14b4ab11e | https://github.com/openclaw/mcporter/issues/167 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocat…",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support refreshable bearer token auth for stdio MCP servers",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_88f8026283fc46309d02fbb7f6a3186f | https://github.com/openclaw/mcporter/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Support refreshable bearer token auth for stdio MCP servers",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": null,
        "forks": null,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": null
      },
      "source_url": "https://github.com/steipete/mcporter",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "MCPorter 🧳 - Call MCPs from TypeScript or as CLI",
      "title": "mcporter 能力包",
      "trial_prompt": "# mcporter - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcporter 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCPorter 🧳 - Call MCPs from TypeScript or as CLI 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：核心架构。围绕“核心架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-runtime-system：运行时系统。围绕“运行时系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“核心架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-runtime-system\n输入：用户提供的“运行时系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quick-start：Step 3 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“核心架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-runtime-system：Step 5 必须围绕“运行时系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/steipete/mcporter#readme\n- README.md\n- package.json\n- src/index.ts\n- docs/install.md\n- docs/windows.md\n- docs/quickstart.md\n- src/cli.ts\n- src/cli/call-command.ts\n- src/config.ts\n- src/config/read-config.ts\n- src/config-normalize.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcporter 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "voices": [
        {
          "body": "来源平台：github。github/github_issue: generate-cli produces non-deterministic bundles: tmp paths and schema ke（https://github.com/openclaw/mcporter/issues/180）；github/github_issue: MCPorter not using OAuth credentials（https://github.com/openclaw/mcporter/issues/179）；github/github_issue: OAuth callback server not reachable when run via process managers that u（https://github.com/openclaw/mcporter/issues/177）；github/github_issue: `daemonIdleTimeoutMs` missing?（https://github.com/openclaw/mcporter/issues/174）；github/github_issue: Support refreshable bearer token auth for stdio MCP servers（https://github.com/openclaw/mcporter/issues/173）；github/github_issue: Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 （https://github.com/openclaw/mcporter/issues/158）；github/github_issue: Add a flag to suppress browser launch in `auth` / `config login` for hea（https://github.com/openclaw/mcporter/issues/169）；github/github_issue: Residual structuredContent regression in 0.10.2: memory-* servers fail a（https://github.com/openclaw/mcporter/issues/168）；github/github_issue: Serialize concurrent file writes — credentials.json, mcporter.json, OAut（https://github.com/openclaw/mcporter/issues/167）；github/github_issue: list reports auth required on expired access_token even when refresh_tok（https://github.com/openclaw/mcporter/issues/166）；github/github_issue: JSON output mode broken for MCP servers using structuredContent and isEr（https://github.com/openclaw/mcporter/issues/160）；github/github_issue: Add `mcporter vault set <server>` to seed credentials non-interactively（https://github.com/openclaw/mcporter/issues/156）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_issue",
              "source": "github",
              "title": "generate-cli produces non-deterministic bundles: tmp paths and schema ke",
              "url": "https://github.com/openclaw/mcporter/issues/180"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "MCPorter not using OAuth credentials",
              "url": "https://github.com/openclaw/mcporter/issues/179"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "OAuth callback server not reachable when run via process managers that u",
              "url": "https://github.com/openclaw/mcporter/issues/177"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "`daemonIdleTimeoutMs` missing?",
              "url": "https://github.com/openclaw/mcporter/issues/174"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Support refreshable bearer token auth for stdio MCP servers",
              "url": "https://github.com/openclaw/mcporter/issues/173"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 ",
              "url": "https://github.com/openclaw/mcporter/issues/158"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Add a flag to suppress browser launch in `auth` / `config login` for hea",
              "url": "https://github.com/openclaw/mcporter/issues/169"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Residual structuredContent regression in 0.10.2: memory-* servers fail a",
              "url": "https://github.com/openclaw/mcporter/issues/168"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Serialize concurrent file writes — credentials.json, mcporter.json, OAut",
              "url": "https://github.com/openclaw/mcporter/issues/167"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "list reports auth required on expired access_token even when refresh_tok",
              "url": "https://github.com/openclaw/mcporter/issues/166"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "JSON output mode broken for MCP servers using structuredContent and isEr",
              "url": "https://github.com/openclaw/mcporter/issues/160"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Add `mcporter vault set <server>` to seed credentials non-interactively",
              "url": "https://github.com/openclaw/mcporter/issues/156"
            }
          ],
          "status": "已收录 13 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "MCPorter 🧳 - Call MCPs from TypeScript or as CLI",
      "effort": "安装已验证",
      "forks": null,
      "icon": "code",
      "name": "mcporter 能力包",
      "risk": "可发布",
      "slug": "mcporter",
      "stars": null,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "thumb": "gray",
      "type": "MCP 配置"
    },
    "manual": {
      "markdown": "# https://github.com/steipete/mcporter 项目说明书\n\n生成时间：2026-05-18 21:37:46 UTC\n\n## 目录\n\n- [项目概述](#page-project-overview)\n- [安装指南](#page-installation-guide)\n- [快速入门](#page-quick-start)\n- [核心架构](#page-core-architecture)\n- [运行时系统](#page-runtime-system)\n- [传输层](#page-transport-layer)\n- [CLI 命令参考](#page-cli-reference)\n- [工具调用语法](#page-call-syntax)\n- [调用启发式与自动更正](#page-call-heuristic)\n- [配置管理](#page-configuration)\n\n<a id='page-project-overview'></a>\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [快速入门](#page-quick-start), [安装指南](#page-installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/index.ts](https://github.com/steipete/mcporter/blob/main/src/index.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n</details>\n\n# 项目概述\n\nmcporter 是一个命令行工具，用于统一管理和调用 MCP（Model Context Protocol）服务器。它提供了配置管理、服务器调用、工具生成等核心功能，帮助开发者更高效地集成和操作 MCP 服务。\n\n## 核心定位\n\nmcporter 的设计目标是为 MCP 服务器提供统一的入口层：\n\n- **配置管理**：集中管理多个 MCP 服务器配置\n- **工具调用**：通过 CLI 直接调用 MCP 工具\n- **类型生成**：自动生成 TypeScript 类型定义和客户端代码\n- **跨编辑器兼容**：支持导入/导出 Cursor、Claude、VS Code 等编辑器的 MCP 配置\n\n资料来源：[README.md:1-15]()\n\n## 核心命令\n\nmcporter 提供了以下主要命令：\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `config` | 管理 MCP 配置 | `mcporter config list`、`mcporter config add` |\n| `list` | 列出可用工具 | `mcporter list <server>` |\n| `call` | 调用 MCP 工具 | `mcporter call <server>.<tool>` |\n| `generate-cli` | 生成独立 CLI | `mcporter generate-cli --command <url>` |\n| `emit-ts` | 生成 TypeScript 类型 | `mcporter emit-ts <server> --out types/` |\n\n资料来源：[README.md:60-85]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n    A[用户 CLI] --> B[mcporter 核心]\n    B --> C{命令路由}\n    C -->|config| D[配置管理模块]\n    C -->|list| E[服务器列表模块]\n    C -->|call| F[工具调用模块]\n    C -->|generate-cli| G[代码生成模块]\n    C -->|emit-ts| H[类型生成模块]\n    D --> I[配置文件<br/>mcporter.json]\n    D --> J[外部导入<br/>Cursor/Claude/VS Code]\n    E --> K[运行时引擎]\n    F --> K\n    K --> L[MCP 协议栈]\n    L --> M[HTTP 传输]\n    L --> N[SSE 传输]\n    L --> O[STDIO 传输]\n```\n\n## 配置系统\n\n### 配置文件格式\n\nmcporter 使用 `config/mcporter.json` 作为主配置文件，格式兼容 JSONC（支持注释和尾随逗号）：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n资料来源：[README.md:30-50]()\n\n### 配置导入功能\n\nmcporter 支持从多种编辑器和工具导入 MCP 配置：\n\n| 来源 | 支持的容器 |\n|------|-----------|\n| Cursor | `mcpServers`、`servers`、`mcp` |\n| Claude Code | `mcpServers`、`servers`、`mcp` |\n| VS Code | `mcpServers`、`servers`、`mcp` |\n| Windsurf | `mcpServers`、`servers`、`mcp` |\n\n资料来源：[README.md:35-40]()\n\n配置导入时支持模糊匹配和自动纠错，例如输入 `sshadcn` 会自动纠正为 `shadcn`。\n\n资料来源：[README.md:45-47]()\n\n## 运行时引擎\n\n运行时引擎是 mcporter 的核心，负责与 MCP 服务器建立连接并执行调用：\n\n```mermaid\nsequenceDiagram\n    用户 ->> CLI: mcporter call server.tool\n    CLI ->> Runtime: createRuntime(config)\n    Runtime ->> Definition: getDefinitions()\n    Definition -->> Runtime: ServerDefinition[]\n    Runtime ->> Transport: 建立连接\n    Transport -->> Runtime: 连接就绪\n    Runtime ->> MCP: callTool(name, args)\n    MCP -->> Runtime: CallResult\n    Runtime -->> CLI: 格式化输出\n    CLI ->> 用户: 显示结果\n```\n\n资料来源：[src/cli/list-command.ts:1-30]()\n\n### 传输类型支持\n\n| 传输类型 | 说明 | 配置字段 |\n|----------|------|----------|\n| HTTP | 基于 HTTP 的请求-响应模式 | `baseUrl` |\n| SSE | Server-Sent Events 模式 | `baseUrl` + `sse` |\n| STDIO | 标准输入输出通信 | `command` + `args` |\n\n资料来源：[src/cli/config/help.ts:5-10]()\n\n## 生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n```mermaid\ngraph LR\n    A[生命周期] --> B[keep-alive]\n    A --> C[ephemeral]\n    B --> D{空闲超时}\n    D -->|无超时| E[持续运行]\n    D -->|设置超时| F[idleTimeoutMs]\n    C --> G[调用后立即关闭]\n```\n\n| 模式 | 说明 | 配置值 |\n|------|------|--------|\n| `keep-alive` | 服务器持续运行，可复用连接 | `\"keep-alive\"` 或 `{ mode: \"keep-alive\", idleTimeoutMs: number }` |\n| `ephemeral` | 每次调用后关闭服务器 | `\"ephemeral\"` |\n\n资料来源：[src/lifecycle.ts:25-40]()\n\n## 工具调用与结果处理\n\n### 调用语法\n\n```bash\nmcporter call <server>.<tool> [key=value ...] [--tool-arg <json>]\n```\n\nmcporter 支持多种参数格式：\n\n- `key=value` 形式\n- `key:value` 形式\n- 尾随位置参数\n- `--tool-arg` JSON 格式\n\n资料来源：[README.md:70-80]()\n\n### 结果类型\n\n调用结果包装在 `CallResult` 对象中，提供多种访问方式：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `.text()` | `string \\| null` | 获取文本内容 |\n| `.markdown()` | `string \\| null` | 获取 Markdown 内容 |\n| `.json()` | `unknown` | 获取 JSON 数据 |\n| `.images()` | `ImageContent[] \\| null` | 获取图片内容 |\n| `.content()` | `string[]` | 获取所有文本内容 |\n| `.raw` | `CallResultEnvelope` | 获取原始响应 |\n\n资料来源：[README.md:110-120]()\n\n### 资源收集逻辑\n\n```mermaid\ngraph TD\n    A[CallResult] --> B{内容类型}\n    B -->|text| C[直接添加]\n    B -->|markdown| D[添加并标记]\n    B -->|image| E[收集 mimeType + data]\n    B -->|resource| F{资源类型}\n    F -->|text| G[解析 JSON 后添加]\n    F -->|blob| H[输出为文本占位符]\n    C --> I[textEntries]\n    D --> I\n    G --> I\n    E --> J[images]\n    H --> I\n```\n\n资料来源：[src/result-utils.ts:15-55]()\n\n## 代码生成功能\n\n### 生成独立 CLI\n\n```bash\nnpx mcporter generate-cli \\\n  --command https://mcp.context7.com/mcp\n```\n\n输出文件：\n- `context7.ts` - TypeScript 模板\n- `context7.js` - 打包后的可执行 CLI\n\n生成的 CLI 嵌入元数据，支持通过 `mcporter inspect-cli` 查看信息或 `mcporter generate-cli --from` 重新生成。\n\n资料来源：[README.md:90-110]()\n\n### 生成 TypeScript 类型\n\n```bash\n# 仅生成类型定义\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成客户端包装器\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n| 模式 | 输出内容 |\n|------|----------|\n| `types`（默认） | `.d.ts` 接口定义 |\n| `client` | `.d.ts` + `.ts` 客户端包装 |\n\n资料来源：[README.md:125-140]()\n\n## 命令行选项参考\n\n### 全局选项\n\n| 选项 | 说明 | 环境变量 |\n|------|------|----------|\n| `--config <path>` | 自定义配置文件路径 | `MCPORTER_CONFIG` |\n| `--root <path>` | 工作目录（用于 stdio 命令） | `MCPORTER_ROOT` |\n| `--log-level <level>` | 日志级别 | `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 等待超时 | `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--tail-log` | 尾随日志输出 | - |\n\n资料来源：[README.md:55-65]()\n\n### list 命令选项\n\n| 选项 | 说明 |\n|------|------|\n| `--all-parameters` | 显示所有可选参数 |\n| `--schema` | 显示 JSON Schema |\n| `--brief` | 简洁输出 |\n| `--json` | JSON 格式输出 |\n| `--timeout <ms>` | 连接超时 |\n\n资料来源：[src/cli/list-command.ts:80-100]()\n\n### call 命令选项\n\n| 选项 | 说明 |\n|------|------|\n| `--raw-strings` | 保持数值型参数为字符串 |\n| `--no-coerce` | 禁用类型转换 |\n| `--save-images <dir>` | 保存图片到目录 |\n| `--raw` | 原始输出格式 |\n| `--` | 停止标志解析 |\n\n资料来源：[README.md:75-80]()\n\n## 错误处理与诊断\n\n### 状态分类\n\n| 状态 | 说明 | 颜色标识 |\n|------|------|----------|\n| `ok` | 调用成功 | 绿色 |\n| `auth` | 认证失败 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 橙色 |\n| `error` | 一般错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:10-25]()\n\n### 诊断命令\n\n```bash\n# 查看服务器状态摘要\nmcporter list --json\n\n# 尾随相关日志\nmcporter call <server>.<tool> --tail-log\n```\n\n## 技术栈\n\n| 组件 | 技术 | 用途 |\n|------|------|------|\n| CLI 框架 | TypeScript | 类型安全 |\n| 传输层 | Bun/Node.js | HTTP/SSE/STDIO |\n| 配置解析 | JSONC | 支持注释的 JSON |\n| 代码打包 | Rolldown/Bun | 生成可执行 CLI |\n\n资料来源：[README.md:100-105]()\n\n## 总结\n\nmcporter 作为一个 MCP 统一管理工具，提供了从配置管理到工具调用、再到代码生成的完整工具链。它的设计强调：\n\n1. **统一性**：多种 MCP 服务器的集中管理\n2. **兼容性**：支持多种编辑器和工具的配置导入\n3. **开发者体验**：模糊匹配、自动纠错、类型生成\n4. **灵活性**：多种传输协议和生命周期管理\n\n通过 mcporter，开发者可以快速集成 MCP 服务器到自己的工作流程中，无需关心底层协议细节。\n\n---\n\n<a id='page-installation-guide'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速入门](#page-quick-start), [项目概述](#page-project-overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)\n- [docs/emit-ts.md](https://github.com/steipete/mcporter/blob/main/docs/emit-ts.md)\n</details>\n\n# 安装指南\n\nmcporter 是一个 MCP（Model Context Protocol）服务器启动器和客户端工具，用于连接和管理各种 MCP 服务器。本指南详细介绍 mcporter 的多种安装方式、项目配置以及进阶用法。\n\n## 环境要求\n\n### 运行时依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0+ | 支持 ES Modules 和原生 HTTP 客户端 |\n| pnpm | 推荐使用 | 项目首选包管理器 |\n| npm | 兼容 | 可作为替代方案 |\n| Homebrew | 最新版 | macOS/Linux 用户可选 |\n\n### 系统要求\n\n- macOS、Linux 或 Windows（通过 WSL 或 Git Bash）\n- 网络连接（用于访问远程 MCP 服务器）\n- OAuth 认证需要浏览器环境\n\n## 安装方式\n\n### 通过 pnpm 安装（推荐）\n\n将 mcporter 添加为项目依赖：\n\n```bash\npnpm add mcporter\n```\n\n这种方式适合在项目内部使用 mcporter API，或者通过 `pnpm exec mcporter` 调用。资料来源：[README.md]()\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g mcporter\n```\n\n安装后可在任意目录直接使用 `mcporter` 命令。资料来源：[README.md]()\n\n### 通过 Homebrew 安装（macOS/Linux）\n\n```bash\nbrew tap steipete/tap\nbrew install steipete/tap/mcporter\n```\n\n> **提示**：Homebrew tap 与 npm 同步发布。如果遇到问题，运行 `brew update` 后重新安装。资料来源：[README.md]()\n\n## 配置管理\n\n### 配置文件位置\n\nmcporter 默认从以下位置读取配置（按优先级排序）：\n\n1. `./config/mcporter.json`（项目本地）\n2. `./config/mcporter.jsonc`（支持注释的配置）\n3. `~/.mcporter/config.json`（用户级别）\n\n### 配置命令\n\n| 命令 | 功能 |\n|------|------|\n| `mcporter config list` | 列出所有本地 MCP 服务器配置 |\n| `mcporter config get <name>` | 获取指定服务器的配置详情 |\n| `mcporter config add` | 交互式添加新服务器 |\n| `mcporter config remove <name>` | 删除服务器配置 |\n| `mcporter config import <kind>` | 从编辑器（Cursor/Claude）导入配置 |\n\n资料来源：[README.md]()\n\n### 配置文件格式\n\nmcporter 使用 JSONC 格式，支持注释和尾随逗号：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    },\n    \"chrome-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"@modelcontextprotocol/server-chrome-devtools\"]\n    }\n  }\n}\n```\n\n## 命令行用法\n\n### 常用命令\n\n| 命令 | 说明 |\n|------|------|\n| `mcporter list` | 列出所有已配置的 MCP 服务器及其工具 |\n| `mcporter call <server>.<tool>` | 调用指定服务器的指定工具 |\n| `mcporter generate-cli` | 从 MCP 服务器生成独立的 CLI |\n| `mcporter emit-ts` | 生成 TypeScript 类型定义 |\n| `mcporter inspect-cli` | 检查已生成的 CLI 元数据 |\n\n### 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config <path>` | 指定配置文件路径（默认 `./config/mcporter.json`） |\n| `--root <path>` | 设置 stdio 命令的工作目录 |\n| `--log-level <level>` | 日志级别：`debug`、`info`、`warn`、`error` |\n| `--oauth-timeout <ms>` | OAuth 浏览器等待超时 |\n| `--output <format>` | 输出格式：`json` 或美化输出 |\n\n资料来源：[README.md](), [src/cli/config/help.ts]()\n\n## 编程接口\n\n### One-shot 调用\n\n适合单次执行任务的场景：\n\n```typescript\nimport { callOnce } from 'mcporter';\n\nconst result = await callOnce({\n  server: 'firecrawl',\n  toolName: 'crawl',\n  args: { url: 'https://anthropic.com' },\n});\n\nconsole.log(result);\n```\n\n`callOnce` 会自动发现服务器、处理 OAuth 认证并在完成后关闭传输。资料来源：[README.md]()\n\n### 运行时 API\n\n适合需要多次调用或高级配置的场景：\n\n```typescript\nimport { createRuntime } from 'mcporter';\n\nconst runtime = await createRuntime();\n\nconst tools = await runtime.listTools('context7');\nconst result = await runtime.callTool('context7', 'resolve-library-id', {\n  args: { query: 'React hooks docs', libraryName: 'react' },\n});\n\nawait runtime.close();\n```\n\n### 生成类型化客户端\n\n#### 仅生成类型定义\n\n```bash\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n```\n\n#### 生成客户端包装器\n\n```bash\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n可用选项：\n\n| 选项 | 说明 |\n|------|------|\n| `--mode types` | 仅生成 `.d.ts` 接口（默认） |\n| `--mode client` | 生成 `.d.ts` 和 `.ts` 包装器 |\n| `--include-optional` | 展开所有可选字段 |\n| `--json` | 输出结构化摘要（用于脚本） |\n\n资料来源：[README.md](), [docs/emit-ts.md]()\n\n## OAuth 认证配置\n\n### OAuth 选项\n\n| 选项 | 说明 |\n|------|------|\n| `--oauth-client-id <id>` | 使用预注册的 OAuth 客户端 ID |\n| `--oauth-client-secret-env <env>` | 从环境变量读取客户端密钥 |\n| `--oauth-redirect-url <url>` | 设置自定义重定向 URL |\n| `--token-cache-dir <path>` | 覆盖 OAuth 令牌持久化位置 |\n\n### 清除认证\n\n```bash\nmcporter config logout <server-name>\n```\n\n资料来源：[README.md](), [src/cli/config/help.ts]()\n\n## 生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 说明 |\n|------|------|\n| `ephemeral` | 每次调用后自动终止服务器（默认） |\n| `keep-alive` | 保持服务器运行，复用连接 |\n\n可通过配置文件或命令行设置：\n\n```json\n{\n  \"mcpServers\": {\n    \"example\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"example-server\"],\n      \"lifecycle\": \"keep-alive\"\n    }\n  }\n}\n```\n\n资料来源：[src/lifecycle.ts]()\n\n## 工具列表与调用\n\n### 列出服务器工具\n\n```bash\n# 列出所有服务器的工具\nmcporter list\n\n# 列出单个服务器的详细工具信息\nmcporter list context7\n\n# 输出 JSON 格式\nmcporter list --json\n```\n\n### 调用工具\n\n```bash\n# 基本调用\nmcporter call context7.resolve-library-id --args query=\"React hooks\"\n\n# 使用参数文件\nmcporter call server.tool --args-file params.json\n\n# 保存图片输出\nmcporter call server.tool --save-images ./output-dir\n```\n\n参数值默认会自动转换类型。使用 `--raw-strings` 可保持原始字符串格式，`--no-coerce` 可禁用所有类型转换。资料来源：[README.md](), [src/cli/list-command.ts]()\n\n## 故障排除\n\n### 常见问题\n\n1. **服务器连接超时**\n   - 检查网络连接\n   - 使用 `--log-level debug` 查看详细日志\n   - 调整 `--oauth-timeout` 值\n\n2. **OAuth 认证失败**\n   - 确认浏览器可以打开重定向 URL\n   - 检查 `--oauth-redirect-url` 配置\n   - 清除旧的认证：`mcporter config logout <server>`\n\n3. **配置找不到**\n   - 使用 `--config <path>` 指定配置文件\n   - 使用 `mcporter config list` 查看已加载的配置\n\n### 日志调试\n\n```bash\nmcporter list --log-level debug --tail-log\n```\n\n`--tail-log` 选项会流式输出相关日志文件的最后 20 行。资料来源：[README.md]()\n\n---\n\n<a id='page-quick-start'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[CLI 命令参考](#page-cli-reference), [工具调用语法](#page-call-syntax), [配置管理](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n</details>\n\n# 快速入门\n\nmcporter 是一个强大的 MCP（Model Context Protocol）客户端工具，提供命令行界面来管理、调用和调试 MCP 服务器。本指南将帮助您快速掌握 mcporter 的核心功能，从安装配置到日常使用。\n\n## 安装与基础配置\n\n### 安装方式\n\nmcporter 支持多种包管理器安装方式，开发者可根据项目环境选择最适合的方案：\n\n| 包管理器 | 安装命令 |\n|---------|---------|\n| pnpm | `pnpm add -g mcporter` |\n| npm | `npm install -g mcporter` |\n| npx | `npx mcporter` |\n\n资料来源：[README.md:1-15]()\n\n### 配置文件位置\n\nmcporter 默认使用 `./config/mcporter.json` 作为配置文件，同时也支持 JSONC 格式，允许使用 `//` 和 `/* ... */` 注释以及尾随逗号。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\",\n      }\n    }\n  }\n}\n```\n\n资料来源：[README.md:45-60]()\n\n### 常用命令行参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--config <path>` | 指定配置文件路径 | `./config/mcporter.json` |\n| `--root <path>` | 设置 stdio 命令的工作目录 | 当前目录 |\n| `--log-level <level>` | 日志级别（debug/info/warn/error） | 参考 `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 浏览器等待超时 | 参考 `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--output <format>` | 输出格式控制 | 自动检测 |\n| `--raw` | 原始输出，不进行格式化 | - |\n\n资料来源：[README.md:20-35]()\n\n## 列出可用服务器与工具\n\n### 基础列表命令\n\n使用 `mcporter list` 命令查看所有已配置的 MCP 服务器及其状态：\n\n```bash\nmcporter list\n```\n\n该命令会检查每个服务器的可访问性，并显示工具数量、连接耗时和状态信息。状态分类包括：\n\n| 状态类别 | 说明 | 颜色标识 |\n|---------|------|---------|\n| `ok` | 服务器正常响应 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 蓝色 |\n| `error` | 连接错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:1-30]()\n\n### 查看特定服务器的工具\n\n当您指定服务器名称时，mcporter 会显示该服务器的所有可用工具及其详细签名：\n\n```bash\nmcporter list <server>\nmcporter list context7\n```\n\n工具详情包括：\n- **工具名称**：MCP 服务器暴露的函数名\n- **输入模式（Input Schema）**：参数定义，包含类型和约束\n- **描述信息**：工具功能说明\n- **示例调用**：常用参数组合示例\n\n资料来源：[src/cli/list-command.ts:1-50]()\n\n### 过滤工具输出\n\n| 过滤选项 | 说明 |\n|---------|------|\n| `--brief` | 仅显示简要签名 |\n| `--signatures` | 显示紧凑签名 |\n| `--required-only` | 仅显示必需参数 |\n| `--all-parameters` | 显示所有参数（包括可选） |\n| `--schema` | 显示完整 JSON Schema |\n\n```bash\n# 简要输出\nmcporter list context7 --brief\n\n# 显示所有参数\nmcporter list context7 --all-parameters\n\n# 指定特定工具\nmcporter list context7.shadcn_getComponents\n```\n\n资料来源：[src/cli/list-command.ts:50-100]()\n\n## 调用 MCP 工具\n\n### 基础调用语法\n\n使用 `mcporter call` 命令调用服务器上的工具：\n\n```bash\nmcporter call <server>.<tool> [参数...]\nmcporter call context7.resolve-library library_name=\"shadcn\"\n```\n\nmcporter 会自动处理：\n- 参数类型转换（布尔值、数字、JSON）\n- 必需参数验证\n- 位置参数到命名参数的映射\n\n资料来源：[src/cli/call-command.ts:1-40]()\n\n### 参数传递方式\n\n#### 命名参数\n\n```bash\n# 使用 key=value 格式\nmcporter call server.tool arg1=value1 arg2=value2\n\n# 使用 key:value 格式\nmcporter call server.tool arg1:value1 arg2:value2\n```\n\n#### 位置参数\n\n当工具参数按声明顺序传递时，mcporter 会根据工具的输入模式自动匹配：\n\n```bash\nmcporter call context7.resolve-library shadcn\n```\n\n如果位置参数数量超过剩余必需参数数量，命令会报错并提示正确的参数数量。\n\n资料来源：[src/cli/call-command.ts:40-80]()\n\n### 参数类型处理\n\nmcporter 支持智能类型推断：\n\n| 输入格式 | 推断类型 | 示例 |\n|---------|---------|------|\n| `true` / `false` | 布尔值 | `enabled=true` |\n| `123` / `3.14` | 数字 | `count=42` |\n| `\"text\"` 或 `'text'` | 字符串 | `name=\"test\"` |\n| `{...}` / `[...]` | JSON 对象/数组 | `config={\"key\":1}` |\n| 不符合以上格式 | 字符串 | `text=abc` |\n\n使用 `--no-coerce` 可禁用类型推断，保持所有值为原始字符串。\n\n```bash\n# 禁用类型转换\nmcporter call server.tool --no-coerce arg1=value1\n```\n\n资料来源：[src/cli/call-command.ts:80-120]()\n\n### 处理工具输出\n\n`mcporter call` 返回的结果封装在 `CallResult` 对象中，支持多种访问方式：\n\n| 方法 | 说明 | 返回类型 |\n|-----|------|---------|\n| `.text()` | 获取纯文本内容 | `string \\| null` |\n| `.markdown()` | 获取 Markdown 内容 | `string \\| null` |\n| `.json()` | 解析 JSON 内容 | `object \\| null` |\n| `.images()` | 获取图片内容 | `ImageContent[] \\| null` |\n| `.content()` | 获取原始内容项 | `ContentBlock[]` |\n| `.raw` | 获取完整响应信封 | `CallResponse` |\n\n```bash\n# 格式化输出（默认）\nmcporter call context7.resolve-library library_name=\"shadcn\"\n\n# 原始输出\nmcporter call context7.resolve-library --raw library_name=\"shadcn\"\n\n# JSON 格式\nmcporter call context7.resolve-library --json library_name=\"shadcn\"\n```\n\n资料来源：[src/result-utils.ts:1-50]()\n\n### 保存图片内容\n\n某些 MCP 工具会返回图片内容，使用 `--save-images` 参数可以将其保存到指定目录：\n\n```bash\nmcporter call server.tool --save-images ./output_dir arg1=value1\n```\n\n图片会按工具响应中的顺序编号保存，输出形状保持不变。\n\n资料来源：[README.md:30-35]()\n\n## 服务器生命周期管理\n\nmcporter 支持不同的服务器生命周期模式，决定工具调用后服务器的运行行为：\n\n| 生命周期模式 | 说明 | 配置方式 |\n|------------|------|---------|\n| `ephemeral` | 调用后立即关闭（默认） | `lifecycle: \"ephemeral\"` |\n| `keep-alive` | 保持运行状态 | `lifecycle: \"keep-alive\"` |\n| `keep-alive` + `idleTimeoutMs` | 空闲超时后关闭 | `lifecycle: { mode: \"keep-alive\", idleTimeoutMs: 60000 }` |\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"some-mcp-server\"],\n      \"lifecycle\": {\n        \"mode\": \"keep-alive\",\n        \"idleTimeoutMs\": 300000\n      }\n    }\n  }\n}\n```\n\n资料来源：[src/lifecycle.ts:1-30]()\n\n### 动态端口处理\n\n某些服务器（如 chrome-devtools）需要动态分配端口。mcporter 会自动检测并处理以下场景：\n\n- 检测命令参数中的端口占位符\n- 在运行时分配可用端口\n- 将端口信息传递给子进程\n\n## 配置管理\n\n### 交互式配置命令\n\n使用 `mcporter config` 子命令进行配置管理：\n\n| 子命令 | 说明 |\n|-------|------|\n| `config list` | 列出本地配置 |\n| `config get <name>` | 获取配置项详情 |\n| `config add <name>` | 添加新配置 |\n| `config remove <name>` | 删除配置 |\n| `config import <kind>` | 导入其他编辑器的配置 |\n| `config logout <name>` | 清除认证信息 |\n\n```bash\n# 查看所有配置\nmcporter config list\n\n# 获取特定配置\nmcporter config get context7\n\n# 添加新服务器\nmcporter config add my-server --command \"npx\" --arg \"-y\" --arg \"my-mcp-server\"\n\n# 导入其他编辑器的配置\nmcporter config import cursor --copy\n```\n\n资料来源：[src/cli/config/help.ts:1-50]()\n\n### 配置查找与自动补全\n\nmcporter 使用模糊匹配来查找服务器名称，即使输入有拼写错误也能找到正确的配置：\n\n```bash\n# 错误拼写会自动纠正\nmcporter list sshadcn\n# 输出: sshadcn → shadcn (自动纠正提示)\n\n# 服务器选择器支持 .tool 语法\nmcporter list context7.resolve-library\n```\n\n资料来源：[src/cli/list-command.ts:100-150]()\n\n### 多环境配置\n\n支持使用 `--config` 和 `--root` 参数切换不同的配置环境：\n\n```bash\n# 使用项目级配置\nmcporter list --config ./project/config/mcporter.json\n\n# 设置工作目录\nmcporter call server.tool --root /path/to/project arg1=value1\n```\n\n## 生成工具客户端\n\n### 生成 TypeScript 类型定义\n\n使用 `emit-ts` 命令生成强类型工具接口：\n\n```bash\n# 仅生成类型定义\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成带客户端包装器\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n| 模式 | 输出 | 说明 |\n|-----|------|------|\n| `types`（默认） | `.d.ts` | 仅包含 Promise 签名的接口 |\n| `client` | `.d.ts` + `.ts` | 包含类型定义和 `createRuntime`/`createServerProxy` 包装器 |\n\n附加选项：\n- `--include-optional`：展开所有可选字段\n- `--json`：输出结构化摘要而非纯文本\n\n资料来源：[README.md:100-120]()\n\n### 生成独立 CLI 工具\n\n将 MCP 服务器转换为独立的可分发 CLI：\n\n```bash\n# 从 URL 生成\nnpx mcporter generate-cli --command https://mcp.context7.com/mcp\n\n# 从 npm 包生成\nnpx mcporter generate-cli \"npx -y chrome-devtools-mcp@latest\"\n\n# 指定输出名称\nnpx mcporter generate-cli --command https://mcp.context7.com/mcp --name context7\n```\n\n生成的工件包含：\n- `context7.ts`：TypeScript 模板 + 嵌入的 schema\n- `context7.js`：打包后的 CLI（使用 Rolldown 或 Bun）\n\n```bash\n# 检查已生成的 CLI\nnpx mcporter inspect-cli dist/context7.js\n\n# 重新生成（使用嵌入的元数据）\nnpx mcporter generate-cli --from dist/context7.js\n```\n\n资料来源：[README.md:80-100]()\n\n## 常见工作流程\n\n### 流程图：基础调用流程\n\n```mermaid\ngraph TD\n    A[开始] --> B[配置 mcporter.json]\n    B --> C[运行 mcporter list]\n    C --> D{服务器可用?}\n    D -->|是| E[运行 mcporter call]\n    D -->|否| F[检查配置和网络]\n    F --> C\n    E --> G[解析 CallResult]\n    G --> H[提取所需格式]\n    H --> I[结束]\n```\n\n### 流程图：工具调用处理\n\n```mermaid\ngraph TD\n    A[mcporter call 命令] --> B[解析参数]\n    B --> C{使用 --no-coerce?}\n    C -->|是| D[保持字符串类型]\n    C -->|否| E[智能类型推断]\n    E --> F[验证必需参数]\n    F --> G{参数完整?}\n    G -->|否| H[显示错误信息]\n    G -->|是| I[构建 MCP 请求]\n    I --> J[发送请求到服务器]\n    J --> K[接收响应]\n    K --> L[包装为 CallResult]\n    L --> M[返回给调用者]\n```\n\n### 典型使用场景\n\n#### 场景一：快速查询文档\n\n```bash\n# 1. 列出可用服务器\nmcporter list\n\n# 2. 查看特定服务器工具\nmcporter list context7\n\n# 3. 调用文档查询工具\nmcporter call context7.resolve-library library_name=\"shadcn\"\n```\n\n#### 场景二：调试 MCP 服务器\n\n```bash\n# 使用 verbose 模式查看详细信息\nmcporter list context7 --verbose\n\n# 启用调试日志\nmcporter list --log-level debug\n\n# 查看日志尾随内容\nmcporter call server.tool --tail-log\n```\n\n#### 场景三：自动化脚本集成\n\n```bash\n#!/bin/bash\n# 批量调用脚本\n\nSERVERS=(\"context7\" \"shadcn\" \"linear\")\nfor server in \"${SERVERS[@]}\"; do\n    echo \"检查服务器: $server\"\n    mcporter list \"$server\" --json | jq -r '.status'\ndone\n```\n\n## 故障排除\n\n### 常见问题与解决方案\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 连接超时 | 服务器未启动或网络问题 | 检查 `--timeout` 设置，使用 `--tail-log` 查看日志 |\n| 认证失败 | OAuth token 过期 | 运行 `mcporter config logout <name>` 后重新认证 |\n| 工具未找到 | 名称拼写错误或服务器未启动 | 使用 `mcporter list` 确认工具存在 |\n| 参数类型错误 | 字符串被错误解析为数字 | 使用 `--no-coerce` 或显式使用引号 |\n\n### 调试模式\n\n启用详细日志进行问题排查：\n\n```bash\n# 设置日志级别\nexport MCPORTER_LOG_LEVEL=debug\n\n# 运行命令\nmcporter call server.tool arg=value\n\n# 或直接在命令中指定\nmcporter call server.tool arg=value --log-level debug\n```\n\n使用 `--tail-log` 查看关联的日志文件：\n\n```bash\nmcporter call server.tool --tail-log\n```\n\n## 下一步\n\n- 阅读 [配置参考文档](docs/config.md) 了解更多配置选项\n- 查看 [Agent Skills 指南](docs/agent-skills.md) 了解如何为 AI Agent 创建技能\n- 参考 [emit-ts 文档](docs/emit-ts.md) 生成强类型客户端\n\n---\n\n<a id='page-core-architecture'></a>\n\n## 核心架构\n\n### 相关页面\n\n相关主题：[运行时系统](#page-runtime-system), [传输层](#page-transport-layer), [配置管理](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n- [src/cli.ts](https://github.com/steipete/mcporter/blob/main/src/cli.ts)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n</details>\n\n# 核心架构\n\nmcporter 是一个用于管理 MCP（Model Context Protocol）服务器的 CLI 工具，其核心架构围绕配置管理、运行时生命周期、CLI 命令解析和结果处理四大模块展开。\n\n## 架构总览\n\nmcporter 的设计采用了分层架构模式，核心组件包括：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| CLI 层 | `src/cli.ts` | 命令行入口、参数解析、路由分发 |\n| 命令层 | `src/cli/list-command.ts` | list/list-format/list-output 子系统 |\n| 配置层 | `src/config/` | 配置读取、规范化、导入 |\n| 运行时层 | `src/runtime.ts` | MCP 服务器生命周期管理 |\n| 工具层 | `src/lifecycle.ts` | 服务端生命周期控制 |\n\n## 配置管理模块\n\n### 配置解析流程\n\n配置管理模块负责加载和规范化用户配置。mcporter 支持多种配置格式，包括 `mcporter.json` 和 `mcporter.jsonc`（支持注释和尾随逗号的 JSON）。\n\n### 配置导入机制\n\n外部配置导入功能支持从多种编辑器配置中读取 MCP 服务器定义：\n\n```typescript\n// 支持的配置容器\n{\n  allowMcpServers: true,   // 标准 mcpServers\n  allowServers: true,      // servers 容器\n  allowMcp: true,          // mcp 容器\n  allowRootFallback: true  // 根目录回退\n}\n```\n\n资料来源：[src/config/imports/external.ts:15-25]()\n\n对于 Claude Code 配置，有特殊的路径规范化逻辑：\n\n```typescript\nconst allowRootFallback =\n  normalized.endsWith('.claude.json') || \n  normalized.endsWith(`${path.sep}.claude${path.sep}mcp.json`);\n```\n\n资料来源：[src/config/imports/external.ts:11-14]()\n\n### 配置值转换\n\n配置导入模块提供了类型安全的数据转换工具：\n\n| 函数 | 作用 |\n|------|------|\n| `asString()` | 提取非空字符串值 |\n| `asStringRecord()` | 将混合类型对象转换为字符串记录 |\n| `shouldIgnoreParseError()` | 判断是否应忽略解析错误 |\n\n资料来源：[src/config/imports/external.ts:40-62]()\n\n## 生命周期管理\n\n### 生命周期模式\n\nmcporter 支持两种服务端生命周期模式：\n\n```mermaid\ngraph TD\n    A[MCP 服务器定义] --> B{生命周期模式}\n    B -->|keep-alive| C[持续运行]\n    B -->|ephemeral| D[按需启动]\n    C --> E[idleTimeoutMs 配置]\n    D --> F[调用后终止]\n```\n\n资料来源：[src/lifecycle.ts:45-50]()\n\n生命周期序列化函数 `serializeLifecycle` 处理以下返回值格式：\n\n```typescript\n// 三种序列化形式\n'keep-alive'                                    // 无超时\n{ mode: 'keep-alive', idleTimeoutMs?: number }  // 带超时\n'ephemeral'                                     // 临时模式\n```\n\n资料来源：[src/cli/adhoc-server.ts:89-97]()\n\n### 动态端口检测\n\n对于 Chrome DevTools 相关的 MCP 服务器，mcporter 支持动态端口分配：\n\n```typescript\nconst CHROME_DEVTOOLS_URL_PLACEHOLDERS = [\n  '__MCP_PORT_3000__',\n  '__MCP_PORT_9222__',\n  // ...其他占位符\n];\n\nfunction commandRequiresDynamicChromePort(command: CommandSpec): boolean {\n  if (command.kind !== 'stdio') {\n    return false;\n  }\n  const tokens = [command.command, ...command.args];\n  return tokens.some((token) => \n    CHROME_DEVTOOLS_URL_PLACEHOLDERS.some(\n      (placeholder) => token.includes(placeholder)\n    )\n  );\n}\n```\n\n资料来源：[src/lifecycle.ts:19-33]()\n\n### Keep-Alive 命令识别\n\nmcporter 内置了对常见持续运行命令的识别：\n\n```typescript\nconst KEEP_ALIVE_COMMANDS = [\n  { label: 'docker', fragments: ['docker'] },\n  { label: 'npx', fragments: ['npx', 'npm exec'] },\n  // ...更多命令模式\n];\n\nfunction commandRequiresKeepAlive(command: CommandSpec): string | undefined {\n  if (command.kind !== 'stdio') {\n    return undefined;\n  }\n  const tokens = [command.command, ...command.args].map(\n    (token) => token.toLowerCase()\n  );\n  const match = KEEP_ALIVE_COMMANDS.find((signature) =>\n    signature.fragments.some((fragment) =>\n      tokens.some((token) => token.includes(fragment))\n    )\n  );\n  return match?.label;\n}\n```\n\n资料来源：[src/lifecycle.ts:6-18]()\n\n### 覆盖集合解析\n\n配置中的覆盖设置使用集合匹配机制：\n\n```typescript\nfunction parseList(value: string | undefined): OverrideSet {\n  if (!value) {\n    return { all: false, names: new Set() };\n  }\n  const names = value\n    .split(',')\n    .map((token) => token.trim().toLowerCase())\n    .filter((token) => token.length > 0);\n  \n  if (names.includes('*')) {\n    return { all: true, names: new Set() };\n  }\n  return { all: false, names: new Set(names) };\n}\n\nfunction matchesOverride(names: Set<string>, candidates: Set<string>): boolean {\n  for (const candidate of candidates) {\n    if (names.has(candidate)) {\n      return true;\n    }\n  }\n  return false;\n}\n```\n\n资料来源：[src/lifecycle.ts:35-62]()\n\n## CLI 命令系统\n\n### 命令路由\n\nCLI 入口点 `src/cli.ts` 负责将命令行参数路由到相应的处理函数：\n\n```mermaid\ngraph TD\n    A[CLI 入口] --> B[命令解析]\n    B --> C{命令类型}\n    C -->|list| D[list-command.ts]\n    C -->|call| E[call-command.ts]\n    C -->|config| F[config 子系统]\n    C -->|generate-cli| G[CLI 生成]\n    C -->|emit-ts| H[类型导出]\n    C -->|inspect-cli| I[CLI 检查]\n```\n\n### 工具选择器解析\n\n`list-command.ts` 实现了智能工具选择器解析，支持 `server.tool` 格式的直接调用：\n\n```typescript\nfunction resolveConfiguredToolSelector(\n  runtime: Runtime,\n  target: string | undefined\n): { server: string; tool: string } | undefined {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  const definitions = runtime.getDefinitions();\n  const match = definitions\n    .map((definition) => definition.name)\n    .filter((name) => target.startsWith(`${name}.`))\n    .toSorted((a, b) => b.length - a.length)[0];\n  \n  if (!match) {\n    return undefined;\n  }\n  const tool = target.slice(match.length + 1);\n  if (!tool) {\n    return undefined;\n  }\n  return { server: match, tool };\n}\n```\n\n资料来源：[src/cli/list-command.ts:90-109]()\n\n### 服务器定义解析\n\n解析流程如下：\n\n1. 检查目标是否为配置的 `server.tool` 格式\n2. 尝试从运行时获取服务器定义\n3. 解析超时配置\n4. 格式化传输层摘要\n\n```typescript\nconst resolved = resolveServerDefinition(runtime, target);\nif (!resolved) {\n  return;\n}\ntarget = resolved.name;\nconst definition = resolved.definition;\nconst timeoutMs = flags.timeoutMs ?? LIST_TIMEOUT_MS;\n```\n\n资料来源：[src/cli/list-command.ts:40-50]()\n\n## 列表输出系统\n\n### 状态分类\n\nmcporter 使用标准化的状态分类系统：\n\n```typescript\ntype StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';\n\nexport function createEmptyStatusCounts(): Record<StatusCategory, number> {\n  return {\n    ok: 0,\n    auth: 0,\n    offline: 0,\n    http: 0,\n    error: 0,\n  };\n}\n```\n\n资料来源：[src/cli/list-output.ts:42-50]()\n\n### 列表格式化\n\n列表格式化模块负责生成用户友好的输出：\n\n```typescript\nexport function truncateForSpinner(text: string, maxLength = 72): string {\n  if (text.length <= maxLength) {\n    return text;\n  }\n  return `${text.slice(0, Math.max(0, maxLength - 1))}…`;\n}\n```\n\n资料来源：[src/cli/list-format.ts:29-34]()\n\n### 工具元数据过滤\n\n支持按工具名称过滤返回的元数据：\n\n```typescript\nfunction filterToolMetadata(\n  entries: ToolMetadata[], \n  requestedTool: string | undefined\n): ToolMetadata[] {\n  if (!requestedTool) {\n    return entries;\n  }\n  return entries.filter((entry) => entry.tool.name === requestedTool);\n}\n```\n\n资料来源：[src/cli/list-command.ts:111-117]()\n\n## 结果处理系统\n\n### 内容类型提取\n\n`result-utils.ts` 实现了复杂的内容解析逻辑：\n\n```mermaid\ngraph TD\n    A[CallResult] --> B{内容类型判断}\n    B -->|text| C[textEntries]\n    B -->|markdown| D[markdownEntries + textEntries]\n    B -->|image| E[images]\n    B -->|resource| F[资源处理]\n    B -->|JSON| G[jsonCandidates]\n```\n\n### 资源负载收集\n\n```typescript\nfunction collectResourcePayload(\n  resource: unknown,\n  textEntries: string[],\n  markdownEntries: string[],\n  jsonCandidates: unknown[]\n): void {\n  if (!resource || typeof resource !== 'object') {\n    return;\n  }\n  const record = resource as Record<string, unknown>;\n  const mimeType = typeof record.mimeType === 'string' \n    ? record.mimeType \n    : '';\n  \n  if (typeof record.text === 'string') {\n    textEntries.push(record.text);\n    if (mimeType.toLowerCase().includes('markdown')) {\n      markdownEntries.push(record.text);\n    }\n    const parsed = tryParseJson(record.text);\n    if (parsed !== null) {\n      jsonCandidates.push(parsed);\n    }\n  } else if (typeof record.blob === 'string') {\n    textEntries.push(`[Binary resource: ${uri}]`);\n  }\n}\n```\n\n资料来源：[src/result-utils.ts:77-101]()\n\n### JSON 信封展开\n\n支持从标准信封格式中提取 JSON 数据：\n\n```typescript\nfunction unwrapJsonEnvelope(\n  record: Record<string, unknown>, \n  fallback: unknown\n): unknown {\n  if ('json' in record) {\n    return record.json ?? null;\n  }\n  if ('data' in record) {\n    return Object.keys(record).length === 1 \n      ? (record.data ?? null) \n      : fallback;\n  }\n  return null;\n}\n```\n\n资料来源：[src/result-utils.ts:111-121]()\n\n## 临时服务器管理\n\n### Ad-hoc 服务器解析\n\nmcporter 支持通过命令行直接定义临时 MCP 服务器：\n\n```mermaid\ngraph TD\n    A[--stdio 命令字符串] --> B[引号解析]\n    B --> C[命令+参数分离]\n    C --> D[生命周期决定]\n    D --> E[序列化配置]\n    E --> F[运行时注册]\n```\n\n### 命令字符串解析\n\n实现了完整的 shell 风格引号解析：\n\n```typescript\nfunction parseStdioCommand(input: string): string[] {\n  const result: string[] = [];\n  let current = '';\n  let inSingle = false;\n  let inDouble = false;\n  \n  for (let i = 0; i < input.length; i += 1) {\n    const char = input[i];\n    \n    if (char === '\\\\' && !inSingle) {\n      // 转义处理\n      continue;\n    }\n    \n    if (char === \"'\" && !inDouble) {\n      inSingle = !inSingle;\n      continue;\n    }\n    if (char === '\"' && !inSingle) {\n      inDouble = !inDouble;\n      continue;\n    }\n    // ...\n  }\n  \n  return result;\n}\n```\n\n资料来源：[src/cli/adhoc-server.ts:40-75]()\n\n## 环境变量控制\n\nmcporter 通过环境变量支持运行时行为控制：\n\n| 环境变量 | 作用 | 默认值 |\n|----------|------|--------|\n| `MCPORTER_LOG_LEVEL` | 日志级别 | info |\n| `MCPORTER_OAUTH_TIMEOUT_MS` | OAuth 超时 | 60000 |\n| `MCPORTER_DISABLE_KEEPALIVE` | 禁用 keep-alive | - |\n| `MCPORTER_NO_KEEPALIVE` | 同上（兼容） | - |\n\n```typescript\nfunction isFastPathKeepAliveDisabled(server: string): boolean {\n  const raw = process.env.MCPORTER_DISABLE_KEEPALIVE \n    ?? process.env.MCPORTER_NO_KEEPALIVE;\n  \n  if (!raw) {\n    return false;\n  }\n  \n  const disabled = new Set(\n    raw\n      .split(',')\n      .map((entry) => entry.trim().toLowerCase())\n      .filter(Boolean)\n  );\n  \n  return disabled.has('*') || disabled.has(server.toLowerCase());\n}\n```\n\n资料来源：[src/cli.ts:89-104]()\n\n## 数据流图\n\n### 列表命令完整数据流\n\n```mermaid\nsequenceDiagram\n    participant CLI as CLI 入口\n    participant Parse as 参数解析\n    participant Runtime as 运行时\n    participant Server as MCP 服务器\n    participant Format as 格式化输出\n    \n    CLI->>Parse: mcporter list [server]\n    Parse->>Runtime: 获取服务器定义\n    Runtime->>Server: 建立连接\n    Server-->>Runtime: 工具元数据\n    Runtime-->>Format: ListSummaryResult\n    Format->>Format: 状态分类\n    Format->>Format: 格式化输出\n    Format-->>CLI: 控制台输出\n```\n\n### 结果处理流程\n\n```mermaid\ngraph LR\n    A[Tool Call Response] --> B[类型检测]\n    B -->|文本| C[收集文本]\n    B -->|图片| D[收集图片]\n    B -->|资源| E[收集资源]\n    B -->|JSON| F[JSON 候选]\n    C --> G[合并输出]\n    D --> G\n    E --> G\n    F --> G\n    G --> H[CallResult]\n```\n\n## 错误处理策略\n\nmcporter 实现了多层次的错误处理机制：\n\n1. **超时处理**：通过 `withTimeout` 包装异步操作\n2. **认证错误分类**：区分 auth/offline/http/error 状态\n3. **解析容错**：对可忽略的解析错误进行特殊处理\n4. **类型安全转换**：使用 `asString()` 等工具函数避免类型错误\n\n```typescript\nfunction shouldIgnoreParseError(error: unknown): boolean {\n  if (error instanceof SyntaxError) {\n    return true;\n  }\n  if (!error || typeof error !== 'object') {\n    return false;\n  }\n  return 'fromTOML' in error;\n}\n```\n\n资料来源：[src/config/imports/external.ts:64-71]()\n\n## 扩展性设计\n\nmcporter 的架构设计支持多种扩展方式：\n\n1. **新命令添加**：在 `src/cli.ts` 中注册新命令处理器\n2. **配置格式扩展**：在 `src/config/imports/` 下添加新的导入器\n3. **输出格式扩展**：在 `src/cli/` 下添加新的格式化器\n4. **生命周期模式**：在 `src/lifecycle.ts` 中定义新的生命周期处理\n\n---\n\n<a id='page-runtime-system'></a>\n\n## 运行时系统\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [传输层](#page-transport-layer), [工具调用语法](#page-call-syntax)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/runtime.ts](https://github.com/steipete/mcporter/blob/main/src/runtime.ts)\n- [src/runtime/utils.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/utils.ts)\n- [src/runtime/errors.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/errors.ts)\n- [src/server-proxy.ts](https://github.com/steipete/mcporter/blob/main/src/server-proxy.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n</details>\n\n# 运行时系统\n\n## 概述\n\nmcporter 的**运行时系统**是整个工具调用框架的核心子系统，负责 MCP 服务器的创建、管理、工具调用及生命周期控制。该系统封装了与 MCP 服务器的通信细节，提供统一的运行时抽象，使 CLI 命令能够以一致的方式与不同类型的 MCP 服务器交互。\n\n运行时系统的主要职责包括：\n\n- **服务器运行时创建与管理**：通过 `createRuntime` 工厂函数实例化服务器运行时\n- **工具元数据加载**：获取 MCP 服务器提供的工具列表及参数模式\n- **工具调用执行**：将工具调用请求路由到目标服务器并处理响应\n- **生命周期管理**：支持 keep-alive 和 ephemeral 两种运行模式\n- **结果解析与格式化**：从服务器响应中提取文本、图像、JSON 等内容\n\n资料来源：[src/cli/list-command.ts:18-30]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n    subgraph \"运行时系统核心\"\n        RT[运行时实例]\n        SP[服务器代理 ServerProxy]\n        LC[生命周期管理器]\n        EU[结果工具]\n    end\n    \n    subgraph \"外部接口\"\n        CLI[CLI 命令层]\n        API[导出 API]\n    end\n    \n    subgraph \"服务器定义\"\n        DEF[ServerDefinition]\n        META[ToolMetadata]\n    end\n    \n    CLI --> RT\n    API --> RT\n    RT --> SP\n    RT --> LC\n    SP --> DEF\n    RT --> EU\n    EU --> META\n```\n\n### 运行时创建流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as CLI 命令\n    participant RT as createRuntime\n    participant SP as ServerProxy\n    participant DEF as ServerDefinition\n    participant LC as Lifecycle\n    \n    CLI->>RT: 创建运行时请求\n    RT->>DEF: 解析服务器定义\n    DEF-->>RT: 定义配置\n    RT->>LC: 初始化生命周期\n    LC-->>RT: 生命周期状态\n    RT->>SP: 创建服务器代理\n    SP-->>RT: 代理实例\n    RT-->>CLI: 运行时句柄\n```\n\n资料来源：[src/runtime.ts]()\n\n## 核心数据类型\n\n### ServerDefinition\n\n服务器定义是运行时系统的核心配置单元，描述单个 MCP 服务器的连接参数：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 服务器唯一标识名称 |\n| `command` | `CommandSpec` | 启动命令配置（stdio/http/sse） |\n| `description` | `string?` | 服务器描述文本 |\n| `source` | `ServerSource` | 配置来源（本地/导入/HTTP） |\n| `sources` | `readonly ServerSource[]?` | 多源配置 |\n| `lifecycle` | `ServerLifecycle?` | 生命周期模式 |\n| `auth` | `AuthConfig?` | 认证配置 |\n\n资料来源：[src/server-proxy.ts]()\n\n### ToolMetadata\n\n工具元数据描述 MCP 服务器暴露的单个工具：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 工具名称 |\n| `description` | `string` | 工具功能描述 |\n| `inputSchema` | `JsonSchema` | 输入参数 JSON Schema |\n| `outputSchema` | `JsonSchema?` | 输出结果 JSON Schema |\n\n```typescript\ninterface ToolMetadata {\n  tool: { name: string; description: string };\n  inputSchema: JsonSchema;\n  outputSchema?: JsonSchema;\n}\n```\n\n资料来源：[src/cli/list-command.ts:31-36]()\n\n## 生命周期管理\n\n### 生命周期模式\n\n运行时系统支持两种服务器生命周期模式：\n\n```typescript\ntype ServerLifecycle =\n  | { mode: 'keep-alive'; idleTimeoutMs?: number }\n  | { mode: 'ephemeral' };\n```\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `keep-alive` | 服务器启动后保持运行，可复用连接 | 高频调用、资源充足环境 |\n| `ephemeral` | 每次工具调用后终止服务器 | 低频调用、资源受限环境 |\n\n### keep-alive 命令识别\n\n系统通过签名片段匹配识别需要保持连接的服务器命令：\n\n```typescript\nconst KEEP_ALIVE_COMMANDS = [\n  { label: 'docker', fragments: ['docker', 'run'] },\n  { label: 'npx', fragments: ['npx'] },\n  { label: 'bun', fragments: ['bun', 'x'] },\n  // 更多命令...\n];\n```\n\n当命令包含匹配的签名片段时，系统自动应用 keep-alive 生命周期。\n\n资料来源：[src/lifecycle.ts]()\n\n## 结果解析系统\n\n### ResultUtils 工具模块\n\n`result-utils.ts` 提供的工具函数负责从 MCP 服务器响应中提取结构化数据：\n\n```typescript\nexport interface ExtractedContent {\n  content: unknown;\n  structuredContent: unknown;\n  textEntries: string[];\n  markdownEntries: string[];\n  jsonCandidates: unknown[];\n  images: ImageContent[] | null;\n}\n```\n\n### 内容提取流程\n\n```mermaid\nflowchart TD\n    A[MCP 响应 envelope] --> B{遍历 content 数组}\n    B -->|image 类型| C[提取图像数据]\n    B -->|resource 类型| D[收集资源载荷]\n    B -->|text/markdown| E[文本处理]\n    B -->|其他类型| F[跳过]\n    \n    C --> G[合并图像列表]\n    D --> H[解析 text/blob]\n    E --> I[文本条目收集]\n    \n    H --> J[JSON 解析尝试]\n    I --> J\n    \n    G --> K[返回 ExtractedContent]\n    J --> K\n    K --> K\n```\n\n### 支持的内容类型\n\n| 内容类型 | 处理逻辑 |\n|----------|----------|\n| `text` | 直接添加到 `textEntries` |\n| `markdown` | 添加到 `textEntries` 和 `markdownEntries` |\n| `image` | 提取 data 和 mimeType，添加到 `images` |\n| `resource` | 递归解析 uri、mimeType、text、blob 字段 |\n| 其他 | 跳过处理 |\n\n资料来源：[src/result-utils.ts:1-80]()\n\n## 错误处理机制\n\n### 错误分类系统\n\n运行时系统包含完善的错误分类机制，为不同类型的连接问题提供诊断建议：\n\n```mermaid\nflowchart TD\n    A[错误发生] --> B{错误类型判定}\n    B -->|认证失败| C[auth 错误类别]\n    B -->|网络不可达| D[offline 错误类别]\n    B -->|HTTP 错误| E[http 错误类别]\n    B -->|其他| F[error 错误类别]\n    \n    C --> G[生成 authCommand 提示]\n    D --> H[提供连接检查建议]\n    E --> I[显示 HTTP 状态码]\n    F --> J[通用错误信息]\n```\n\n### 状态类别定义\n\n```typescript\ntype StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';\n```\n\n| 状态 | 含义 | 颜色标识 |\n|------|------|----------|\n| `ok` | 连接成功，工具正常 | 绿色 |\n| `auth` | 认证失败或缺失 | 黄色 |\n| `offline` | 服务器不可达 | 红色 |\n| `http` | HTTP 协议层错误 | 红色 |\n| `error` | 通用运行时错误 | 红色 |\n\n资料来源：[src/runtime/errors.ts](), [src/cli/list-format.ts:25-40]()\n\n## 工具调用流程\n\n### 标准工具调用序列\n\n```mermaid\nsequenceDiagram\n    participant User as 用户/CLI\n    participant RT as Runtime\n    participant SP as ServerProxy\n    participant Server as MCP Server\n    participant Utils as ResultUtils\n    \n    User->>RT: callTool(name, args)\n    RT->>SP: 路由到目标服务器\n    SP->>Server: 发送 JSON-RPC 请求\n    Server-->>SP: 工具响应\n    SP-->>RT: 响应 envelope\n    RT->>Utils: extractContent(envelope)\n    Utils-->>RT: ExtractedContent\n    RT-->>User: 格式化结果\n```\n\n### 工具选择器解析\n\n系统支持 `server.tool` 格式的工具选择器，简化跨服务器工具调用：\n\n```typescript\nfunction resolveConfiguredToolSelector(\n  runtime: Runtime,\n  target: string | undefined\n): { server: string; tool: string } | undefined {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  // 匹配 server.tool 格式\n  const match = definitions\n    .filter((name) => target.startsWith(`${name}.`))\n    .sort((a, b) => b.length - a.length)[0];\n  \n  if (!match) return undefined;\n  const tool = target.slice(match.length + 1);\n  return { server: match, tool };\n}\n```\n\n此函数自动从 `server.tool` 格式中提取服务器名称和工具名称。\n\n资料来源：[src/cli/list-command.ts:45-60]()\n\n## 配置与超时控制\n\n### 超时配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `LIST_TIMEOUT_MS` | 30000ms | 工具列表加载超时 |\n| `MCPORTER_OAUTH_TIMEOUT_MS` | 环境变量控制 | OAuth 流程超时 |\n\n### 运行时超时处理\n\n```typescript\nconst metadataEntries = await withTimeout(\n  loadToolMetadata(runtime, target, {\n    includeSchema: true,\n    autoAuthorize: false,\n    allowCachedAuth: true,\n  }),\n  timeoutMs\n);\n```\n\n工具元数据加载使用 `withTimeout` 包装，确保操作不会无限阻塞。\n\n资料来源：[src/cli/list-command.ts:85-95]()\n\n## 调试支持\n\n### 运行时调试模式\n\n`src/cli/runtime-debug.ts` 提供了详细的进程清理逻辑，用于调试挂起问题：\n\n```typescript\n// 强制销毁 Socket 句柄\nif (ctor === 'Socket' && typeof handle.destroy === 'function') {\n  handle.destroy?.();\n  handle.unref?.();\n}\n\n// 清理子进程 stdio\ncandidate.stdout?.destroy?.();\ncandidate.stderr?.destroy?.();\ncandidate.stdin?.end?.();\n\n// 可选强制 SIGKILL\nif (DEBUG_HANG) {\n  candidate.kill?.('SIGKILL');\n}\n```\n\n当启用 `DEBUG_HANG` 环境变量时，系统会记录详细的进程终止信息。\n\n资料来源：[src/cli/runtime-debug.ts]()\n\n## 导出 API\n\n运行时系统通过以下入口导出公共接口：\n\n```typescript\n// 主入口\nexport { createRuntime } from './runtime.js';\n\n// 工具函数\nexport { \n  loadToolMetadata,\n  callTool,\n  getDefinitions \n} from './runtime.js';\n\n// 结果处理\nexport { \n  extractContent,\n  extractText,\n  extractStructuredContent \n} from './result-utils.js';\n\n// 错误类型\nexport { \n  McpError,\n  ConnectionError,\n  TimeoutError \n} from './runtime/errors.js';\n```\n\n资料来源：[src/runtime.ts](), [src/result-utils.ts]()\n\n## 最佳实践\n\n### 1. 选择合适的生命周期模式\n\n```typescript\n// 高频调用场景 - 使用 keep-alive\nconst server = {\n  name: 'frequently-used',\n  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },\n  lifecycle: { mode: 'keep-alive', idleTimeoutMs: 60000 }\n};\n\n// 低频调用场景 - 使用 ephemeral\nconst server = {\n  name: 'rarely-used',\n  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },\n  lifecycle: { mode: 'ephemeral' }\n};\n```\n\n### 2. 配置合理的超时时间\n\n```bash\n# 启动时指定超时\nmcporter list --timeout-ms 60000\n\n# 或通过环境变量\nexport MCPORTER_OAUTH_TIMEOUT_MS=120000\n```\n\n### 3. 利用工具选择器\n\n```bash\n# 正确使用 server.tool 格式\nmcporter call context7.getComponents --prompt \"React button\"\n\n# 不需要显式指定服务器\nmcporter list linear.listProjects\n```\n\n## 总结\n\nmcporter 的运行时系统通过抽象 MCP 服务器的连接细节，提供了一个统一、可靠的工具调用平台。其核心设计包括：\n\n1. **声明式配置**：通过 `ServerDefinition` 描述服务器连接参数\n2. **生命周期管理**：支持 keep-alive 和 ephemeral 两种模式平衡资源与性能\n3. **结构化结果处理**：完善的响应解析支持多种内容类型\n4. **完善的错误诊断**：分类错误并提供可操作的修复建议\n5. **调试支持**：内置进程清理和挂起检测机制\n\n这些设计使得 mcporter 能够可靠地与各种 MCP 服务器交互，同时保持良好的开发体验。\n\n---\n\n<a id='page-transport-layer'></a>\n\n## 传输层\n\n### 相关页面\n\n相关主题：[运行时系统](#page-runtime-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/runtime/transport.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/transport.ts)\n- [src/cli/transport-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/transport-utils.ts)\n- [src/cli/http-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/http-utils.ts)\n- [src/runtime/node-http-fetch.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/node-http-fetch.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n</details>\n\n# 传输层\n\n## 概述\n\n传输层是 mcporter 架构中连接 MCP 服务器与客户端的核心组件，负责处理不同通信协议之间的数据传输与协议协商。mcporter 支持多种传输方式，包括 HTTP、SSE（Server-Sent Events）和 stdio（标准输入输出），每种传输方式都有其特定的适用场景和配置要求。\n\n传输层的主要职责包括：\n\n- 建立与 MCP 服务器的连接\n- 处理请求与响应的序列化/反序列化\n- 管理传输生命周期（持久连接 vs 临时连接）\n- 处理认证和授权流程\n- 提供传输层面的错误处理与重试机制\n\n资料来源：[src/runtime/transport.ts:1-50]()\n\n## 支持的传输类型\n\nmcporter 支持三种主要的传输协议，开发者可通过 `--transport` 参数显式指定，或由系统自动检测：\n\n| 传输类型 | 标识符 | 说明 | 适用场景 |\n|---------|--------|------|---------|\n| HTTP | `http` | 基于 RESTful 风格的请求/响应模式 | 远程服务器、无状态服务 |\n| SSE | `sse` | Server-Sent Events，支持服务端推送 | 需要实时更新的场景 |\n| stdio | `stdio` | 标准输入输出流 | 本地进程、子进程通信 |\n\n资料来源：[src/cli/config/help.ts:3]()\n\n## HTTP 传输\n\n### 基本原理\n\nHTTP 传输是 mcporter 用于连接远程 MCP 服务器的主要方式。客户端通过 HTTP POST 请求发送工具调用请求，服务器返回 JSON 格式的响应。\n\n```mermaid\ngraph LR\n    A[mcporter 客户端] -->|POST /call-tool| B[HTTP MCP 服务器]\n    B -->|200 OK + JSON| A\n    A -->|GET /tools| B\n    B -->|200 OK + JSON Schema| A\n```\n\n### URL 处理\n\nHTTP 传输层支持完整的 URL 解析，包括：\n\n- 标准 HTTPS URL\n- 自定义端口指定\n- 路径前缀处理\n\n资料来源：[src/cli/http-utils.ts:1-30]()\n\n### 请求配置\n\nHTTP 传输支持多种请求头配置，用于认证和自定义元数据传递：\n\n```typescript\ninterface HttpTransportConfig {\n  url: string;\n  headers?: Record<string, string>;\n  timeout?: number;\n}\n```\n\n资料来源：[src/runtime/node-http-fetch.ts:1-40]()\n\n## SSE 传输\n\n### 基本原理\n\nSSE（Server-Sent Events）传输允许服务器主动向客户端推送消息，这在需要实时通知或长连接操作的场景中特别有用。\n\n```mermaid\ngraph TB\n    A[mcporter 客户端] -->|建立 SSE 连接| B[MCP 服务器]\n    B -->|事件流| A\n    A -->|POST 请求| B\n    B -->|响应| A\n```\n\nSSE 传输层会自动处理连接重连和心跳机制，确保连接的可靠性。\n\n资料来源：[src/runtime/transport.ts:100-150]()\n\n## stdio 传输\n\n### 基本原理\n\nstdio 传输通过标准输入输出与本地 MCP 服务器进程通信。这种方式适用于：\n\n- 本地安装的 MCP 服务器\n- 需要在同一进程中运行的服务\n- 调试和开发环境\n\n### 命令解析\n\nstdio 传输支持复杂的命令行解析，包括引号处理和参数转义：\n\n```mermaid\ngraph TD\n    A[原始命令字符串] --> B[字符逐个解析]\n    B --> C{检测引号状态}\n    C -->|\"单引号 ''\"| D[单引号模式]\n    C -->|\"双引号 \\\"\\\"\"| E[双引号模式]\n    C -->|普通字符| F[追加到当前 token]\n    D --> G{遇到单引号?}\n    E --> H{遇到双引号?}\n    G -->|是| I[结束引号模式]\n    G -->|否| D\n    H -->|是| J[结束引号模式]\n    H -->|否| E\n    I --> F\n    J --> F\n    F --> K{结束?}\n    K -->|否| B\n    K -->|是| L[返回 token 数组]\n```\n\n资料来源：[src/cli/adhoc-server.ts:50-100]()\n\n### 特殊命令识别\n\nstdio 传输包含对特定命令的自动识别机制：\n\n| 命令类型 | 标识 | 行为 |\n|---------|------|------|\n| Chrome DevTools | `chrome-devtools` 相关占位符 | 自动分配动态端口 |\n| 持久化命令 | 配置中的 keep-alive 列表 | 保持连接复用 |\n\n资料来源：[src/lifecycle.ts:30-80]()\n\n## 传输生命周期管理\n\n### 生命周期模式\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 标识 | 说明 |\n|------|------|------|\n| 持久化 | `keep-alive` | 服务器进程持续运行，支持连接复用 |\n| 临时 | `ephemeral` | 每次请求后终止服务器进程 |\n\n### 持久化配置\n\n```typescript\ninterface LifecycleConfig {\n  mode: 'keep-alive' | 'ephemeral';\n  idleTimeoutMs?: number;  // 可选的空闲超时配置\n}\n```\n\n资料来源：[src/lifecycle.ts:100-150]()\n\n### 生命周期序列化\n\n```mermaid\ngraph TD\n    A[生命周期配置] --> B{mode 检测}\n    B -->|keep-alive + 无超时| C[返回字符串 'keep-alive']\n    B -->|keep-alive + 有超时| D[返回对象 {mode, idleTimeoutMs}]\n    B -->|ephemeral| E[返回字符串 'ephemeral']\n    C --> F[序列化完成]\n    D --> F\n    E --> F\n```\n\n资料来源：[src/cli/adhoc-server.ts:120-140]()\n\n## 传输层工具函数\n\n### 传输摘要格式化\n\n`formatTransportSummary` 函数用于生成人类可读的传输信息摘要：\n\n```typescript\nfunction formatTransportSummary(\n  server: ServerDefinition,\n  options?: { verbose?: boolean }\n): string\n```\n\n返回值示例：\n\n- HTTP 传输：`https://api.example.com/mcp`\n- stdio 传输：`stdio /usr/local/bin/mcp-server`\n\n资料来源：[src/cli/transport-utils.ts:1-50]()\n\n### 传输类型检测\n\n传输层提供自动检测机制，根据服务器配置推断最合适的传输类型：\n\n```typescript\nfunction inferTransportType(config: ServerConfig): TransportType\n```\n\n检测优先级：\n\n1. 显式指定的 `--transport` 参数\n2. URL 格式（`http://`/`https://` → HTTP/SSE）\n3. 命令行配置（存在 `command` 字段 → stdio）\n4. 默认fallback\n\n资料来源：[src/runtime/transport.ts:50-100]()\n\n## HTTP 请求处理\n\n### Node.js 环境适配\n\nmcporter 在 Node.js 环境中使用原生 `fetch` API，并通过 `node-http-fetch.ts` 模块提供额外配置能力：\n\n```typescript\n// 超时配置示例\nconst response = await fetch(url, {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    ...customHeaders\n  },\n  body: JSON.stringify(payload),\n  signal: AbortSignal.timeout(timeoutMs)\n});\n```\n\n资料来源：[src/runtime/node-http-fetch.ts:40-80]()\n\n### 错误处理\n\nHTTP 传输层的错误分类：\n\n| 错误类型 | 状态码范围 | 处理策略 |\n|---------|-----------|---------|\n| 认证错误 | 401, 403 | 提示用户执行 `mcporter auth login` |\n| 网络错误 | - | 自动重试或返回离线状态 |\n| 服务器错误 | 5xx | 记录日志，返回错误状态 |\n| 超时 | - | 根据配置的超时时间终止请求 |\n\n资料来源：[src/cli/http-utils.ts:50-100]()\n\n## 进程清理与资源管理\n\n### 标准清理流程\n\n对于 stdio 传输，mcporter 在连接关闭时执行以下清理：\n\n```mermaid\ngraph TD\n    A[检测连接关闭信号] --> B[销毁 stdout 流]\n    B --> C[销毁 stderr 流]\n    C --> D[关闭 stdin 管道]\n    D --> E{DEBUG_HANG 启用?}\n    E -->|是| F[发送 SIGKILL]\n    E -->|否| G[正常退出]\n    F --> H[记录调试信息]\n```\n\n资料来源：[src/cli/runtime-debug.ts:20-60]()\n\n### 锁文件恢复\n\n传输层包含锁文件管理机制，用于处理异常进程退出：\n\n```typescript\nasync function removeRecoverableLock(lockPath: string): Promise<boolean>\n```\n\n恢复条件：\n\n- 锁文件持有进程已不存在\n- 锁文件创建时间超过阈值\n- breaker 文件存在且满足恢复条件\n\n资料来源：[src/fs-json.ts:60-100]()\n\n## 配置参考\n\n### 传输相关配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `transport` | `http` \\| `sse` \\| `stdio` | 自动检测 | 强制使用指定传输类型 |\n| `baseUrl` | string | - | HTTP 服务器基础 URL |\n| `command` | string | - | stdio 模式下的可执行命令 |\n| `args` | string[] | `[]` | 命令行参数 |\n| `env` | Record | `{}` | 环境变量 |\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--transport <http\\|sse\\|stdio>` | 指定传输类型 |\n| `--arg <value>` | 传递 stdio 额外参数（可重复） |\n| `--header KEY=value` | 添加 HTTP 请求头（可重复） |\n| `--env KEY=value` | 设置环境变量（可重复） |\n\n资料来源：[src/cli/config/help.ts:1-30]()\n\n## 最佳实践\n\n### 选择传输类型\n\n1. **远程 API 访问**：优先使用 HTTP 传输\n2. **需要实时推送**：选择 SSE 传输\n3. **本地工具集成**：使用 stdio 传输\n4. **混合场景**：在配置文件中为每个服务器单独指定\n\n### 性能优化\n\n- 对于频繁调用的服务器，启用 `keep-alive` 模式减少连接建立开销\n- HTTP 传输建议设置合理的超时时间（默认 60 秒）\n- stdio 传输注意进程清理，避免僵尸进程\n\n### 安全建议\n\n- 使用 HTTPS 替代 HTTP 传输敏感数据\n- 通过环境变量存储认证凭据，避免硬编码\n- 定期轮换 OAuth 客户端密钥\n\n## 相关文档\n\n- [配置管理](./config.md) - 传输层配置详解\n- [认证流程](./auth.md) - OAuth 和 API Key 认证\n- [工具调用](./tools.md) - 通过传输层执行工具调用\n- [CLI 生成](./cli-generation.md) - 生成独立 CLI 工具\n\n---\n\n<a id='page-cli-reference'></a>\n\n## CLI 命令参考\n\n### 相关页面\n\n相关主题：[工具调用语法](#page-call-syntax), [调用启发式与自动更正](#page-call-heuristic)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/cli-reference.md](https://github.com/steipete/mcporter/blob/main/docs/cli-reference.md)\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/cli-factory.ts](https://github.com/steipete/mcporter/blob/main/src/cli/cli-factory.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/serve-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/serve-command.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)\n</details>\n\n# CLI 命令参考\n\n## 概述\n\nmcporter 提供了一套完整的命令行工具，用于管理、调用和调试 MCP（Model Context Protocol）服务器。该 CLI 是与 MCP 服务器交互的主要入口点，支持服务器发现、工具调用、配置管理以及代码生成等功能。\n\nCLI 工具的核心设计理念是统一处理不同类型的 MCP 服务器（HTTP、SSE、stdio），并提供一致的接口和输出格式。通过运行时抽象层，`mcporter` 能够自动发现已配置的服务器、处理 OAuth 认证、管理连接生命周期。资料来源：[README.md:1-50]()\n\n## 核心命令架构\n\nmcporter CLI 采用子命令架构，主要包含以下命令模块：\n\n```mermaid\ngraph TD\n    A[mcporter] --> B[list]\n    A --> C[call]\n    A --> D[config]\n    A --> E[generate-cli]\n    A --> F[emit-ts]\n    A --> G[inspect-cli]\n    \n    B --> B1[列出所有服务器]\n    C --> C1[调用指定工具]\n    D --> D1[增删改查配置]\n    E --> E1[生成独立CLI]\n    F --> F1[生成TypeScript类型]\n    G --> G1[检查CLI元数据]\n```\n\n## 全局选项\n\n所有 mcporter 命令支持以下全局选项：\n\n| 选项 | 说明 | 环境变量 |\n|------|------|----------|\n| `--config <path>` | 指定配置文件路径 | `MCPORTER_CONFIG` |\n| `--root <path>` | 设置工作目录 | - |\n| `--log-level <level>` | 设置日志级别（debug/info/warn/error） | `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 超时时间 | `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--output <format>` | 控制输出格式 | - |\n\n资料来源：[src/cli/config/help.ts:1-30]()\n\n## mcporter list\n\n`list` 命令用于列出已配置的 MCP 服务器及其可用工具。\n\n### 基本用法\n\n```bash\nmcporter list [server]\nmcporter list --json\nmcporter list --signatures\n```\n\n### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `--json` | 以 JSON 格式输出结果 |\n| `--signatures` | 仅显示函数签名 |\n| `--brief` | 简化输出格式 |\n| `--all-parameters` | 显示所有参数（包括可选） |\n| `--required-only` | 仅显示必需参数 |\n| `--schema` | 显示 JSON Schema |\n\n资料来源：[src/cli/list-command.ts:1-50]()\n\n### 输出状态分类\n\n服务器状态分为以下几类：\n\n| 状态 | 含义 | 颜色标识 |\n|------|------|----------|\n| `ok` | 服务器正常，可调用工具 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 红色 |\n| `error` | 未知错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:40-80]()\n\n### 服务器信息格式化\n\n输出格式包括工具数量、响应耗时和来源信息：\n\n```typescript\n// 输出格式示例\n- context7 (5 tools, 1.2s) [npm:@context7/mcp]\n- firecrawl (3 tools, 0.8s) [local]\n```\n\n来源标签表示服务器的定义来源：\n- `[npm:xxx]` - npm 包\n- `[local]` - 本地配置\n- `[cursor]` - Cursor 导入\n- `[claude]` - Claude 导入\n\n资料来源：[src/cli/list-format.ts:80-120]()\n\n## mcporter call\n\n`call` 命令用于调用 MCP 服务器上的特定工具。\n\n### 基本用法\n\n```bash\nmcporter call <server>.<tool> [args...]\nmcporter call context7.resolve-library-id --query \"React hooks\"\n```\n\n### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `--raw` | 保持原始输出格式 |\n| `--raw-strings` | 保持数字形式的字符串参数 |\n| `--no-coerce` | 禁用类型转换 |\n| `--save-images <dir>` | 保存图片内容到指定目录 |\n| `--tail-log` | 显示相关日志的最后 20 行 |\n\n### 参数传递规则\n\n`call` 命令支持多种参数格式：\n\n```bash\n# 关键字参数\nmcporter call server.tool --key value\n\n# 位置参数\nmcporter call server.tool arg1 arg2\n\n# 混合使用\nmcporter call server.tool --key value arg1\n```\n\n类型自动转换规则：\n- `true`/`false` → 布尔值\n- `null` → null\n- 数字形式字符串 → 数字\n- JSON 对象 → 对象\n\n资料来源：[README.md:50-100]()\n\n## mcporter config\n\n`config` 命令用于管理 mcporter.json 配置文件。\n\n### 子命令\n\n| 子命令 | 说明 |\n|--------|------|\n| `config list` | 列出本地配置 |\n| `config get <name>` | 获取指定配置项 |\n| `config add <name>` | 添加新配置 |\n| `config remove <name>` | 删除配置项 |\n| `config import <kind>` | 导入外部配置 |\n\n资料来源：[README.md:120-150]()\n\n### 配置示例\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n配置文件支持 JSONC 格式，允许内联注释和尾随逗号。资料来源：[README.md:140-180]()\n\n## mcporter generate-cli\n\n生成独立的可分享 CLI 工件，将 MCP 服务器转换为独立的命令行工具。\n\n### 基本用法\n\n```bash\nmcporter generate-cli --command https://mcp.context7.com/mcp\nmcporter generate-cli \"npx -y chrome-devtools-mcp@latest\"\nmcporter generate-cli linear --bundle dist/linear.js\n```\n\n### 生成选项\n\n| 选项 | 说明 |\n|------|------|\n| `--name <name>` | 覆盖推断的 CLI 名称 |\n| `--description <text>` | 设置帮助文本摘要 |\n| `--command <spec>` | MCP 服务器命令或 URL |\n| `--server <name>` | 从配置中选择服务器 |\n| `--bundle <path>` | 输出捆绑包路径 |\n| `--dry-run` | 预览生成结果 |\n| `--from <cli>` | 从现有 CLI 重新生成 |\n\n资料来源：[README.md:30-60]()\n\n### 工件元数据\n\n生成的 CLI 嵌入以下元数据：\n\n```bash\nnpx mcporter inspect-cli dist/context7.js     # 查看元数据摘要\nnpx mcporter generate-cli --from dist/context7.js  # 使用元数据重新生成\n```\n\n## mcporter emit-ts\n\n生成强类型的 TypeScript 客户端代码，无需完整的 CLI 即可使用 MCP 工具。\n\n### 基本用法\n\n```bash\n# 仅生成类型定义\nmcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成客户端包装器\nmcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n### 输出模式\n\n| 模式 | 说明 | 输出文件 |\n|------|------|----------|\n| `types` | 仅接口定义 | `.d.ts` |\n| `client` | 接口 + 代理工厂 | `.d.ts` + `.ts` |\n\n### 附加选项\n\n| 选项 | 说明 |\n|------|------|\n| `--include-optional` | 展开所有可选字段 |\n| `--json` | 输出结构化摘要 |\n| `--server <name>` | 选择服务器（支持 URL） |\n\n生成的客户端模式与 `createRuntime()` API 保持同步。资料来源：[README.md:70-100]()\n\n## mcporter inspect-cli\n\n检查已生成 CLI 工件的元数据和签名信息。\n\n### 基本用法\n\n```bash\nmcporter inspect-cli dist/context7.js\n```\n\n## 服务器生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 说明 | 配置值 |\n|------|------|--------|\n| `keep-alive` | 持续运行，复用连接 | `\"keep-alive\"` |\n| `ephemeral` | 每次调用后关闭 | `\"ephemeral\"` |\n\n### 生命周期配置\n\n```json\n{\n  \"lifecycle\": {\n    \"mode\": \"keep-alive\",\n    \"idleTimeoutMs\": 300000\n  }\n}\n```\n\n自动保活检测：mcporter 会识别特定的命令签名（如某些 chrome-devtools 命令），自动应用 `keep-alive` 策略。资料来源：[src/lifecycle.ts:1-50]()\n\n## 输出格式化\n\n### 文本模式\n\n默认使用人类可读的格式化输出：\n\n```\n✓ context7 (5 tools, 1.2s)\n  - resolve-library-id(query, libraryName)\n  - get-library-docs(libraryId, ...)\n```\n\n### JSON 模式\n\n使用 `--json` 选项获取机器可读输出：\n\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"context7\",\n      \"status\": \"ok\",\n      \"durationMs\": 1200,\n      \"tools\": [...]\n    }\n  ]\n}\n```\n\n资料来源：[src/cli/list-output.ts:1-80]()\n\n## OAuth 认证\n\nmcporter 自动处理 MCP 服务器的 OAuth 认证流程。\n\n### OAuth 配置选项\n\n| 选项 | 说明 |\n|------|------|\n| `--oauth-client-id <id>` | 使用预注册的客户端 ID |\n| `--oauth-client-secret-env <var>` | 从环境变量读取密钥 |\n| `--oauth-token-endpoint-auth-method <method>` | 设置令牌认证方式 |\n| `--oauth-redirect-url <url>` | 自定义重定向 URL |\n| `--token-cache-dir <path>` | OAuth 令牌缓存目录 |\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CLI as mcporter\n    participant Server as MCP Server\n    participant Browser\n    \n    User->>CLI: call <server>.<tool>\n    CLI->>Server: 发现需要 OAuth\n    Server->>Browser: 重定向到授权页面\n    Browser->>User: 显示授权页面\n    User->>Browser: 确认授权\n    Browser->>Server: 授权码\n    Server->>CLI: 颁发访问令牌\n    CLI->>Server: 调用工具\n```\n\n认证超时默认 5 分钟，可通过 `--oauth-timeout` 调整。资料来源：[src/cli/config/help.ts:1-40]()\n\n## 错误处理与调试\n\n### 常见错误状态\n\n| 状态码 | 含义 | 解决方案 |\n|--------|------|----------|\n| `auth` | 认证失败 | 运行 `mcporter config login <server>` |\n| `offline` | 服务器不可达 | 检查网络连接和服务器地址 |\n| `http` | HTTP 请求错误 | 检查服务器日志 |\n| `error` | 未知错误 | 使用 `--log-level debug` 调试 |\n\n### 调试模式\n\n```bash\nmcporter list --log-level debug\nDEBUG_HANG=1 mcporter call server tool\n```\n\n启用 `DEBUG_HANG` 后，mcporter 会在强制终止进程前留下调试标记，便于诊断连接问题。资料来源：[src/cli/runtime-debug.ts:1-50]()\n\n## 高级用法\n\n### 临时服务器（Ad-hoc）\n\n通过 `--command` 直接运行未配置的服务器：\n\n```bash\nmcporter list --command \"npx -y some-mcp-server\"\n```\n\n支持完整的命令参数传递和生命周期管理。资料来源：[src/cli/adhoc-server.ts:1-50]()\n\n### 工具选择器\n\n使用点号分隔符精确指定服务器和工具：\n\n```bash\nmcporter list context7.resolve-library-id\n```\n\n自动补全和纠错功能支持模糊匹配服务器名称。资料来源：[src/cli/list-command.ts:50-100]()\n\n## 最佳实践\n\n1. **配置管理**：优先使用 `mcporter config` 管理配置，避免直接编辑 JSON 文件\n2. **类型安全**：使用 `emit-ts` 生成 TypeScript 类型，集成到开发工作流\n3. **认证处理**：生产环境使用环境变量存储敏感信息，配合 `--oauth-client-secret-env`\n4. **调试技巧**：使用 `--tail-log` 查看工具调用的关联日志\n5. **性能优化**：高频调用场景选择 `keep-alive` 生命周期模式\n\n---\n\n*本文档最后更新于 2024 年 11 月，基于 mcporter 最新版本。*\n\n---\n\n<a id='page-call-syntax'></a>\n\n## 工具调用语法\n\n### 相关页面\n\n相关主题：[调用启发式与自动更正](#page-call-heuristic), [CLI 命令参考](#page-cli-reference)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/call-syntax.md](https://github.com/steipete/mcporter/blob/main/docs/call-syntax.md)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n- [src/cli/call-argument-expression.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-argument-expression.ts)\n- [src/cli/call-expression-parser.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-expression-parser.ts)\n- [src/cli/command-inference.ts](https://github.com/steipete/mcporter/blob/main/src/cli/command-inference.ts)\n</details>\n\n# 工具调用语法\n\n## 概述\n\nmcporter 的工具调用语法（Tool Calling Syntax）是连接用户命令行与 MCP（Model Context Protocol）服务器工具之间的核心桥接层。该系统负责解析用户输入的参数表达式，将其转换为符合工具 schema 的结构化参数，并最终传递给运行时执行调用。\n\n工具调用语法的主要职责包括：\n\n- **参数解析**：支持命名参数、位置参数、混合使用等多种调用方式\n- **类型强制转换**：自动将字符串形式的参数值转换为 schema 定义的正确类型\n- **工具发现**：根据服务器名称和工具名称定位目标工具\n- **参数验证**：验证参数是否符合工具定义的输入 schema\n\n资料来源：[src/cli/call-command.ts:1-50]()\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    A[用户输入] --> B[call-command.ts]\n    B --> C{参数类型判定}\n    C -->|命名参数| D[直接使用命名参数]\n    C -->|位置参数| E[call-expression-parser.ts]\n    C -->|字符串候选| F[类型强制转换]\n    C -->|数组候选| G[数组参数处理]\n    E --> H[loadToolMetadata]\n    H --> I[获取 Schema 信息]\n    I --> J[参数映射]\n    J --> K[参数验证]\n    K --> L[runtime.callTool]\n    F --> L\n    G --> L\n```\n\n### 主要模块说明\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| call-command | `src/cli/call-command.ts` | 命令入口、参数解析协调、调用执行 |\n| call-expression-parser | `src/cli/call-expression-parser.ts` | 解析位置参数表达式 |\n| call-argument-expression | `src/cli/call-argument-expression.ts` | 处理参数表达式求值 |\n| command-inference | `src/cli/command-inference.ts` | 服务器和工具名称推断 |\n| list-command | `src/cli/list-command.ts` | 工具元数据查询 |\n\n资料来源：[src/cli/call-command.ts:50-100]()\n\n## 调用方式\n\nmcporter 支持多种工具调用方式，以适应不同用户习惯和场景需求。\n\n### 1. 命名参数方式\n\n最直接的调用方式，用户显式指定每个参数的名称和值：\n\n```bash\nmcporter call <server>.<tool> --key1=value1 --key2=value2\n```\n\n示例：\n\n```bash\nmcporter call linear.create-issue --title=\"Bug Report\" --team_id=team123\n```\n\n### 2. 位置参数方式\n\n用户按照工具 schema 定义的参数顺序提供值，系统自动将位置参数映射到对应的字段：\n\n```bash\nmcporter call <server>.<tool> <arg1> <arg2> <arg3>\n```\n\n位置参数映射遵循以下规则：\n\n- 仅填充**未通过命名参数设置的字段**\n- 严格校验位置参数数量不超过剩余可填充字段数\n- 必须按照 schema 中 required 参数在前、optional 参数在后的顺序提供\n\n资料来源：[src/cli/call-command.ts:150-200]()\n\n```typescript\nconst remaining = options.filter((option) => !(option.property in namedArgs));\nif (positionalArgs.length > remaining.length) {\n  throw new Error(\n    `Too many positional arguments (${positionalArgs.length}) supplied; only ${remaining.length} parameter${remaining.length === 1 ? '' : 's'} remain on ${tool}.`\n  );\n}\n```\n\n### 3. 混合使用方式\n\n命名参数和位置参数可以混合使用，命名参数具有更高的优先级：\n\n```bash\nmcporter call <server>.<tool> <arg1> --key2=value2 <arg3>\n```\n\n### 4. 选择器语法（Selector Syntax）\n\n使用点号分隔符直接指定服务器和工具：\n\n```bash\nmcporter call <server>.<tool>\n```\n\n系统会从 `<server>.<tool>` 中提取服务器名称和工具名称，支持自动补全和建议功能。\n\n资料来源：[src/cli.ts:80-120]()\n\n## 参数类型强制转换\n\nmcporter 内置了智能的类型强制转换系统，能够自动将命令行输入的字符串值转换为工具 schema 定义的正确类型。\n\n### 支持的转换类型\n\n| 目标类型 | 转换规则 | 示例 |\n|----------|----------|------|\n| string | 保持原值 | `--name=value` → `\"value\"` |\n| number | 解析数值字符串 | `--count=42` → `42` |\n| boolean | 识别真值/假值 | `--verbose=true` → `true` |\n| null | 识别 null 字符串 | `--value=null` → `null` |\n| array | 逗号分隔或 JSON 数组 | `--ids=a,b,c` → `[\"a\",\"b\",\"c\"]` |\n| object | JSON 对象字符串 | `--config='{\"a\":1}'` → `{a:1}` |\n\n### 强制转换流程\n\n```mermaid\ngraph LR\n    A[原始输入] --> B{类型检测}\n    B -->|key=value| C[stringCandidate]\n    B -->|key:value| D[stringCandidate]\n    B -->|尾部位置参数| E[stringCandidate]\n    C --> F[loadToolMetadata]\n    D --> F\n    E --> F\n    F --> G[获取 Schema]\n    G --> H{字段类型匹配}\n    H -->|number| I[parseFloat]\n    H -->|boolean| J[布尔解析]\n    H -->|null| K[空值处理]\n    H -->|array| L[数组处理]\n    I --> M[最终参数]\n    J --> M\n    K --> M\n    L --> M\n```\n\n### 强制转换函数\n\n参数强制转换的核心逻辑位于 `enforceSchemaAwareArgumentTypes` 函数中：\n\n资料来源：[src/cli/call-command.ts:200-250]()\n\n```typescript\nasync function enforceSchemaAwareArgumentTypes(\n  runtime,\n  server,\n  tool,\n  args,\n  stringCandidates,\n  arrayCandidates,\n  timeoutMs\n): Promise<Record<string, unknown>> {\n  // 1. 获取工具 schema\n  const tools = await withTimeout(loadToolMetadata(runtime, server, { includeSchema: true }), timeoutMs);\n  const toolInfo = tools.find((entry) => entry.tool.name === tool);\n  const schema = toolInfo?.tool.inputSchema as { properties?: Record<string, unknown> } | undefined;\n  \n  // 2. 遍历候选参数进行类型转换\n  for (const [key, rawValue] of Object.entries(stringCandidates ?? {})) {\n    if (typeof args[key] !== 'number') {\n      continue; // 跳过已经是正确类型的参数\n    }\n    // 根据 schema 类型进行转换\n  }\n}\n```\n\n### 布尔值识别规则\n\nmcporter 识别以下字符串为真值（case-insensitive）：\n\n- `true`、`yes`、`1`、`on`\n\n识别以下字符串为假值（case-insensitive）：\n\n- `false`、`no`、`0`、`off`\n\n## 位置参数解析详解\n\n### Schema 顺序保证\n\n位置参数到命名参数的映射依赖于 schema 中定义的参数顺序。系统通过 `loadToolMetadata` 获取工具列表时，会同时返回符合 TypeScript 风格的签名顺序，确保 required 参数优先于 optional 参数。\n\n资料来源：[src/cli/call-command.ts:100-150]()\n\n### 解析步骤\n\n1. **加载工具元数据**：获取完整 schema 和参数选项列表\n2. **计算剩余字段**：排除已通过命名参数设置的字段\n3. **校验参数数量**：确保位置参数不超过剩余字段数\n4. **按顺序映射**：将位置参数依次赋给剩余字段\n\n```typescript\nconst tools = await loadToolMetadata(runtime, server, { includeSchema: true }).catch(() => undefined);\nconst toolInfo = tools.find((entry) => entry.tool.name === tool);\nconst options = toolInfo.options;\nconst remaining = options.filter((option) => !(option.property in namedArgs));\n```\n\n## 工具选择器解析\n\n### 服务器和工具名称推断\n\n系统支持通过多种方式指定目标服务器和工具：\n\n```mermaid\ngraph TD\n    A[用户输入] --> B{包含点号?}\n    B -->|是| C[解析 selector]\n    B -->|否| D[检查 --server 参数]\n    C --> E[提取服务器名]\n    C --> F[提取工具名]\n    D --> G{有 --server?|H}\n    H -->|是| I[使用 --server 值]\n    H -->|否| J[报错缺失服务器]\n    E --> K[定位服务器]\n    F --> L[定位工具]\n    I --> K\n    K --> M[执行调用]\n    L --> M\n```\n\n### 选择器解析规则\n\n资料来源：[src/cli.ts:60-80]()\n\n1. **点号分隔符**：`<server>.<tool>` 格式直接解析\n2. **服务器标志**：`--server <name>` 或 `--server=<name>`\n3. **工具标志**：`--tool <name>` 或 `--tool=<name>`\n4. **URL 识别**：包含 `://` 的输入视为 HTTP 服务器定义\n\n```typescript\nconst separator = token.indexOf('.');\nif (separator > 0) {\n  return token.slice(0, separator); // 返回服务器名\n}\n```\n\n### 自动补全建议\n\n当用户输入的服务器或工具名称不存在时，系统会使用 `chooseClosestIdentifier` 函数提供最接近的候选建议：\n\n```typescript\nfunction resolveConfiguredToolSelector(runtime, target: string | undefined) {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  const definitions = runtime.getDefinitions();\n  const match = definitions\n    .map((definition) => definition.name)\n    .filter((name) => target.startsWith(`${name}.`))\n    .toSorted((a, b) => b.length - a.length)[0]; // 最长匹配优先\n}\n```\n\n## 错误处理与诊断\n\n### 常见错误类型\n\n| 错误场景 | 错误信息 | 解决方案 |\n|----------|----------|----------|\n| 工具不存在 | `Tool 'xxx' not found on 'yyy'` | 检查工具名称是否正确 |\n| 参数过多 | `Too many positional arguments` | 减少位置参数或使用命名参数 |\n| 参数缺失 | `Missing required parameter` | 检查 required 字段 |\n| 类型不匹配 | `Cannot convert 'xxx' to number` | 检查参数格式 |\n| Schema 不可用 | `Unable to load tool metadata` | 检查服务器连接 |\n\n### 参数类型错误处理\n\n当类型强制转换失败时，系统会保留原始字符串值并输出警告，而非直接报错。这允许某些工具接受灵活格式的输入。\n\n资料来源：[src/cli/call-command.ts:250-300]()\n\n### 超时处理\n\n所有涉及网络请求的操作都支持超时控制：\n\n```typescript\nconst tools = await withTimeout(\n  loadToolMetadata(runtime, server, { includeSchema: true }), \n  timeoutMs\n).catch(() => undefined);\n```\n\n## 调用流程完整图\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant CLI as mcporter CLI\n    participant Parser as 参数解析器\n    participant Runtime as 运行时\n    participant Server as MCP 服务器\n    \n    User->>CLI: mcporter call server.tool --arg=value\n    CLI->>Parser: 解析参数表达式\n    Parser->>Parser: 分离命名/位置参数\n    Parser->>CLI: 返回解析结果\n    CLI->>Runtime: 创建运行时实例\n    Runtime->>Server: 连接 MCP 服务器\n    Server-->>Runtime: 返回工具列表\n    CLI->>Parser: 获取 schema 信息\n    Parser-->>CLI: 返回参数映射\n    CLI->>CLI: 类型强制转换\n    CLI->>Runtime: callTool(name, args)\n    Runtime->>Server: 发送工具调用请求\n    Server-->>Runtime: 返回调用结果\n    Runtime-->>CLI: 返回 CallResult\n    CLI->>CLI: 格式化输出结果\n    CLI-->>User: 显示结果\n```\n\n## 高级用法\n\n### Raw Strings 模式\n\n使用 `--raw-strings` 标志可以禁用所有自动类型转换，保持参数值为原始字符串形式：\n\n```bash\nmcporter call server.tool --raw-strings --count=42 --enabled=true\n```\n\n此模式下，所有值都将作为字符串传递，不会进行数值或布尔值转换。\n\n### 禁用 Coerce 模式\n\n`--no-coerce` 标志完全禁用类型强制，包括 `key=value`、`key:value` 和尾部位置参数的所有转换：\n\n```bash\nmcporter call server.tool --no-coerce --id=12345 --data='{\"json\":\"value\"}'\n```\n\n### 双破折号分隔符\n\n使用 `--` 可以停止标志解析，使后续参数保持字面形式：\n\n```bash\nmcporter call server.tool -- --some-value --another-value\n```\n\n## 命令行参数速查表\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--server <name>` | 指定服务器名称 | `--server linear` |\n| `--tool <name>` | 指定工具名称 | `--tool create-issue` |\n| `--timeout <ms>` | 设置调用超时 | `--timeout 60000` |\n| `--raw-strings` | 禁用类型转换 | `--raw-strings` |\n| `--no-coerce` | 禁用所有强制转换 | `--no-coerce` |\n| `--output <format>` | 指定输出格式 | `--output json` |\n\n## 相关文档\n\n- [配置文件参考](docs/config.md) - mcporter.json 配置语法\n- [emit-ts 命令](docs/emit-ts.md) - 生成 TypeScript 类型定义\n- [generate-cli 命令](docs/generate-cli.md) - 生成独立 CLI 工具\n\n---\n\n<a id='page-call-heuristic'></a>\n\n## 调用启发式与自动更正\n\n### 相关页面\n\n相关主题：[工具调用语法](#page-call-syntax), [CLI 命令参考](#page-cli-reference)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/call-heuristic.md](https://github.com/steipete/mcporter/blob/main/docs/call-heuristic.md)\n- [src/cli/identifier-helpers.ts](https://github.com/steipete/mcporter/blob/main/src/cli/identifier-helpers.ts)\n- [src/cli/server-lookup.ts](https://github.com/steipete/mcporter/blob/main/src/cli/server-lookup.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n</details>\n\n# 调用启发式与自动更正\n\nmcporter 的调用启发式与自动更正系统为 MCP 服务器和工具的调用提供了智能容错机制。该系统通过模糊匹配、选择建议和上下文感知解析，显著提升了命令行交互的用户体验，减少了因拼写错误或格式偏差导致的命令失败。\n\n## 核心概念\n\nmcporter 在处理服务器名称、工具选择器和命令参数时，采用了多层次的启发式策略。这些策略协同工作，形成了从输入解析到错误恢复的完整链路。\n\n### 模糊匹配算法\n\n当用户输入的服务器名称与配置中的实际名称不完全匹配时，mcporter 使用基于字符串相似度的算法进行自动更正。该算法不仅考虑精确匹配，还评估字符串之间的距离和公共子序列。资料来源：[src/cli/identifier-helpers.ts]()\n\n```typescript\n// 伪代码示例：chooseClosestIdentifier 的匹配逻辑\nfunction chooseClosestIdentifier(attempted: string, candidates: string[]): string | undefined {\n  // 计算编辑距离并选择最接近的候选者\n  // 优先处理前缀匹配，然后考虑编辑距离\n}\n```\n\n### 选择器解析规则\n\nmcporter 支持 `server.tool` 格式的工具选择器，通过分层解析策略确保准确识别目标服务器和工具。解析器首先尝试完整匹配，然后降级为服务器名称前缀匹配，最后进行模糊校正。资料来源：[src/cli/list-command.ts:35-52]()\n\n## 系统架构\n\n```\ngraph TD\n    A[用户输入命令] --> B[输入标准化]\n    B --> C{选择器格式检测}\n    C -->|包含 \".\"| D[server.tool 解析]\n    C -->|纯文本| E[服务器名称解析]\n    D --> F{精确匹配?}\n    E --> G{精确匹配?}\n    F -->|否| H[前缀匹配扫描]\n    G -->|否| I[模糊匹配搜索]\n    H --> J{唯一匹配?}\n    I --> K[返回最佳候选]\n    J -->|是| K\n    J -->|否| L[输出歧义提示]\n    K --> M[执行命令]\n    L --> N[显示建议列表]\n```\n\n## 核心组件\n\n### 1. 服务器定义解析器\n\n服务器定义解析器负责将用户提供的目标字符串映射到配置中的实际服务器定义。该组件支持多种输入格式，包括纯服务器名称、带选择器的复合名称、以及 HTTP URL。资料来源：[src/cli/list-command.ts:35-52]()\n\n| 输入类型 | 处理策略 | 示例 |\n|---------|---------|------|\n| 精确名称 | 直接映射 | `mcporter list context7` |\n| 带点分隔符 | 提取 server 和 tool | `mcporter call linear.listProjects` |\n| 前缀模糊 | 扫描配置匹配 | `sshadcn` → `shadcn` |\n| URL 格式 | 协议解析 | `https://mcp.context7.com/mcp` |\n\n### 2. 工具元数据加载器\n\n工具元数据加载器负责获取指定服务器的工具列表，并在存在请求的工具时进行过滤。该组件通过 MCP 协议的 `tools/list` 方法获取服务器提供的所有工具及其输入模式。资料来源：[src/cli/list-command.ts:54-71]()\n\n```typescript\n// 工具元数据过滤逻辑\nfunction filterToolMetadata(entries: ToolMetadata[], requestedTool: string | undefined): ToolMetadata[] {\n  if (!requestedTool) {\n    return entries;\n  }\n  return entries.filter((entry) => entry.tool.name === requestedTool);\n}\n```\n\n### 3. 错误分类器\n\n错误分类器对 MCP 服务器连接失败的情况进行系统化分类，并为每种错误类型提供诊断建议和可能的修复命令。该分类器区分认证错误、网络错误、协议错误和超时情况。资料来源：[src/cli/list-format.ts:15-24]()\n\n```typescript\nconst timeoutSeconds = Math.round(timeoutMs / 1000);\nconst advice = classifyListError(result.error, result.server.name, timeoutSeconds);\nreturn {\n  line: `${prefix} (${advice.colored}, ${durationLabel})${sourceSuffix}`,\n  summary: advice.summary,\n  category: advice.category,\n  authCommand: advice.authCommand,\n  issue: advice.issue,\n};\n```\n\n## 调用流程详解\n\n### 标准调用路径\n\n1. **参数接收**：mcporter CLI 接收 `mcporter call <target>` 形式的命令\n2. **选择器解析**：检测是否包含 `.` 分隔符，提取服务器和工具名称\n3. **定义解析**：调用 `resolveServerDefinition` 获取服务器定义\n4. **元数据加载**：获取工具列表并验证请求的工具是否存在\n5. **参数准备**：处理命名参数和位置参数的混合输入\n6. **工具调用**：通过 MCP 运行时执行实际的工具调用\n\n资料来源：[src/cli/call-command.ts:1-50]()\n\n### 位置参数推断\n\n当用户使用位置参数而非命名参数时，mcporter 会动态查询工具的输入模式来确定参数顺序。这种设计允许用户使用 `mcporter call server tool arg1 arg2` 的简洁格式，而无需手动指定参数名称。资料来源：[src/cli/call-command.ts:18-48]()\n\n```typescript\n// 从工具模式推断位置参数映射\nconst tools = await loadToolMetadata(runtime, server, { includeSchema: true });\nconst toolInfo = tools.find((entry) => entry.tool.name === tool);\nconst remaining = options.filter((option) => !(option.property in namedArgs));\n\n// 验证位置参数数量不超限\nif (positionalArgs.length > remaining.length) {\n  throw new Error(`Too many positional arguments supplied...`);\n}\n```\n\n### 临时服务器管理\n\n对于通过命令行直接定义的临时服务器（adhoc server），mcporter 提供特殊的管理机制。临时服务器使用特殊的生命周期配置，并在命令执行完毕后自动清理。资料来源：[src/cli/adhoc-server.ts:50-62]()\n\n```typescript\nfunction serializeLifecycle(lifecycle: ReturnType<typeof resolveLifecycle>): string | { mode: 'keep-alive'; idleTimeoutMs?: number } | undefined {\n  if (!lifecycle) {\n    return undefined;\n  }\n  if (lifecycle.mode === 'keep-alive' && lifecycle.idleTimeoutMs === undefined) {\n    return 'keep-alive';\n  }\n  if (lifecycle.mode === 'keep-alive') {\n    return { mode: 'keep-alive', idleTimeoutMs: lifecycle.idleTimeoutMs };\n  }\n  return 'ephemeral';\n}\n```\n\n## 自动更正机制\n\n### 拼写校正示例\n\nmcporter 的模糊匹配功能能够智能处理常见的拼写错误：\n\n| 用户输入 | 实际配置 | 校正行为 |\n|---------|---------|---------|\n| `sshadcn` | `shadcn` | 自动更正 + 提示消息 |\n| `contextt7` | `context7` | 自动更正 |\n| `linearr` | `linear` | 自动更正 |\n\n校正发生时，mcporter 会在输出中显示暗淡处理的提示信息，告知用户进行了自动更正，同时执行用户的实际意图。资料来源：[src/cli/server-lookup.ts]()\n\n### 歧义检测与建议\n\n当用户输入存在多种可能的匹配时，mcporter 不会盲目选择一个，而是输出清晰的歧义提示：\n\n```\nmcporter: ambiguous server 'db'. Did you mean one of: [db-mysql, db-postgres, db-sqlite]?\n```\n\n这种设计确保用户始终了解系统的行为，避免因自动选择导致的意外后果。\n\n## 配置与使用\n\n### 启用自动更正\n\n自动更正在 mcporter 的 `list`、`call`、`config` 等主要命令中默认启用。用户可以通过配置或命令行参数调整匹配算法的敏感度。\n\n### 匹配范围控制\n\n| 命令 | 默认行为 | 可配置选项 |\n|------|---------|-----------|\n| `mcporter list` | 匹配服务器名称 | `--exact` 禁用模糊匹配 |\n| `mcporter call` | 匹配服务器和工具 | `--strict` 严格模式 |\n| `mcporter config` | 匹配配置键名 | 无需配置 |\n\n## 错误处理\n\n### 缺失工具的诊断\n\n当用户请求的工具在服务器上不存在时，mcporter 提供友好的错误消息，列出该服务器实际提供的工具列表。资料来源：[src/cli/list-command.ts:72-79]()\n\n```typescript\nfunction printMissingToolText(\n  definition: ServerDefinition,\n  tool: string,\n  durationMs: number,\n  transportSummary: string,\n  sourcePath: string | undefined\n): void {\n  printSingleServerHeader(definition, 0, durationMs, transportSummary, sourcePath);\n  console.warn(`  Tool '${tool}' not found on '${definition.name}'.`);\n}\n```\n\n### 超时与重试策略\n\n对于网络请求，mcporter 实现了可配置的超时机制。默认超时时间因服务器类型而异，HTTP 服务器通常使用较短的超时，而 stdio 服务器则使用更宽松的时间限制。资料来源：[src/cli/list-format.ts:12-14]()\n\n```typescript\nconst timeoutSeconds = Math.round(timeoutMs / 1000);\nconst timeoutLabel = `${timeoutSeconds}s`;\n```\n\n## 性能考量\n\n### 缓存策略\n\nmcporter 对服务器元数据和认证状态实施智能缓存，以减少重复连接的开销。缓存策略考虑以下因素：\n\n- 服务器的连接稳定性\n- 上次成功连接的时间戳\n- 配置文件的修改时间\n\n### 并行检查优化\n\n在批量检查多个服务器状态时，mcporter 使用并行连接策略，同时对多个服务器发起探测请求，显著减少总体检查时间。资料来源：[src/cli/list-command.ts:100-130]()\n\n## 扩展与定制\n\n### 自定义选择器解析器\n\n开发者可以通过实现 `resolveConfiguredToolSelector` 接口来扩展选择器的解析逻辑，支持自定义的命名约定和别名系统。资料来源：[src/cli/list-command.ts:35-52]()\n\n### 错误分类插件\n\n通过扩展 `classifyListError` 函数，可以添加针对特定 MCP 服务器的自定义错误处理和诊断建议。这种机制允许维护者提供针对特定服务（如 Docker、Kubernetes 等）的专业故障排除指导。\n\n## 相关文档\n\n- [配置管理文档](docs/config.md) - 了解服务器配置的编写方式\n- [emit-ts 文档](docs/emit-ts.md) - 生成类型化客户端工具\n- [Agent Skills 文档](docs/agent-skills.md) - 为 AI 代理编写技能定义\n\n---\n\n<a id='page-configuration'></a>\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)\n- [src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)\n- [src/config/path-discovery.ts](https://github.com/steipete/mcporter/blob/main/src/config/path-discovery.ts)\n- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n- [src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)\n- [src/cli/config/index.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/index.ts)\n</details>\n\n# 配置管理\n\nmcporter 的配置管理系统负责定义、加载和组织 MCP 服务器的连接信息。该系统支持多种配置源、灵活的命名匹配、跨编辑器的配置导入以及完整的 XDG 标准兼容。\n\n## 配置架构概述\n\nmcporter 采用分层配置架构，支持本地项目配置、全局用户配置和系统级配置的组合使用。\n\n```mermaid\ngraph TD\n    A[CLI 参数] --> B[环境变量<br/>MCPORTER_CONFIG]\n    B --> C[项目配置<br/>config/mcporter.json]\n    C --> D[XDG 配置<br/>$XDG_CONFIG_HOME/mcporter/mcporter.json]\n    D --> E[默认配置<br/>~/.mcporter/mcporter.json]\n    \n    F[MCP Servers 定义] --> C\n    G[导入配置<br/>Cursor/Claude/Windsurf] --> C\n    H[OAuth Vault 存储] -.-> D\n```\n\n配置加载按优先级从高到低依次为：\n\n1. **CLI 参数**：`--config <path>` 或 `--root <dir>`\n2. **环境变量**：`MCPORTER_CONFIG`\n3. **项目配置**：`<root>/config/mcporter.json`\n4. **XDG 配置**：`$XDG_CONFIG_HOME/mcporter/mcporter.json`\n5. **默认配置**：`~/.mcporter/mcporter.json`\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 配置文件格式\n\nmcporter 支持 JSONC 格式的配置文件，允许使用行内注释和尾随逗号。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    },\n    \"chrome-devtools\": {\n      // 内联注释\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chrome-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n### 服务器定义结构\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `command` | `string` | 条件 | stdio 传输时的启动命令 |\n| `args` | `string[]` | 否 | 命令行参数数组 |\n| `env` | `Record<string, string>` | 否 | 环境变量 |\n| `baseUrl` | `string` | 条件 | HTTP 传输时的服务器地址 |\n| `headers` | `Record<string, string>` | 否 | HTTP 请求头 |\n| `transport` | `http \\| sse \\| stdio` | 否 | 强制指定传输类型 |\n| `description` | `string` | 否 | 服务器描述文本 |\n| `allowedTools` | `string[]` | 否 | 允许的工具列表（白名单） |\n| `blockedTools` | `string[]` | 否 | 屏蔽的工具列表（黑名单） |\n| `lifecycle` | `keep-alive \\| ephemeral` | 否 | 服务器生命周期模式 |\n\n资料来源：[src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)\n\n## 路径发现机制\n\n配置路径发现遵循标准化的优先级规则，支持显式覆盖和 XDG 标准。\n\n```mermaid\ngraph LR\n    A[Config CLI] --> B{存在 --config?}\n    B -->|是| C[使用指定路径]\n    B -->|否| D{存在环境变量?}\n    D -->|MCPORTER_CONFIG| E[使用环境变量路径]\n    D -->|否| F{项目配置存在?}\n    F -->|是| G[config/mcporter.json]\n    F -->|否| H{XDG_CONFIG_HOME?}\n    H -->|是| I[$XDG_CONFIG_HOME/mcporter/mcporter.json]\n    H -->|否| J[~/.mcporter/mcporter.json]\n```\n\n路径发现逻辑实现于 `src/config/path-discovery.ts`，支持以下环境变量：\n\n| 环境变量 | 用途 | 默认值 |\n|----------|------|--------|\n| `MCPORTER_CONFIG` | 直接指定配置文件路径 | - |\n| `XDG_CONFIG_HOME` | XDG 配置根目录 | `~/.config` |\n| `XDG_DATA_HOME` | OAuth 令牌存储目录 | `~/.local/share` |\n| `XDG_CACHE_HOME` | Schema 缓存目录 | `~/.cache` |\n| `XDG_STATE_HOME` | 守护进程状态目录 | `~/.local/state` |\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 工具过滤配置\n\n服务器定义支持细粒度的工具访问控制，通过 `allowedTools` 和 `blockedTools` 实现白名单和黑名单机制。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"slack-readonly\": {\n      \"baseUrl\": \"https://example.com/slack/mcp\",\n      \"allowedTools\": [\"channels_list\", \"conversations_history\"]\n    },\n    \"devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chrome-devtools-mcp\"],\n      \"blockedTools\": [\"screenshot_fullpage\", \"performance_metrics\"]\n    }\n  }\n}\n```\n\n过滤机制在列表查询和工具调用时均生效，确保只有授权的工具可被访问。\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 配置管理命令\n\n`mcporter config` 提供交互式配置管理功能，支持列表、查询、添加、删除和导入操作。\n\n### 子命令概览\n\n| 命令 | 功能 |\n|------|------|\n| `mcporter config list` | 列出当前配置的服务器 |\n| `mcporter config get <name>` | 获取指定服务器配置详情 |\n| `mcporter config add <name> <command>` | 添加新服务器配置 |\n| `mcporter config remove <name>` | 删除服务器配置 |\n| `mcporter config import <kind>` | 从编辑器导入配置 |\n| `mcporter config logout <name>` | 清除 OAuth 认证信息 |\n\n资料来源：[src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)\n\n### 添加服务器配置\n\n```bash\n# 基本 stdio 服务器\nmcporter config add myserver npx -y my-mcp-server\n\n# HTTP 服务器\nmcporter config add context7 https://mcp.context7.com/mcp\n\n# 带 OAuth 认证\nmcporter config add github --auth oauth --oauth-client-id $CLIENT_ID\n\n# 带环境变量\nmcporter config add api --env OPENAI_API_KEY=$OPENAI_API_KEY\n```\n\n支持的添加参数：\n\n| 参数 | 说明 |\n|------|------|\n| `--command <cmd>` | stdio 传输的启动命令 |\n| `--transport <http\\|sse\\|stdio>` | 强制指定传输类型 |\n| `--arg <value>` | 附加 stdio 参数（可重复） |\n| `--env KEY=value` | 环境变量（可重复） |\n| `--header KEY=value` | HTTP 请求头（可重复） |\n| `--auth <strategy>` | 强制认证类型 |\n| `--oauth-client-id <id>` | OAuth 客户端 ID |\n| `--oauth-client-secret-env <env>` | OAuth 密钥环境变量名 |\n| `--token-cache-dir <path>` | OAuth 令牌缓存目录 |\n| `--persist <path>` | 写入指定配置文件路径 |\n| `--scope <home\\|project>` | 配置文件作用域 |\n| `--copy-from <import:name>` | 从导入配置复制 |\n\n资料来源：[src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n\n## 配置导入系统\n\nmcporter 支持从主流编辑器的配置中导入 MCP 服务器定义，实现配置迁移。\n\n### 支持的导入源\n\n| 编辑器 | 导入标识 | 配置格式 |\n|--------|----------|----------|\n| Cursor | `cursor` | `cursor/mcp.json` |\n| Claude Code | `claude-code` | `.claude/mcp.json` |\n| Windsurf | `windsurf` | `windsurf/mcp.json` |\n| VS Code | `vscode` | `mcp.json` |\n\n```bash\n# 列出可导入的服务器\nmcporter config import cursor --list\n\n# 交互式导入\nmcporter config import cursor\n\n# 直接复制到本地配置\nmcporter config import cursor --copy\n```\n\n导入过程会处理多种配置格式，包括 `mcpServers`、`servers` 和 `mcp` 容器结构。\n\n资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n\n### 导入安全规则\n\n不同来源的导入有不同的安全限制：\n\n```typescript\n{\n  allowMcpServers: true,    // 标准 mcpServers 容器\n  allowServers: true,        // servers 容器\n  allowMcp: true,            // mcp 容器\n  allowRootFallback: boolean // 是否允许根目录回退\n}\n```\n\nClaude Code 配置有特殊处理，仅在 `.claude.json` 或 `.claude/mcp.json` 路径下允许根目录回退。\n\n资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n\n## 模糊匹配与自动纠正\n\nmcporter 在配置管理中内置了智能模糊匹配机制，支持输入纠错和歧义提示。\n\n```bash\n# 拼写错误自动纠正\nmcporter config get sshadcn\n# 输出: sshadcn → shadcn (已纠正)\n\n# 歧义时提示选择\nmcporter config get linear\n# 输出: \"Did you mean linear-api or linear-tools?\"\n```\n\n匹配逻辑实现于 `src/cli/list-command.ts`，使用最长前缀匹配策略：\n\n```typescript\nconst match = definitions\n  .map((definition) => definition.name)\n  .filter((name) => target.startsWith(`${name}.`))\n  .toSorted((a, b) => b.length - a.length)[0];\n```\n\n资料来源：[src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n\n## 配置输出格式化\n\n`mcporter list` 命令以表格形式展示配置，支持文本和 JSON 两种输出格式。\n\n### 状态分类\n\n| 状态 | 说明 | 颜色编码 |\n|------|------|----------|\n| `ok` | 服务器在线，工具可用 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 |\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：steipete/mcporter\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)。\n\n## 1. 安全/权限坑 · 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor\n\n## 4. 配置坑 · 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：`daemonIdleTimeoutMs` missing?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`daemonIdleTimeoutMs` missing?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Add `mcporter vault set <server>` to seed credentials non-interactively\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add `mcporter vault set <server>` to seed credentials non-interactively\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b63d0f3f42e046488953064089bf8025 | https://github.com/openclaw/mcporter/issues/156 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d76f84533e8406d965b1762634996dd | https://github.com/openclaw/mcporter/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：MCPorter not using OAuth credentials\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCPorter not using OAuth credentials\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2705d784929e4996bcb34f3a71543ed7 | https://github.com/openclaw/mcporter/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78f73e8e0c9d4cca9e886fa2d89ef296 | https://github.com/openclaw/mcporter/issues/158 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocat…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocations\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9439129321d048dabb2ad6f14b4ab11e | https://github.com/openclaw/mcporter/issues/167 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Support refreshable bearer token auth for stdio MCP servers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support refreshable bearer token auth for stdio MCP servers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88f8026283fc46309d02fbb7f6a3186f | https://github.com/openclaw/mcporter/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1aff56feb584e23ac8b345ddc61934f | https://github.com/openclaw/mcporter/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：list reports auth required on expired access_token even when refresh_token is valid\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：list reports auth required on expired access_token even when refresh_token is valid\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcd9da058a8b48df94395fee1f995805 | https://github.com/openclaw/mcporter/issues/166 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | release_recency=unknown\n\n<!-- canonical_name: steipete/mcporter; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "mcporter",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "art_dff4c80f0d4d4ac1a1ab1697d13faf8d",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/steipete/mcporter#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "mcporter 说明书",
      "toc": [
        "https://github.com/steipete/mcporter 项目说明书",
        "目录",
        "项目概述",
        "核心定位",
        "核心命令",
        "系统架构",
        "配置系统",
        "运行时引擎",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "ae3b83cecb0b69afc1e3e69e3730405bcca8ea91",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "pnpm-lock.yaml",
      "package.json",
      "README.md",
      "docs/import.md",
      "docs/tool-calling.md",
      "docs/call-syntax.md",
      "docs/pnpm-mcp-migration.md",
      "docs/cli-generator.md",
      "docs/index.md",
      "docs/adhoc.md",
      "docs/refactor.md",
      "docs/daemon.md",
      "docs/logging.md",
      "docs/cli-reference.md",
      "docs/quickstart.md",
      "docs/call-heuristic.md",
      "docs/windows.md",
      "docs/install.md",
      "docs/local.md",
      "docs/subagent.md",
      "docs/emit-ts.md",
      "docs/RELEASE.md",
      "docs/spec.md",
      "docs/hang-debug.md",
      "docs/tmux.md",
      "docs/supabase-auth-issue.md",
      "docs/agent-skills.md",
      "docs/manual-testing.md",
      "docs/migration.md",
      "docs/shortcuts.md",
      "docs/mcp.md",
      "docs/known-issues.md",
      "docs/livetests.md",
      "docs/config.md",
      "examples/context7-headlines.ts",
      "src/generate-cli.ts",
      "src/oauth-client-info.ts",
      "src/paths.ts",
      "src/lifecycle.ts",
      "src/runtime.ts"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# mcporter - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mcporter 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n- `npx mcporter call 'linear.create_comment(issueId: \"ENG-123\", body: \"Looks good!\")'` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n- `npx mcporter call server.tool -- --raw-value` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx mcporter list` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等\n- `npx mcporter list context7 --schema` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx mcporter list https://mcp.linear.app/mcp --all-parameters` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx mcporter list shadcn.io/api/mcp.getComponents           # URL + tool suffix auto-resolves` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx mcporter list --stdio \"bun run ./local-server.ts\" --env TOKEN=xyz` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx mcporter call context7.resolve-library-id query=\"React hooks docs\" libraryName=react` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npx mcporter call context7.query-docs libraryId=/reactjs/react.dev query=\"useEffect cleanup\"` 证据：`README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs/config.md`, `docs/migration.md`, `examples/context7-headlines.ts` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0027` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0028` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：333\n- 重要文件覆盖：40/333\n- 证据索引条目：80\n- 角色 / Skill 条目：34\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 mcporter 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mcporter 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 mcporter 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 34 个角色 / Skill / 项目文档条目。\n\n- **Install**（project_doc）：mcporter ships as both a published npm package and a Homebrew formula. Most workflows can also run mcporter without installing anything via npx . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/install.md`\n- **AGENTS.md**（project_doc）：Shared guardrails distilled from the various ~/Projects/ /AGENTS.md files state as of November 15, 2025 . This document highlights the rules that show up again and again; still read the repo-local instructions before making changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **MCPorter 🧳 - Call MCPs from TypeScript or as CLI**（project_doc）：MCPorter 🧳 - Call MCPs from TypeScript or as CLI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Release Checklist**（project_doc）：Runner note: From the repo root run export MCP RUNNER=\"$PWD/runner\" and use $MCP RUNNER for every shell command listed below unless the step explicitly says otherwise. This keeps the guardrails active even when the checklist jumps between directories. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/RELEASE.md`\n- **Ad-hoc MCP Servers**（project_doc）：mcporter is gaining support for \"just try it\" workflows where you point the CLI at a raw MCP endpoint without first editing a config file. This doc tracks the behavior and heuristics we use to make that experience smooth while keeping the runtime predictable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/adhoc.md`\n- **Agent Skill Pattern**（project_doc）：Prefer one small skill per MCP server or workflow instead of a single generic mcporter skill. A focused skill keeps the agent prompt small, names the useful tools directly, and avoids loading schemas for servers that are irrelevant to the current task. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agent-skills.md`\n- **Call Command Auto-Correction**（project_doc）：mcporter call aims to help when a tool name is almost correct without hiding real mistakes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/call-heuristic.md`\n- **Call Syntax Reference**（project_doc）：mcporter call now understands two complementary styles: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/call-syntax.md`\n- **CLI Generator Plan**（project_doc）：Default behavior: generating .ts in the working directory if no output path is provided. Bundling is opt-in via --bundle and produces a single JS file with shebang; otherwise we emit TypeScript targeting Node.js. Rolldown handles bundling by default unless the runtime resolves to Bun—in that case Bun’s native bundler is selected automatically still requires --runtime bun or Bun auto-detection ; --bundler lets you ov… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cli-generator.md`\n- **mcporter CLI Reference**（project_doc）：A quick reference for the primary mcporter subcommands. Each command inherits --config and --root to override where servers are loaded from. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cli-reference.md`\n- **CLI Help Menu Snapshot**（project_doc）：mcporter config Usage: mcporter config options 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/config.md`\n- **MCPorter Daemon Plan**（project_doc）：- Invisible keep-alive: mcporter call should transparently start and reuse a per-login daemon whenever a configured server requires persistence e.g., chrome-devtools . No extra flags for agents. - Shared state: Multiple CLI invocations/agents within the same user session must reuse the same warm transport so STDIO servers can hold tabs, cookies, and other stateful context. - Per-config scope: The daemon lives under… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/daemon.md`\n- **mcporter emit-ts**（project_doc）：mcporter emit-ts turns a configured MCP server into TypeScript artifacts so agents, tests, and tooling can consume the server through strongly typed APIs. It reuses the same buildToolDoc data that powers mcporter list , so doc comments, parameter hints, and signatures stay perfectly in sync. For a broader overview of every CLI command, see docs/cli-reference.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/emit-ts.md`\n- **Debugging Hanging mcporter Calls**（project_doc）：When mcporter call prints a tool response but the process never exits, it usually means Node still has active handles it is waiting on. The most common culprit is a child MCP server process that keeps the stdio transport alive. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/hang-debug.md`\n- **Import Reference**（project_doc）：mcporter merges your local config/mcporter.json with editor- or tool-specific config files so you can reuse servers without copying them manually. This document spells out the supported formats, the directories we scan for each import kind, and how precedence works. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/import.md`\n- **Try it**（project_doc）：mcporter is a TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol — built so AI agents and developers can call any MCP server without boilerplate. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Known Issues**（project_doc）：This file tracks limitations that users regularly run into. Most of these require upstream cooperation or larger refactors—feel free to reference this when triaging bugs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/known-issues.md`\n- **Live MCP Tests**（project_doc）：These tests hit real hosted MCP servers and require outbound HTTP. They are off by default to keep CI and local runs deterministic. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/livetests.md`\n- **Running mcporter Locally**（project_doc）：You don’t need npx every time—here are the three local entry points we use while developing mcporter itself. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/local.md`\n- **Logging & Diagnostics**（project_doc）：The keep-alive daemon can tee its stdout/stderr and per-server call traces into a file so you can see crashes or repeated failures without rerunning it in the foreground. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/logging.md`\n- **Manual Testing Harness**（project_doc）：When we need to sanity-check CLI flows against real MCP servers or reproduce bugs by hand , use this repeatable harness. Everything runs under tmux so long-running commands can be inspected without blocking the current shell. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/manual-testing.md`\n- **mcporter Overview**（project_doc）：mcporter is the Sweetistics CLI + runtime for the Model Context Protocol MCP . It wraps the upstream TypeScript SDK with: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/mcp.md`\n- **Migration Guide**（project_doc）：This guide walks through replacing the Python-based pnpm mcp: helpers with the new TypeScript runtime and CLI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration.md`\n- **Migrating from pnpm mcp:**（project_doc）：The legacy pnpm mcp: helpers map directly onto the mcporter CLI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pnpm-mcp-migration.md`\n- **Quickstart**（project_doc）：This walkthrough assumes you already have an MCP server configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, or VS Code. If not, copy config/mcporter.example.json https://github.com/steipete/mcporter/blob/main/config/mcporter.example.json into ~/.mcporter/mcporter.json and edit it — see Configuration config.md for the full schema. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/quickstart.md`\n- **Next-Step Refactor Checklist**（project_doc）：This doc tracks remaining reuse/refactor work now that the original plan is done. Each section lists the goal, why it matters, and the concrete steps/tests needed. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/refactor.md`\n- **Agent Shortcuts**（project_doc）：These undocumented shortcuts are safe for MCP agents to call when they need a quick description of a server or its tools without memorizing the full mcporter CLI surface. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/shortcuts.md`\n- **mcporter Roadmap**（project_doc）：Inspired in part by Anthropic’s guidance on MCP code execution agents: https://www.anthropic.com/engineering/code-execution-with-mcp 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/spec.md`\n- **Claude Subagent Quickstart**（project_doc）：- Never invoke subagents through ./runner —launch them inside tmux directly so the session can persist and bypass the runner timeouts. Example: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/subagent.md`\n- **OAuth Notes & Hosted MCP Compatibility**（project_doc）：OAuth Notes & Hosted MCP Compatibility 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/supabase-auth-issue.md`\n- **tmux Hang Diagnostics**（project_doc）：Use tmux to verify whether a CLI command actually exits or is stalled on open handles. This keeps the main shell free while you inspect logs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tmux.md`\n- **Tool Calling Cheatsheet**（project_doc）：mcporter accepts multiple argument styles so you can match whatever feels most natural in your shell or script. Every style feeds the same validation pipeline schema-driven type coercion, required-field checks, enum hints , so pick the one that's easiest to type. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tool-calling.md`\n- **Installing dependencies**（project_doc）：- pnpm install fails on /mnt/c because NTFS/DrvFs blocks futime . Clone/sync the repo to $HOME ext4 inside WSL and run ./runner pnpm install there instead. Example: rsync -a --delete --exclude node modules /mnt/c/Projects/mcporter/ ~/mcporter-wsl/ . - Keep $HOME/.bun/bin and $HOME/.local/share/pnpm on your PATH before invoking ./runner . Without Bun and pnpm the runner prints the guardrail error and exits. - If you… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/windows.md`\n- **mcporter Changelog**（project_doc）：- Make generate-cli --runtime node --bundle .mjs emit an ES module bundle with a local require shim, fixing .mjs artifacts that previously crashed at startup. - Classify generated .mjs and .cjs outputs as bundle artifacts in embedded metadata instead of reporting them as binaries. - Avoid leaving implicit .ts template files in the current directory when generating bundle-only artifacts without --output . - Print gen… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Install**（documentation）：mcporter ships as both a published npm package and a Homebrew formula. Most workflows can also run mcporter without installing anything via npx . 证据：`docs/install.md`\n- **AGENTS.md**（documentation）：Shared guardrails distilled from the various ~/Projects/ /AGENTS.md files state as of November 15, 2025 . This document highlights the rules that show up again and again; still read the repo-local instructions before making changes. 证据：`AGENTS.md`\n- **MCPorter 🧳 - Call MCPs from TypeScript or as CLI**（documentation）：MCPorter 🧳 - Call MCPs from TypeScript or as CLI 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"mcporter\", \"version\": \"0.11.2\", \"description\": \"TypeScript runtime and CLI for connecting to configured Model Context Protocol servers.\", \"keywords\": \"cli\", \"mcp\", \"model-context-protocol\", \"sweetistics\" , \"license\": \"MIT\", \"author\": \"Sweetistics\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/openclaw/mcporter.git\" }, \"bin\": { \"mcporter\": \"dist/cli.js\" }, \"files\": \"dist\", \"README.md\", \"LICENSE\" , \"type\": \"module\", \"main\": \"dist/index.js\", \"module\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" }, \"./cli\": { \"import\": \"./dist/cli.js\", \"types\": \"./dist/cli.d.ts\" } }, \"publishConfig\": { \"ac… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Release Checklist**（documentation）：Runner note: From the repo root run export MCP RUNNER=\"$PWD/runner\" and use $MCP RUNNER for every shell command listed below unless the step explicitly says otherwise. This keeps the guardrails active even when the checklist jumps between directories. 证据：`docs/RELEASE.md`\n- **Ad-hoc MCP Servers**（documentation）：mcporter is gaining support for \"just try it\" workflows where you point the CLI at a raw MCP endpoint without first editing a config file. This doc tracks the behavior and heuristics we use to make that experience smooth while keeping the runtime predictable. 证据：`docs/adhoc.md`\n- **Agent Skill Pattern**（documentation）：Prefer one small skill per MCP server or workflow instead of a single generic mcporter skill. A focused skill keeps the agent prompt small, names the useful tools directly, and avoids loading schemas for servers that are irrelevant to the current task. 证据：`docs/agent-skills.md`\n- **Call Command Auto-Correction**（documentation）：mcporter call aims to help when a tool name is almost correct without hiding real mistakes. 证据：`docs/call-heuristic.md`\n- **Call Syntax Reference**（documentation）：mcporter call now understands two complementary styles: 证据：`docs/call-syntax.md`\n- **CLI Generator Plan**（documentation）：Default behavior: generating .ts in the working directory if no output path is provided. Bundling is opt-in via --bundle and produces a single JS file with shebang; otherwise we emit TypeScript targeting Node.js. Rolldown handles bundling by default unless the runtime resolves to Bun—in that case Bun’s native bundler is selected automatically still requires --runtime bun or Bun auto-detection ; --bundler lets you override either choice. 证据：`docs/cli-generator.md`\n- **mcporter CLI Reference**（documentation）：A quick reference for the primary mcporter subcommands. Each command inherits --config and --root to override where servers are loaded from. 证据：`docs/cli-reference.md`\n- **CLI Help Menu Snapshot**（documentation）：mcporter config Usage: mcporter config options 证据：`docs/config.md`\n- **MCPorter Daemon Plan**（documentation）：- Invisible keep-alive: mcporter call should transparently start and reuse a per-login daemon whenever a configured server requires persistence e.g., chrome-devtools . No extra flags for agents. - Shared state: Multiple CLI invocations/agents within the same user session must reuse the same warm transport so STDIO servers can hold tabs, cookies, and other stateful context. - Per-config scope: The daemon lives under the current user account, keyed by config path ~/.mcporter/daemon/daemon- .sock on Unix-like systems, or $XDG STATE HOME/mcporter/daemon/... when set , and never crosses user boundaries. - Resilience: If the daemon or a keep-alive server crashes, the next CLI call restarts it aut… 证据：`docs/daemon.md`\n- **mcporter emit-ts**（documentation）：mcporter emit-ts turns a configured MCP server into TypeScript artifacts so agents, tests, and tooling can consume the server through strongly typed APIs. It reuses the same buildToolDoc data that powers mcporter list , so doc comments, parameter hints, and signatures stay perfectly in sync. For a broader overview of every CLI command, see docs/cli-reference.md . 证据：`docs/emit-ts.md`\n- **Debugging Hanging mcporter Calls**（documentation）：When mcporter call prints a tool response but the process never exits, it usually means Node still has active handles it is waiting on. The most common culprit is a child MCP server process that keeps the stdio transport alive. 证据：`docs/hang-debug.md`\n- **Import Reference**（documentation）：mcporter merges your local config/mcporter.json with editor- or tool-specific config files so you can reuse servers without copying them manually. This document spells out the supported formats, the directories we scan for each import kind, and how precedence works. 证据：`docs/import.md`\n- **Try it**（documentation）：mcporter auto-discovers the MCP servers already configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, and VS Code. Try it without installing anything: 证据：`docs/index.md`\n- **Known Issues**（documentation）：This file tracks limitations that users regularly run into. Most of these require upstream cooperation or larger refactors—feel free to reference this when triaging bugs. 证据：`docs/known-issues.md`\n- **Live MCP Tests**（documentation）：These tests hit real hosted MCP servers and require outbound HTTP. They are off by default to keep CI and local runs deterministic. 证据：`docs/livetests.md`\n- **Running mcporter Locally**（documentation）：You don’t need npx every time—here are the three local entry points we use while developing mcporter itself. 证据：`docs/local.md`\n- **Logging & Diagnostics**（documentation）：The keep-alive daemon can tee its stdout/stderr and per-server call traces into a file so you can see crashes or repeated failures without rerunning it in the foreground. 证据：`docs/logging.md`\n- **Manual Testing Harness**（documentation）：When we need to sanity-check CLI flows against real MCP servers or reproduce bugs by hand , use this repeatable harness. Everything runs under tmux so long-running commands can be inspected without blocking the current shell. 证据：`docs/manual-testing.md`\n- **mcporter Overview**（documentation）：mcporter is the Sweetistics CLI + runtime for the Model Context Protocol MCP . It wraps the upstream TypeScript SDK with: 证据：`docs/mcp.md`\n- **Migration Guide**（documentation）：This guide walks through replacing the Python-based pnpm mcp: helpers with the new TypeScript runtime and CLI. 证据：`docs/migration.md`\n- **Migrating from pnpm mcp:**（documentation）：The legacy pnpm mcp: helpers map directly onto the mcporter CLI. 证据：`docs/pnpm-mcp-migration.md`\n- **Quickstart**（documentation）：This walkthrough assumes you already have an MCP server configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, or VS Code. If not, copy config/mcporter.example.json https://github.com/steipete/mcporter/blob/main/config/mcporter.example.json into ~/.mcporter/mcporter.json and edit it — see Configuration config.md for the full schema. 证据：`docs/quickstart.md`\n- **Next-Step Refactor Checklist**（documentation）：This doc tracks remaining reuse/refactor work now that the original plan is done. Each section lists the goal, why it matters, and the concrete steps/tests needed. 证据：`docs/refactor.md`\n- **Agent Shortcuts**（documentation）：These undocumented shortcuts are safe for MCP agents to call when they need a quick description of a server or its tools without memorizing the full mcporter CLI surface. 证据：`docs/shortcuts.md`\n- **mcporter Roadmap**（documentation）：Inspired in part by Anthropic’s guidance on MCP code execution agents: https://www.anthropic.com/engineering/code-execution-with-mcp 证据：`docs/spec.md`\n- **Claude Subagent Quickstart**（documentation）：- Never invoke subagents through ./runner —launch them inside tmux directly so the session can persist and bypass the runner timeouts. Example: 证据：`docs/subagent.md`\n- **OAuth Notes & Hosted MCP Compatibility**（documentation）：OAuth Notes & Hosted MCP Compatibility 证据：`docs/supabase-auth-issue.md`\n- **tmux Hang Diagnostics**（documentation）：Use tmux to verify whether a CLI command actually exits or is stalled on open handles. This keeps the main shell free while you inspect logs. 证据：`docs/tmux.md`\n- **Tool Calling Cheatsheet**（documentation）：mcporter accepts multiple argument styles so you can match whatever feels most natural in your shell or script. Every style feeds the same validation pipeline schema-driven type coercion, required-field checks, enum hints , so pick the one that's easiest to type. 证据：`docs/tool-calling.md`\n- **Installing dependencies**（documentation）：- pnpm install fails on /mnt/c because NTFS/DrvFs blocks futime . Clone/sync the repo to $HOME ext4 inside WSL and run ./runner pnpm install there instead. Example: rsync -a --delete --exclude node modules /mnt/c/Projects/mcporter/ ~/mcporter-wsl/ . - Keep $HOME/.bun/bin and $HOME/.local/share/pnpm on your PATH before invoking ./runner . Without Bun and pnpm the runner prints the guardrail error and exits. - If you must work from /mnt/c , remount with metadata support sudo mount -t drvfs C: /mnt/c -o metadata,uid=$ id -u ,gid=$ id -g ,umask=22,fmask=111 . Otherwise installs, chmods, and copyfile calls will continue to fail. 证据：`docs/windows.md`\n- **mcporter Changelog**（documentation）：- Make generate-cli --runtime node --bundle .mjs emit an ES module bundle with a local require shim, fixing .mjs artifacts that previously crashed at startup. - Classify generated .mjs and .cjs outputs as bundle artifacts in embedded metadata instead of reporting them as binaries. - Avoid leaving implicit .ts template files in the current directory when generating bundle-only artifacts without --output . - Print generated CLI help with a trailing newline so subsequent shell output no longer glues onto the help footer. - Point generated CLI metadata and npm package metadata at openclaw/mcporter . - Document the existing generate-cli --timeout , --minify , and --no-minify flags in generate-cl… 证据：`CHANGELOG.md`\n- **.Oxfmtrc**（structured_config）：{ \"$schema\": \"./node modules/oxfmt/configuration schema.json\", \"useTabs\": false, \"tabWidth\": 2, \"printWidth\": 120, \"singleQuote\": true, \"jsxSingleQuote\": false, \"quoteProps\": \"as-needed\", \"trailingComma\": \"es5\", \"semi\": true, \"arrowParens\": \"always\", \"bracketSameLine\": false, \"bracketSpacing\": true, \"ignorePatterns\": \"dist\", \"tmp\", \"node modules\" } 证据：`.oxfmtrc.json`\n- **.Oxlintrc**（structured_config）：{ \"$schema\": \"./node modules/oxlint/configuration schema.json\", \"plugins\": \"typescript\", \"unicorn\", \"oxc\" , \"categories\": { \"correctness\": \"error\", \"suspicious\": \"error\", \"perf\": \"error\" }, \"rules\": { \"no-await-in-loop\": \"off\", \"oxc/no-async-endpoint-handlers\": \"off\", \"typescript/no-unsafe-type-assertion\": \"off\", \"typescript/no-unnecessary-type-assertion\": \"off\", \"typescript/no-unnecessary-type-conversion\": \"off\", \"typescript/no-unnecessary-type-parameters\": \"off\", \"typescript/no-unnecessary-template-expression\": \"off\", \"unicorn/prefer-add-event-listener\": \"off\" }, \"env\": { \"builtin\": true } } 证据：`.oxlintrc.json`\n- **Mcporter**（structured_config）：{ \"mcpServers\": { \"chrome-devtools\": { \"description\": \"Chrome DevTools protocol bridge for driving local tabs during debugging or automation.\", \"command\": \"npx\", \"args\": \"-y\", \"chrome-devtools-mcp@latest\", \"--autoConnect\" , \"env\": { \"npm config loglevel\": \"error\" } }, \"mobile-mcp\": { \"description\": \"Mobile Next MCP server for automating iOS/Android simulators and devices.\", \"command\": \"npx\", \"args\": \"-y\", \"@mobilenext/mobile-mcp@latest\" , \"env\": { \"npm config loglevel\": \"error\" } }, \"context7\": { \"description\": \"Context7 MCP for React documentation lookup.\", \"baseUrl\": \"https://mcp.context7.com/mcp\" }, \"deepwiki\": { \"description\": \"DeepWiki MCP server for querying public code/docs without l… 证据：`config/mcporter.json`\n- **Mcporter.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"type\": \"object\", \"properties\": { \"mcpServers\": { \"type\": \"object\", \"propertyNames\": { \"type\": \"string\" }, \"additionalProperties\": { \"type\": \"object\", \"properties\": { \"description\": { \"description\": \"Human-readable description of the server\", \"type\": \"string\" }, \"baseUrl\": { \"description\": \"Base URL for HTTP/SSE transport camelCase \", \"type\": \"string\" }, \"base url\": { \"description\": \"Base URL for HTTP/SSE transport snake case \", \"type\": \"string\" }, \"url\": { \"description\": \"Server URL for HTTP/SSE transport\", \"type\": \"string\" }, \"serverUrl\": { \"description\": \"Server URL for HTTP/SSE transport camelCase \", \"type\": \"string\" }, \"serve… 证据：`mcporter.schema.json`\n- **Tsconfig.Build**（structured_config）：{ \"extends\": \"./tsconfig.json\", \"compilerOptions\": { \"rootDir\": \"./src\", \"outDir\": \"./dist\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"noEmit\": false }, \"exclude\": \"tests\", \"docs\", \"scripts\", \"dist\", \"node modules\" } 证据：`tsconfig.build.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"module\": \"ESNext\", \"moduleResolution\": \"Bundler\", \"target\": \"ES2023\", \"lib\": \"ES2023\", \"DOM\" , \"verbatimModuleSyntax\": true, \"allowImportingTsExtensions\": false, \"strict\": true, \"noUncheckedIndexedAccess\": true, \"resolveJsonModule\": true, \"skipLibCheck\": true, \"noEmit\": true, \"types\": \"node\", \"bun-types\" }, \"include\": \"src\", \"tests\", \"scripts\", \"docs\" } 证据：`tsconfig.json`\n- **Mcp**（structured_config）：{ \"mcpServers\": { \"claude-only\": { \"command\": \"claude-cli\", \"args\": \"--run\" } } } 证据：`tests/fixtures/imports/.claude/mcp.json`\n- **Settings**（structured_config）：{ \"mcpServers\": { \"claude-shared\": { \"command\": \"claude-shared-cli\" }, \"claude-overridden\": { \"command\": \"claude-shared-cli\" } } } 证据：`tests/fixtures/imports/.claude/settings.json`\n- **Settings.Local**（structured_config）：{ \"mcpServers\": { \"claude-local\": { \"command\": \"claude-local-cli\" }, \"claude-overridden\": { \"command\": \"claude-local-cli\" } } } 证据：`tests/fixtures/imports/.claude/settings.local.json`\n- **Mcp Config**（structured_config）：{ \"mcpServers\": { \"shared\": { \"baseUrl\": \"https://windsurf.local/mcp\" }, \"windsurf-only\": { \"command\": \"windsurf-cli\", \"args\": \"--list\" , \"env\": { \"WINDSURF\": \"1\" } } } } 证据：`tests/fixtures/imports/.codeium/windsurf/mcp_config.json`\n- **Mcp**（structured_config）：{ \"mcpServers\": { \"shared\": { \"baseUrl\": \"https://cursor.local/mcp\", \"httpFetch\": \"node-http1\", \"refresh\": { \"tokenEndpoint\": \"https://auth.cursor.local/token\", \"accessTokenEnv\": \"CURSOR ACCESS TOKEN\" } }, \"cursor-only\": { \"command\": \"cursor-cli\", \"args\": \"--flag\" , \"env\": { \"CURSOR FLAG\": \"1\" } } } } 证据：`tests/fixtures/imports/.cursor/mcp.json`\n- **Mcp**（structured_config）：{ \"mcpServers\": { \"shared\": { \"baseUrl\": \"https://vscode.local/mcp\" }, \"vscode-only\": { \"command\": \"code-mcp\", \"args\": \"--serve\" } } } 证据：`tests/fixtures/imports/Library/Application Support/Code/User/mcp.json`\n- **Mcporter**（structured_config）：{ \"imports\": \"cursor\", \"claude-code\", \"codex\" , \"mcpServers\": { \"local-only\": { \"baseUrl\": \"https://local.example/mcp\" }, \"cursor-only\": { \"baseUrl\": \"https://local.override/cursor\" } } } 证据：`tests/fixtures/imports/config/mcporter.json`\n- **Settings**（structured_config）：{ \"mcpServers\": { \"claude-home\": { \"command\": \"claude-home-cli\" } } } 证据：`tests/fixtures/imports/home/.claude/settings.json`\n- **Mcp Config**（structured_config）：{ \"mcpServers\": { \"shared\": { \"baseUrl\": \"https://windsurf.local/mcp\" }, \"windsurf-only\": { \"command\": \"windsurf-cli\", \"args\": \"--list\" , \"env\": { \"WINDSURF\": \"1\" } } } } 证据：`tests/fixtures/imports/home/.codeium/windsurf/mcp_config.json`\n- **Mcp**（structured_config）：{ \"mcpServers\": { \"shared\": { \"baseUrl\": \"https://vscode.local/mcp\" }, \"vscode-only\": { \"command\": \"code-mcp\", \"args\": \"--serve\" } } } 证据：`tests/fixtures/imports/home/Library/Application Support/Code/User/mcp.json`\n- **Mcporter**（structured_config）：{ \"mcpServers\": { \"chrome-devtools\": { \"description\": \"Chrome DevTools protocol bridge for driving local tabs during debugging or automation.\", \"command\": \"npx\", \"args\": \"-y\", \"chrome-devtools-mcp@latest\", \"--autoConnect\" , \"env\": { \"npm config loglevel\": \"error\" } }, \"context7\": { \"description\": \"Context7 MCP for React documentation lookup.\", \"baseUrl\": \"https://mcp.context7.com/mcp\" }, \"linear\": { \"description\": \"Hosted Linear MCP; exposes issue search, create, and workflow tooling.\", \"baseUrl\": \"https://mcp.linear.app/mcp\", \"headers\": { \"Authorization\": \"Bearer ${LINEAR API KEY}\" } }, \"next-devtools\": { \"description\": \"Next.js dev server introspection project metadata, logs, page insight… 证据：`tests/fixtures/mcporter.json`\n- **.gitattributes**（source_file）：text eol=lf .png binary .tar.gz binary .tgz binary 证据：`.gitattributes`\n- **Release archives**（source_file）：node modules .pnpm-store .DS Store dist dist-bun .bun-build Release archives mcporter- .tgz .tgz .sha1 .sha256 证据：`.gitignore`\n- **Logs**（source_file）：Logs npm-debug.log yarn-debug.log yarn-error.log 证据：`.npmignore`\n- **!/usr/bin/env bun**（source_file）：import { accessSync, constants, existsSync, realpathSync } from 'node:fs'; import { dirname, join, normalize, resolve, sep } from 'node:path'; import { fileURLToPath } from 'node:url'; import process from 'node:process'; import { analyzeGitExecution, evaluateGitPolicies } from '../scripts/git-policy'; 证据：`bin/git`\n- **Cname**（source_file）：mcporter.sh 证据：`docs/CNAME`\n- **Social Card**（source_file）：mcporter social card mcporter: MCP, made portable. TypeScript runtime, CLI, and code-generation toolkit for the Model Context Protocol. 证据：`docs/social-card.svg`\n- **!/usr/bin/env tsx**（source_file）：/ Example: fetch the README for a React-adjacent package from Context7 and print only the markdown headlines. / 证据：`examples/context7-headlines.ts`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/install.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/install.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n  - source_paths: README.md, package.json, src/index.ts\n- **安装指南**：importance `high`\n  - source_paths: docs/install.md, docs/windows.md\n- **快速入门**：importance `high`\n  - source_paths: docs/quickstart.md, src/cli.ts, src/cli/call-command.ts\n- **核心架构**：importance `high`\n  - source_paths: src/config.ts, src/config/read-config.ts, src/config-normalize.ts, src/config-schema.ts, src/lifecycle.ts\n- **运行时系统**：importance `high`\n  - source_paths: src/runtime.ts, src/runtime/utils.ts, src/runtime/errors.ts, src/server-proxy.ts, src/result-utils.ts\n- **传输层**：importance `high`\n  - source_paths: src/runtime/transport.ts, src/cli/transport-utils.ts, src/cli/http-utils.ts, src/runtime/node-http-fetch.ts\n- **CLI 命令参考**：importance `high`\n  - source_paths: docs/cli-reference.md, src/cli/cli-factory.ts, src/cli/list-command.ts, src/cli/serve-command.ts\n- **工具调用语法**：importance `high`\n  - source_paths: docs/call-syntax.md, src/cli/call-command.ts, src/cli/call-argument-expression.ts, src/cli/call-expression-parser.ts, src/cli/command-inference.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `ae3b83cecb0b69afc1e3e69e3730405bcca8ea91`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/import.md`, `docs/tool-calling.md`, `docs/call-syntax.md`, `docs/pnpm-mcp-migration.md`, `docs/cli-generator.md`, `docs/index.md`, `docs/adhoc.md`, `docs/refactor.md`, `docs/daemon.md`, `docs/logging.md`, `docs/cli-reference.md`, `docs/quickstart.md`, `docs/call-heuristic.md`, `docs/windows.md`, `docs/install.md`, `docs/local.md`, `docs/subagent.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：`daemonIdleTimeoutMs` missing?\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`daemonIdleTimeoutMs` missing?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n- Trigger: why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：steipete/mcporter\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：`daemonIdleTimeoutMs` missing?（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/steipete/mcporter 项目说明书\n\n生成时间：2026-05-18 21:37:46 UTC\n\n## 目录\n\n- [项目概述](#page-project-overview)\n- [安装指南](#page-installation-guide)\n- [快速入门](#page-quick-start)\n- [核心架构](#page-core-architecture)\n- [运行时系统](#page-runtime-system)\n- [传输层](#page-transport-layer)\n- [CLI 命令参考](#page-cli-reference)\n- [工具调用语法](#page-call-syntax)\n- [调用启发式与自动更正](#page-call-heuristic)\n- [配置管理](#page-configuration)\n\n<a id='page-project-overview'></a>\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [快速入门](#page-quick-start), [安装指南](#page-installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/index.ts](https://github.com/steipete/mcporter/blob/main/src/index.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n</details>\n\n# 项目概述\n\nmcporter 是一个命令行工具，用于统一管理和调用 MCP（Model Context Protocol）服务器。它提供了配置管理、服务器调用、工具生成等核心功能，帮助开发者更高效地集成和操作 MCP 服务。\n\n## 核心定位\n\nmcporter 的设计目标是为 MCP 服务器提供统一的入口层：\n\n- **配置管理**：集中管理多个 MCP 服务器配置\n- **工具调用**：通过 CLI 直接调用 MCP 工具\n- **类型生成**：自动生成 TypeScript 类型定义和客户端代码\n- **跨编辑器兼容**：支持导入/导出 Cursor、Claude、VS Code 等编辑器的 MCP 配置\n\n资料来源：[README.md:1-15]()\n\n## 核心命令\n\nmcporter 提供了以下主要命令：\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `config` | 管理 MCP 配置 | `mcporter config list`、`mcporter config add` |\n| `list` | 列出可用工具 | `mcporter list <server>` |\n| `call` | 调用 MCP 工具 | `mcporter call <server>.<tool>` |\n| `generate-cli` | 生成独立 CLI | `mcporter generate-cli --command <url>` |\n| `emit-ts` | 生成 TypeScript 类型 | `mcporter emit-ts <server> --out types/` |\n\n资料来源：[README.md:60-85]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n    A[用户 CLI] --> B[mcporter 核心]\n    B --> C{命令路由}\n    C -->|config| D[配置管理模块]\n    C -->|list| E[服务器列表模块]\n    C -->|call| F[工具调用模块]\n    C -->|generate-cli| G[代码生成模块]\n    C -->|emit-ts| H[类型生成模块]\n    D --> I[配置文件<br/>mcporter.json]\n    D --> J[外部导入<br/>Cursor/Claude/VS Code]\n    E --> K[运行时引擎]\n    F --> K\n    K --> L[MCP 协议栈]\n    L --> M[HTTP 传输]\n    L --> N[SSE 传输]\n    L --> O[STDIO 传输]\n```\n\n## 配置系统\n\n### 配置文件格式\n\nmcporter 使用 `config/mcporter.json` 作为主配置文件，格式兼容 JSONC（支持注释和尾随逗号）：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n资料来源：[README.md:30-50]()\n\n### 配置导入功能\n\nmcporter 支持从多种编辑器和工具导入 MCP 配置：\n\n| 来源 | 支持的容器 |\n|------|-----------|\n| Cursor | `mcpServers`、`servers`、`mcp` |\n| Claude Code | `mcpServers`、`servers`、`mcp` |\n| VS Code | `mcpServers`、`servers`、`mcp` |\n| Windsurf | `mcpServers`、`servers`、`mcp` |\n\n资料来源：[README.md:35-40]()\n\n配置导入时支持模糊匹配和自动纠错，例如输入 `sshadcn` 会自动纠正为 `shadcn`。\n\n资料来源：[README.md:45-47]()\n\n## 运行时引擎\n\n运行时引擎是 mcporter 的核心，负责与 MCP 服务器建立连接并执行调用：\n\n```mermaid\nsequenceDiagram\n    用户 ->> CLI: mcporter call server.tool\n    CLI ->> Runtime: createRuntime(config)\n    Runtime ->> Definition: getDefinitions()\n    Definition -->> Runtime: ServerDefinition[]\n    Runtime ->> Transport: 建立连接\n    Transport -->> Runtime: 连接就绪\n    Runtime ->> MCP: callTool(name, args)\n    MCP -->> Runtime: CallResult\n    Runtime -->> CLI: 格式化输出\n    CLI ->> 用户: 显示结果\n```\n\n资料来源：[src/cli/list-command.ts:1-30]()\n\n### 传输类型支持\n\n| 传输类型 | 说明 | 配置字段 |\n|----------|------|----------|\n| HTTP | 基于 HTTP 的请求-响应模式 | `baseUrl` |\n| SSE | Server-Sent Events 模式 | `baseUrl` + `sse` |\n| STDIO | 标准输入输出通信 | `command` + `args` |\n\n资料来源：[src/cli/config/help.ts:5-10]()\n\n## 生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n```mermaid\ngraph LR\n    A[生命周期] --> B[keep-alive]\n    A --> C[ephemeral]\n    B --> D{空闲超时}\n    D -->|无超时| E[持续运行]\n    D -->|设置超时| F[idleTimeoutMs]\n    C --> G[调用后立即关闭]\n```\n\n| 模式 | 说明 | 配置值 |\n|------|------|--------|\n| `keep-alive` | 服务器持续运行，可复用连接 | `\"keep-alive\"` 或 `{ mode: \"keep-alive\", idleTimeoutMs: number }` |\n| `ephemeral` | 每次调用后关闭服务器 | `\"ephemeral\"` |\n\n资料来源：[src/lifecycle.ts:25-40]()\n\n## 工具调用与结果处理\n\n### 调用语法\n\n```bash\nmcporter call <server>.<tool> [key=value ...] [--tool-arg <json>]\n```\n\nmcporter 支持多种参数格式：\n\n- `key=value` 形式\n- `key:value` 形式\n- 尾随位置参数\n- `--tool-arg` JSON 格式\n\n资料来源：[README.md:70-80]()\n\n### 结果类型\n\n调用结果包装在 `CallResult` 对象中，提供多种访问方式：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `.text()` | `string \\| null` | 获取文本内容 |\n| `.markdown()` | `string \\| null` | 获取 Markdown 内容 |\n| `.json()` | `unknown` | 获取 JSON 数据 |\n| `.images()` | `ImageContent[] \\| null` | 获取图片内容 |\n| `.content()` | `string[]` | 获取所有文本内容 |\n| `.raw` | `CallResultEnvelope` | 获取原始响应 |\n\n资料来源：[README.md:110-120]()\n\n### 资源收集逻辑\n\n```mermaid\ngraph TD\n    A[CallResult] --> B{内容类型}\n    B -->|text| C[直接添加]\n    B -->|markdown| D[添加并标记]\n    B -->|image| E[收集 mimeType + data]\n    B -->|resource| F{资源类型}\n    F -->|text| G[解析 JSON 后添加]\n    F -->|blob| H[输出为文本占位符]\n    C --> I[textEntries]\n    D --> I\n    G --> I\n    E --> J[images]\n    H --> I\n```\n\n资料来源：[src/result-utils.ts:15-55]()\n\n## 代码生成功能\n\n### 生成独立 CLI\n\n```bash\nnpx mcporter generate-cli \\\n  --command https://mcp.context7.com/mcp\n```\n\n输出文件：\n- `context7.ts` - TypeScript 模板\n- `context7.js` - 打包后的可执行 CLI\n\n生成的 CLI 嵌入元数据，支持通过 `mcporter inspect-cli` 查看信息或 `mcporter generate-cli --from` 重新生成。\n\n资料来源：[README.md:90-110]()\n\n### 生成 TypeScript 类型\n\n```bash\n# 仅生成类型定义\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成客户端包装器\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n| 模式 | 输出内容 |\n|------|----------|\n| `types`（默认） | `.d.ts` 接口定义 |\n| `client` | `.d.ts` + `.ts` 客户端包装 |\n\n资料来源：[README.md:125-140]()\n\n## 命令行选项参考\n\n### 全局选项\n\n| 选项 | 说明 | 环境变量 |\n|------|------|----------|\n| `--config <path>` | 自定义配置文件路径 | `MCPORTER_CONFIG` |\n| `--root <path>` | 工作目录（用于 stdio 命令） | `MCPORTER_ROOT` |\n| `--log-level <level>` | 日志级别 | `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 等待超时 | `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--tail-log` | 尾随日志输出 | - |\n\n资料来源：[README.md:55-65]()\n\n### list 命令选项\n\n| 选项 | 说明 |\n|------|------|\n| `--all-parameters` | 显示所有可选参数 |\n| `--schema` | 显示 JSON Schema |\n| `--brief` | 简洁输出 |\n| `--json` | JSON 格式输出 |\n| `--timeout <ms>` | 连接超时 |\n\n资料来源：[src/cli/list-command.ts:80-100]()\n\n### call 命令选项\n\n| 选项 | 说明 |\n|------|------|\n| `--raw-strings` | 保持数值型参数为字符串 |\n| `--no-coerce` | 禁用类型转换 |\n| `--save-images <dir>` | 保存图片到目录 |\n| `--raw` | 原始输出格式 |\n| `--` | 停止标志解析 |\n\n资料来源：[README.md:75-80]()\n\n## 错误处理与诊断\n\n### 状态分类\n\n| 状态 | 说明 | 颜色标识 |\n|------|------|----------|\n| `ok` | 调用成功 | 绿色 |\n| `auth` | 认证失败 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 橙色 |\n| `error` | 一般错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:10-25]()\n\n### 诊断命令\n\n```bash\n# 查看服务器状态摘要\nmcporter list --json\n\n# 尾随相关日志\nmcporter call <server>.<tool> --tail-log\n```\n\n## 技术栈\n\n| 组件 | 技术 | 用途 |\n|------|------|------|\n| CLI 框架 | TypeScript | 类型安全 |\n| 传输层 | Bun/Node.js | HTTP/SSE/STDIO |\n| 配置解析 | JSONC | 支持注释的 JSON |\n| 代码打包 | Rolldown/Bun | 生成可执行 CLI |\n\n资料来源：[README.md:100-105]()\n\n## 总结\n\nmcporter 作为一个 MCP 统一管理工具，提供了从配置管理到工具调用、再到代码生成的完整工具链。它的设计强调：\n\n1. **统一性**：多种 MCP 服务器的集中管理\n2. **兼容性**：支持多种编辑器和工具的配置导入\n3. **开发者体验**：模糊匹配、自动纠错、类型生成\n4. **灵活性**：多种传输协议和生命周期管理\n\n通过 mcporter，开发者可以快速集成 MCP 服务器到自己的工作流程中，无需关心底层协议细节。\n\n---\n\n<a id='page-installation-guide'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速入门](#page-quick-start), [项目概述](#page-project-overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)\n- [docs/emit-ts.md](https://github.com/steipete/mcporter/blob/main/docs/emit-ts.md)\n</details>\n\n# 安装指南\n\nmcporter 是一个 MCP（Model Context Protocol）服务器启动器和客户端工具，用于连接和管理各种 MCP 服务器。本指南详细介绍 mcporter 的多种安装方式、项目配置以及进阶用法。\n\n## 环境要求\n\n### 运行时依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0+ | 支持 ES Modules 和原生 HTTP 客户端 |\n| pnpm | 推荐使用 | 项目首选包管理器 |\n| npm | 兼容 | 可作为替代方案 |\n| Homebrew | 最新版 | macOS/Linux 用户可选 |\n\n### 系统要求\n\n- macOS、Linux 或 Windows（通过 WSL 或 Git Bash）\n- 网络连接（用于访问远程 MCP 服务器）\n- OAuth 认证需要浏览器环境\n\n## 安装方式\n\n### 通过 pnpm 安装（推荐）\n\n将 mcporter 添加为项目依赖：\n\n```bash\npnpm add mcporter\n```\n\n这种方式适合在项目内部使用 mcporter API，或者通过 `pnpm exec mcporter` 调用。资料来源：[README.md]()\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g mcporter\n```\n\n安装后可在任意目录直接使用 `mcporter` 命令。资料来源：[README.md]()\n\n### 通过 Homebrew 安装（macOS/Linux）\n\n```bash\nbrew tap steipete/tap\nbrew install steipete/tap/mcporter\n```\n\n> **提示**：Homebrew tap 与 npm 同步发布。如果遇到问题，运行 `brew update` 后重新安装。资料来源：[README.md]()\n\n## 配置管理\n\n### 配置文件位置\n\nmcporter 默认从以下位置读取配置（按优先级排序）：\n\n1. `./config/mcporter.json`（项目本地）\n2. `./config/mcporter.jsonc`（支持注释的配置）\n3. `~/.mcporter/config.json`（用户级别）\n\n### 配置命令\n\n| 命令 | 功能 |\n|------|------|\n| `mcporter config list` | 列出所有本地 MCP 服务器配置 |\n| `mcporter config get <name>` | 获取指定服务器的配置详情 |\n| `mcporter config add` | 交互式添加新服务器 |\n| `mcporter config remove <name>` | 删除服务器配置 |\n| `mcporter config import <kind>` | 从编辑器（Cursor/Claude）导入配置 |\n\n资料来源：[README.md]()\n\n### 配置文件格式\n\nmcporter 使用 JSONC 格式，支持注释和尾随逗号：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    },\n    \"chrome-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"@modelcontextprotocol/server-chrome-devtools\"]\n    }\n  }\n}\n```\n\n## 命令行用法\n\n### 常用命令\n\n| 命令 | 说明 |\n|------|------|\n| `mcporter list` | 列出所有已配置的 MCP 服务器及其工具 |\n| `mcporter call <server>.<tool>` | 调用指定服务器的指定工具 |\n| `mcporter generate-cli` | 从 MCP 服务器生成独立的 CLI |\n| `mcporter emit-ts` | 生成 TypeScript 类型定义 |\n| `mcporter inspect-cli` | 检查已生成的 CLI 元数据 |\n\n### 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config <path>` | 指定配置文件路径（默认 `./config/mcporter.json`） |\n| `--root <path>` | 设置 stdio 命令的工作目录 |\n| `--log-level <level>` | 日志级别：`debug`、`info`、`warn`、`error` |\n| `--oauth-timeout <ms>` | OAuth 浏览器等待超时 |\n| `--output <format>` | 输出格式：`json` 或美化输出 |\n\n资料来源：[README.md](), [src/cli/config/help.ts]()\n\n## 编程接口\n\n### One-shot 调用\n\n适合单次执行任务的场景：\n\n```typescript\nimport { callOnce } from 'mcporter';\n\nconst result = await callOnce({\n  server: 'firecrawl',\n  toolName: 'crawl',\n  args: { url: 'https://anthropic.com' },\n});\n\nconsole.log(result);\n```\n\n`callOnce` 会自动发现服务器、处理 OAuth 认证并在完成后关闭传输。资料来源：[README.md]()\n\n### 运行时 API\n\n适合需要多次调用或高级配置的场景：\n\n```typescript\nimport { createRuntime } from 'mcporter';\n\nconst runtime = await createRuntime();\n\nconst tools = await runtime.listTools('context7');\nconst result = await runtime.callTool('context7', 'resolve-library-id', {\n  args: { query: 'React hooks docs', libraryName: 'react' },\n});\n\nawait runtime.close();\n```\n\n### 生成类型化客户端\n\n#### 仅生成类型定义\n\n```bash\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n```\n\n#### 生成客户端包装器\n\n```bash\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n可用选项：\n\n| 选项 | 说明 |\n|------|------|\n| `--mode types` | 仅生成 `.d.ts` 接口（默认） |\n| `--mode client` | 生成 `.d.ts` 和 `.ts` 包装器 |\n| `--include-optional` | 展开所有可选字段 |\n| `--json` | 输出结构化摘要（用于脚本） |\n\n资料来源：[README.md](), [docs/emit-ts.md]()\n\n## OAuth 认证配置\n\n### OAuth 选项\n\n| 选项 | 说明 |\n|------|------|\n| `--oauth-client-id <id>` | 使用预注册的 OAuth 客户端 ID |\n| `--oauth-client-secret-env <env>` | 从环境变量读取客户端密钥 |\n| `--oauth-redirect-url <url>` | 设置自定义重定向 URL |\n| `--token-cache-dir <path>` | 覆盖 OAuth 令牌持久化位置 |\n\n### 清除认证\n\n```bash\nmcporter config logout <server-name>\n```\n\n资料来源：[README.md](), [src/cli/config/help.ts]()\n\n## 生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 说明 |\n|------|------|\n| `ephemeral` | 每次调用后自动终止服务器（默认） |\n| `keep-alive` | 保持服务器运行，复用连接 |\n\n可通过配置文件或命令行设置：\n\n```json\n{\n  \"mcpServers\": {\n    \"example\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"example-server\"],\n      \"lifecycle\": \"keep-alive\"\n    }\n  }\n}\n```\n\n资料来源：[src/lifecycle.ts]()\n\n## 工具列表与调用\n\n### 列出服务器工具\n\n```bash\n# 列出所有服务器的工具\nmcporter list\n\n# 列出单个服务器的详细工具信息\nmcporter list context7\n\n# 输出 JSON 格式\nmcporter list --json\n```\n\n### 调用工具\n\n```bash\n# 基本调用\nmcporter call context7.resolve-library-id --args query=\"React hooks\"\n\n# 使用参数文件\nmcporter call server.tool --args-file params.json\n\n# 保存图片输出\nmcporter call server.tool --save-images ./output-dir\n```\n\n参数值默认会自动转换类型。使用 `--raw-strings` 可保持原始字符串格式，`--no-coerce` 可禁用所有类型转换。资料来源：[README.md](), [src/cli/list-command.ts]()\n\n## 故障排除\n\n### 常见问题\n\n1. **服务器连接超时**\n   - 检查网络连接\n   - 使用 `--log-level debug` 查看详细日志\n   - 调整 `--oauth-timeout` 值\n\n2. **OAuth 认证失败**\n   - 确认浏览器可以打开重定向 URL\n   - 检查 `--oauth-redirect-url` 配置\n   - 清除旧的认证：`mcporter config logout <server>`\n\n3. **配置找不到**\n   - 使用 `--config <path>` 指定配置文件\n   - 使用 `mcporter config list` 查看已加载的配置\n\n### 日志调试\n\n```bash\nmcporter list --log-level debug --tail-log\n```\n\n`--tail-log` 选项会流式输出相关日志文件的最后 20 行。资料来源：[README.md]()\n\n---\n\n<a id='page-quick-start'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[CLI 命令参考](#page-cli-reference), [工具调用语法](#page-call-syntax), [配置管理](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n</details>\n\n# 快速入门\n\nmcporter 是一个强大的 MCP（Model Context Protocol）客户端工具，提供命令行界面来管理、调用和调试 MCP 服务器。本指南将帮助您快速掌握 mcporter 的核心功能，从安装配置到日常使用。\n\n## 安装与基础配置\n\n### 安装方式\n\nmcporter 支持多种包管理器安装方式，开发者可根据项目环境选择最适合的方案：\n\n| 包管理器 | 安装命令 |\n|---------|---------|\n| pnpm | `pnpm add -g mcporter` |\n| npm | `npm install -g mcporter` |\n| npx | `npx mcporter` |\n\n资料来源：[README.md:1-15]()\n\n### 配置文件位置\n\nmcporter 默认使用 `./config/mcporter.json` 作为配置文件，同时也支持 JSONC 格式，允许使用 `//` 和 `/* ... */` 注释以及尾随逗号。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\",\n      }\n    }\n  }\n}\n```\n\n资料来源：[README.md:45-60]()\n\n### 常用命令行参数\n\n| 参数 | 说明 | 默认值 |\n|-----|------|-------|\n| `--config <path>` | 指定配置文件路径 | `./config/mcporter.json` |\n| `--root <path>` | 设置 stdio 命令的工作目录 | 当前目录 |\n| `--log-level <level>` | 日志级别（debug/info/warn/error） | 参考 `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 浏览器等待超时 | 参考 `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--output <format>` | 输出格式控制 | 自动检测 |\n| `--raw` | 原始输出，不进行格式化 | - |\n\n资料来源：[README.md:20-35]()\n\n## 列出可用服务器与工具\n\n### 基础列表命令\n\n使用 `mcporter list` 命令查看所有已配置的 MCP 服务器及其状态：\n\n```bash\nmcporter list\n```\n\n该命令会检查每个服务器的可访问性，并显示工具数量、连接耗时和状态信息。状态分类包括：\n\n| 状态类别 | 说明 | 颜色标识 |\n|---------|------|---------|\n| `ok` | 服务器正常响应 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 蓝色 |\n| `error` | 连接错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:1-30]()\n\n### 查看特定服务器的工具\n\n当您指定服务器名称时，mcporter 会显示该服务器的所有可用工具及其详细签名：\n\n```bash\nmcporter list <server>\nmcporter list context7\n```\n\n工具详情包括：\n- **工具名称**：MCP 服务器暴露的函数名\n- **输入模式（Input Schema）**：参数定义，包含类型和约束\n- **描述信息**：工具功能说明\n- **示例调用**：常用参数组合示例\n\n资料来源：[src/cli/list-command.ts:1-50]()\n\n### 过滤工具输出\n\n| 过滤选项 | 说明 |\n|---------|------|\n| `--brief` | 仅显示简要签名 |\n| `--signatures` | 显示紧凑签名 |\n| `--required-only` | 仅显示必需参数 |\n| `--all-parameters` | 显示所有参数（包括可选） |\n| `--schema` | 显示完整 JSON Schema |\n\n```bash\n# 简要输出\nmcporter list context7 --brief\n\n# 显示所有参数\nmcporter list context7 --all-parameters\n\n# 指定特定工具\nmcporter list context7.shadcn_getComponents\n```\n\n资料来源：[src/cli/list-command.ts:50-100]()\n\n## 调用 MCP 工具\n\n### 基础调用语法\n\n使用 `mcporter call` 命令调用服务器上的工具：\n\n```bash\nmcporter call <server>.<tool> [参数...]\nmcporter call context7.resolve-library library_name=\"shadcn\"\n```\n\nmcporter 会自动处理：\n- 参数类型转换（布尔值、数字、JSON）\n- 必需参数验证\n- 位置参数到命名参数的映射\n\n资料来源：[src/cli/call-command.ts:1-40]()\n\n### 参数传递方式\n\n#### 命名参数\n\n```bash\n# 使用 key=value 格式\nmcporter call server.tool arg1=value1 arg2=value2\n\n# 使用 key:value 格式\nmcporter call server.tool arg1:value1 arg2:value2\n```\n\n#### 位置参数\n\n当工具参数按声明顺序传递时，mcporter 会根据工具的输入模式自动匹配：\n\n```bash\nmcporter call context7.resolve-library shadcn\n```\n\n如果位置参数数量超过剩余必需参数数量，命令会报错并提示正确的参数数量。\n\n资料来源：[src/cli/call-command.ts:40-80]()\n\n### 参数类型处理\n\nmcporter 支持智能类型推断：\n\n| 输入格式 | 推断类型 | 示例 |\n|---------|---------|------|\n| `true` / `false` | 布尔值 | `enabled=true` |\n| `123` / `3.14` | 数字 | `count=42` |\n| `\"text\"` 或 `'text'` | 字符串 | `name=\"test\"` |\n| `{...}` / `[...]` | JSON 对象/数组 | `config={\"key\":1}` |\n| 不符合以上格式 | 字符串 | `text=abc` |\n\n使用 `--no-coerce` 可禁用类型推断，保持所有值为原始字符串。\n\n```bash\n# 禁用类型转换\nmcporter call server.tool --no-coerce arg1=value1\n```\n\n资料来源：[src/cli/call-command.ts:80-120]()\n\n### 处理工具输出\n\n`mcporter call` 返回的结果封装在 `CallResult` 对象中，支持多种访问方式：\n\n| 方法 | 说明 | 返回类型 |\n|-----|------|---------|\n| `.text()` | 获取纯文本内容 | `string \\| null` |\n| `.markdown()` | 获取 Markdown 内容 | `string \\| null` |\n| `.json()` | 解析 JSON 内容 | `object \\| null` |\n| `.images()` | 获取图片内容 | `ImageContent[] \\| null` |\n| `.content()` | 获取原始内容项 | `ContentBlock[]` |\n| `.raw` | 获取完整响应信封 | `CallResponse` |\n\n```bash\n# 格式化输出（默认）\nmcporter call context7.resolve-library library_name=\"shadcn\"\n\n# 原始输出\nmcporter call context7.resolve-library --raw library_name=\"shadcn\"\n\n# JSON 格式\nmcporter call context7.resolve-library --json library_name=\"shadcn\"\n```\n\n资料来源：[src/result-utils.ts:1-50]()\n\n### 保存图片内容\n\n某些 MCP 工具会返回图片内容，使用 `--save-images` 参数可以将其保存到指定目录：\n\n```bash\nmcporter call server.tool --save-images ./output_dir arg1=value1\n```\n\n图片会按工具响应中的顺序编号保存，输出形状保持不变。\n\n资料来源：[README.md:30-35]()\n\n## 服务器生命周期管理\n\nmcporter 支持不同的服务器生命周期模式，决定工具调用后服务器的运行行为：\n\n| 生命周期模式 | 说明 | 配置方式 |\n|------------|------|---------|\n| `ephemeral` | 调用后立即关闭（默认） | `lifecycle: \"ephemeral\"` |\n| `keep-alive` | 保持运行状态 | `lifecycle: \"keep-alive\"` |\n| `keep-alive` + `idleTimeoutMs` | 空闲超时后关闭 | `lifecycle: { mode: \"keep-alive\", idleTimeoutMs: 60000 }` |\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"some-mcp-server\"],\n      \"lifecycle\": {\n        \"mode\": \"keep-alive\",\n        \"idleTimeoutMs\": 300000\n      }\n    }\n  }\n}\n```\n\n资料来源：[src/lifecycle.ts:1-30]()\n\n### 动态端口处理\n\n某些服务器（如 chrome-devtools）需要动态分配端口。mcporter 会自动检测并处理以下场景：\n\n- 检测命令参数中的端口占位符\n- 在运行时分配可用端口\n- 将端口信息传递给子进程\n\n## 配置管理\n\n### 交互式配置命令\n\n使用 `mcporter config` 子命令进行配置管理：\n\n| 子命令 | 说明 |\n|-------|------|\n| `config list` | 列出本地配置 |\n| `config get <name>` | 获取配置项详情 |\n| `config add <name>` | 添加新配置 |\n| `config remove <name>` | 删除配置 |\n| `config import <kind>` | 导入其他编辑器的配置 |\n| `config logout <name>` | 清除认证信息 |\n\n```bash\n# 查看所有配置\nmcporter config list\n\n# 获取特定配置\nmcporter config get context7\n\n# 添加新服务器\nmcporter config add my-server --command \"npx\" --arg \"-y\" --arg \"my-mcp-server\"\n\n# 导入其他编辑器的配置\nmcporter config import cursor --copy\n```\n\n资料来源：[src/cli/config/help.ts:1-50]()\n\n### 配置查找与自动补全\n\nmcporter 使用模糊匹配来查找服务器名称，即使输入有拼写错误也能找到正确的配置：\n\n```bash\n# 错误拼写会自动纠正\nmcporter list sshadcn\n# 输出: sshadcn → shadcn (自动纠正提示)\n\n# 服务器选择器支持 .tool 语法\nmcporter list context7.resolve-library\n```\n\n资料来源：[src/cli/list-command.ts:100-150]()\n\n### 多环境配置\n\n支持使用 `--config` 和 `--root` 参数切换不同的配置环境：\n\n```bash\n# 使用项目级配置\nmcporter list --config ./project/config/mcporter.json\n\n# 设置工作目录\nmcporter call server.tool --root /path/to/project arg1=value1\n```\n\n## 生成工具客户端\n\n### 生成 TypeScript 类型定义\n\n使用 `emit-ts` 命令生成强类型工具接口：\n\n```bash\n# 仅生成类型定义\nnpx mcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成带客户端包装器\nnpx mcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n| 模式 | 输出 | 说明 |\n|-----|------|------|\n| `types`（默认） | `.d.ts` | 仅包含 Promise 签名的接口 |\n| `client` | `.d.ts` + `.ts` | 包含类型定义和 `createRuntime`/`createServerProxy` 包装器 |\n\n附加选项：\n- `--include-optional`：展开所有可选字段\n- `--json`：输出结构化摘要而非纯文本\n\n资料来源：[README.md:100-120]()\n\n### 生成独立 CLI 工具\n\n将 MCP 服务器转换为独立的可分发 CLI：\n\n```bash\n# 从 URL 生成\nnpx mcporter generate-cli --command https://mcp.context7.com/mcp\n\n# 从 npm 包生成\nnpx mcporter generate-cli \"npx -y chrome-devtools-mcp@latest\"\n\n# 指定输出名称\nnpx mcporter generate-cli --command https://mcp.context7.com/mcp --name context7\n```\n\n生成的工件包含：\n- `context7.ts`：TypeScript 模板 + 嵌入的 schema\n- `context7.js`：打包后的 CLI（使用 Rolldown 或 Bun）\n\n```bash\n# 检查已生成的 CLI\nnpx mcporter inspect-cli dist/context7.js\n\n# 重新生成（使用嵌入的元数据）\nnpx mcporter generate-cli --from dist/context7.js\n```\n\n资料来源：[README.md:80-100]()\n\n## 常见工作流程\n\n### 流程图：基础调用流程\n\n```mermaid\ngraph TD\n    A[开始] --> B[配置 mcporter.json]\n    B --> C[运行 mcporter list]\n    C --> D{服务器可用?}\n    D -->|是| E[运行 mcporter call]\n    D -->|否| F[检查配置和网络]\n    F --> C\n    E --> G[解析 CallResult]\n    G --> H[提取所需格式]\n    H --> I[结束]\n```\n\n### 流程图：工具调用处理\n\n```mermaid\ngraph TD\n    A[mcporter call 命令] --> B[解析参数]\n    B --> C{使用 --no-coerce?}\n    C -->|是| D[保持字符串类型]\n    C -->|否| E[智能类型推断]\n    E --> F[验证必需参数]\n    F --> G{参数完整?}\n    G -->|否| H[显示错误信息]\n    G -->|是| I[构建 MCP 请求]\n    I --> J[发送请求到服务器]\n    J --> K[接收响应]\n    K --> L[包装为 CallResult]\n    L --> M[返回给调用者]\n```\n\n### 典型使用场景\n\n#### 场景一：快速查询文档\n\n```bash\n# 1. 列出可用服务器\nmcporter list\n\n# 2. 查看特定服务器工具\nmcporter list context7\n\n# 3. 调用文档查询工具\nmcporter call context7.resolve-library library_name=\"shadcn\"\n```\n\n#### 场景二：调试 MCP 服务器\n\n```bash\n# 使用 verbose 模式查看详细信息\nmcporter list context7 --verbose\n\n# 启用调试日志\nmcporter list --log-level debug\n\n# 查看日志尾随内容\nmcporter call server.tool --tail-log\n```\n\n#### 场景三：自动化脚本集成\n\n```bash\n#!/bin/bash\n# 批量调用脚本\n\nSERVERS=(\"context7\" \"shadcn\" \"linear\")\nfor server in \"${SERVERS[@]}\"; do\n    echo \"检查服务器: $server\"\n    mcporter list \"$server\" --json | jq -r '.status'\ndone\n```\n\n## 故障排除\n\n### 常见问题与解决方案\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 连接超时 | 服务器未启动或网络问题 | 检查 `--timeout` 设置，使用 `--tail-log` 查看日志 |\n| 认证失败 | OAuth token 过期 | 运行 `mcporter config logout <name>` 后重新认证 |\n| 工具未找到 | 名称拼写错误或服务器未启动 | 使用 `mcporter list` 确认工具存在 |\n| 参数类型错误 | 字符串被错误解析为数字 | 使用 `--no-coerce` 或显式使用引号 |\n\n### 调试模式\n\n启用详细日志进行问题排查：\n\n```bash\n# 设置日志级别\nexport MCPORTER_LOG_LEVEL=debug\n\n# 运行命令\nmcporter call server.tool arg=value\n\n# 或直接在命令中指定\nmcporter call server.tool arg=value --log-level debug\n```\n\n使用 `--tail-log` 查看关联的日志文件：\n\n```bash\nmcporter call server.tool --tail-log\n```\n\n## 下一步\n\n- 阅读 [配置参考文档](docs/config.md) 了解更多配置选项\n- 查看 [Agent Skills 指南](docs/agent-skills.md) 了解如何为 AI Agent 创建技能\n- 参考 [emit-ts 文档](docs/emit-ts.md) 生成强类型客户端\n\n---\n\n<a id='page-core-architecture'></a>\n\n## 核心架构\n\n### 相关页面\n\n相关主题：[运行时系统](#page-runtime-system), [传输层](#page-transport-layer), [配置管理](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n- [src/cli.ts](https://github.com/steipete/mcporter/blob/main/src/cli.ts)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n</details>\n\n# 核心架构\n\nmcporter 是一个用于管理 MCP（Model Context Protocol）服务器的 CLI 工具，其核心架构围绕配置管理、运行时生命周期、CLI 命令解析和结果处理四大模块展开。\n\n## 架构总览\n\nmcporter 的设计采用了分层架构模式，核心组件包括：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| CLI 层 | `src/cli.ts` | 命令行入口、参数解析、路由分发 |\n| 命令层 | `src/cli/list-command.ts` | list/list-format/list-output 子系统 |\n| 配置层 | `src/config/` | 配置读取、规范化、导入 |\n| 运行时层 | `src/runtime.ts` | MCP 服务器生命周期管理 |\n| 工具层 | `src/lifecycle.ts` | 服务端生命周期控制 |\n\n## 配置管理模块\n\n### 配置解析流程\n\n配置管理模块负责加载和规范化用户配置。mcporter 支持多种配置格式，包括 `mcporter.json` 和 `mcporter.jsonc`（支持注释和尾随逗号的 JSON）。\n\n### 配置导入机制\n\n外部配置导入功能支持从多种编辑器配置中读取 MCP 服务器定义：\n\n```typescript\n// 支持的配置容器\n{\n  allowMcpServers: true,   // 标准 mcpServers\n  allowServers: true,      // servers 容器\n  allowMcp: true,          // mcp 容器\n  allowRootFallback: true  // 根目录回退\n}\n```\n\n资料来源：[src/config/imports/external.ts:15-25]()\n\n对于 Claude Code 配置，有特殊的路径规范化逻辑：\n\n```typescript\nconst allowRootFallback =\n  normalized.endsWith('.claude.json') || \n  normalized.endsWith(`${path.sep}.claude${path.sep}mcp.json`);\n```\n\n资料来源：[src/config/imports/external.ts:11-14]()\n\n### 配置值转换\n\n配置导入模块提供了类型安全的数据转换工具：\n\n| 函数 | 作用 |\n|------|------|\n| `asString()` | 提取非空字符串值 |\n| `asStringRecord()` | 将混合类型对象转换为字符串记录 |\n| `shouldIgnoreParseError()` | 判断是否应忽略解析错误 |\n\n资料来源：[src/config/imports/external.ts:40-62]()\n\n## 生命周期管理\n\n### 生命周期模式\n\nmcporter 支持两种服务端生命周期模式：\n\n```mermaid\ngraph TD\n    A[MCP 服务器定义] --> B{生命周期模式}\n    B -->|keep-alive| C[持续运行]\n    B -->|ephemeral| D[按需启动]\n    C --> E[idleTimeoutMs 配置]\n    D --> F[调用后终止]\n```\n\n资料来源：[src/lifecycle.ts:45-50]()\n\n生命周期序列化函数 `serializeLifecycle` 处理以下返回值格式：\n\n```typescript\n// 三种序列化形式\n'keep-alive'                                    // 无超时\n{ mode: 'keep-alive', idleTimeoutMs?: number }  // 带超时\n'ephemeral'                                     // 临时模式\n```\n\n资料来源：[src/cli/adhoc-server.ts:89-97]()\n\n### 动态端口检测\n\n对于 Chrome DevTools 相关的 MCP 服务器，mcporter 支持动态端口分配：\n\n```typescript\nconst CHROME_DEVTOOLS_URL_PLACEHOLDERS = [\n  '__MCP_PORT_3000__',\n  '__MCP_PORT_9222__',\n  // ...其他占位符\n];\n\nfunction commandRequiresDynamicChromePort(command: CommandSpec): boolean {\n  if (command.kind !== 'stdio') {\n    return false;\n  }\n  const tokens = [command.command, ...command.args];\n  return tokens.some((token) => \n    CHROME_DEVTOOLS_URL_PLACEHOLDERS.some(\n      (placeholder) => token.includes(placeholder)\n    )\n  );\n}\n```\n\n资料来源：[src/lifecycle.ts:19-33]()\n\n### Keep-Alive 命令识别\n\nmcporter 内置了对常见持续运行命令的识别：\n\n```typescript\nconst KEEP_ALIVE_COMMANDS = [\n  { label: 'docker', fragments: ['docker'] },\n  { label: 'npx', fragments: ['npx', 'npm exec'] },\n  // ...更多命令模式\n];\n\nfunction commandRequiresKeepAlive(command: CommandSpec): string | undefined {\n  if (command.kind !== 'stdio') {\n    return undefined;\n  }\n  const tokens = [command.command, ...command.args].map(\n    (token) => token.toLowerCase()\n  );\n  const match = KEEP_ALIVE_COMMANDS.find((signature) =>\n    signature.fragments.some((fragment) =>\n      tokens.some((token) => token.includes(fragment))\n    )\n  );\n  return match?.label;\n}\n```\n\n资料来源：[src/lifecycle.ts:6-18]()\n\n### 覆盖集合解析\n\n配置中的覆盖设置使用集合匹配机制：\n\n```typescript\nfunction parseList(value: string | undefined): OverrideSet {\n  if (!value) {\n    return { all: false, names: new Set() };\n  }\n  const names = value\n    .split(',')\n    .map((token) => token.trim().toLowerCase())\n    .filter((token) => token.length > 0);\n  \n  if (names.includes('*')) {\n    return { all: true, names: new Set() };\n  }\n  return { all: false, names: new Set(names) };\n}\n\nfunction matchesOverride(names: Set<string>, candidates: Set<string>): boolean {\n  for (const candidate of candidates) {\n    if (names.has(candidate)) {\n      return true;\n    }\n  }\n  return false;\n}\n```\n\n资料来源：[src/lifecycle.ts:35-62]()\n\n## CLI 命令系统\n\n### 命令路由\n\nCLI 入口点 `src/cli.ts` 负责将命令行参数路由到相应的处理函数：\n\n```mermaid\ngraph TD\n    A[CLI 入口] --> B[命令解析]\n    B --> C{命令类型}\n    C -->|list| D[list-command.ts]\n    C -->|call| E[call-command.ts]\n    C -->|config| F[config 子系统]\n    C -->|generate-cli| G[CLI 生成]\n    C -->|emit-ts| H[类型导出]\n    C -->|inspect-cli| I[CLI 检查]\n```\n\n### 工具选择器解析\n\n`list-command.ts` 实现了智能工具选择器解析，支持 `server.tool` 格式的直接调用：\n\n```typescript\nfunction resolveConfiguredToolSelector(\n  runtime: Runtime,\n  target: string | undefined\n): { server: string; tool: string } | undefined {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  const definitions = runtime.getDefinitions();\n  const match = definitions\n    .map((definition) => definition.name)\n    .filter((name) => target.startsWith(`${name}.`))\n    .toSorted((a, b) => b.length - a.length)[0];\n  \n  if (!match) {\n    return undefined;\n  }\n  const tool = target.slice(match.length + 1);\n  if (!tool) {\n    return undefined;\n  }\n  return { server: match, tool };\n}\n```\n\n资料来源：[src/cli/list-command.ts:90-109]()\n\n### 服务器定义解析\n\n解析流程如下：\n\n1. 检查目标是否为配置的 `server.tool` 格式\n2. 尝试从运行时获取服务器定义\n3. 解析超时配置\n4. 格式化传输层摘要\n\n```typescript\nconst resolved = resolveServerDefinition(runtime, target);\nif (!resolved) {\n  return;\n}\ntarget = resolved.name;\nconst definition = resolved.definition;\nconst timeoutMs = flags.timeoutMs ?? LIST_TIMEOUT_MS;\n```\n\n资料来源：[src/cli/list-command.ts:40-50]()\n\n## 列表输出系统\n\n### 状态分类\n\nmcporter 使用标准化的状态分类系统：\n\n```typescript\ntype StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';\n\nexport function createEmptyStatusCounts(): Record<StatusCategory, number> {\n  return {\n    ok: 0,\n    auth: 0,\n    offline: 0,\n    http: 0,\n    error: 0,\n  };\n}\n```\n\n资料来源：[src/cli/list-output.ts:42-50]()\n\n### 列表格式化\n\n列表格式化模块负责生成用户友好的输出：\n\n```typescript\nexport function truncateForSpinner(text: string, maxLength = 72): string {\n  if (text.length <= maxLength) {\n    return text;\n  }\n  return `${text.slice(0, Math.max(0, maxLength - 1))}…`;\n}\n```\n\n资料来源：[src/cli/list-format.ts:29-34]()\n\n### 工具元数据过滤\n\n支持按工具名称过滤返回的元数据：\n\n```typescript\nfunction filterToolMetadata(\n  entries: ToolMetadata[], \n  requestedTool: string | undefined\n): ToolMetadata[] {\n  if (!requestedTool) {\n    return entries;\n  }\n  return entries.filter((entry) => entry.tool.name === requestedTool);\n}\n```\n\n资料来源：[src/cli/list-command.ts:111-117]()\n\n## 结果处理系统\n\n### 内容类型提取\n\n`result-utils.ts` 实现了复杂的内容解析逻辑：\n\n```mermaid\ngraph TD\n    A[CallResult] --> B{内容类型判断}\n    B -->|text| C[textEntries]\n    B -->|markdown| D[markdownEntries + textEntries]\n    B -->|image| E[images]\n    B -->|resource| F[资源处理]\n    B -->|JSON| G[jsonCandidates]\n```\n\n### 资源负载收集\n\n```typescript\nfunction collectResourcePayload(\n  resource: unknown,\n  textEntries: string[],\n  markdownEntries: string[],\n  jsonCandidates: unknown[]\n): void {\n  if (!resource || typeof resource !== 'object') {\n    return;\n  }\n  const record = resource as Record<string, unknown>;\n  const mimeType = typeof record.mimeType === 'string' \n    ? record.mimeType \n    : '';\n  \n  if (typeof record.text === 'string') {\n    textEntries.push(record.text);\n    if (mimeType.toLowerCase().includes('markdown')) {\n      markdownEntries.push(record.text);\n    }\n    const parsed = tryParseJson(record.text);\n    if (parsed !== null) {\n      jsonCandidates.push(parsed);\n    }\n  } else if (typeof record.blob === 'string') {\n    textEntries.push(`[Binary resource: ${uri}]`);\n  }\n}\n```\n\n资料来源：[src/result-utils.ts:77-101]()\n\n### JSON 信封展开\n\n支持从标准信封格式中提取 JSON 数据：\n\n```typescript\nfunction unwrapJsonEnvelope(\n  record: Record<string, unknown>, \n  fallback: unknown\n): unknown {\n  if ('json' in record) {\n    return record.json ?? null;\n  }\n  if ('data' in record) {\n    return Object.keys(record).length === 1 \n      ? (record.data ?? null) \n      : fallback;\n  }\n  return null;\n}\n```\n\n资料来源：[src/result-utils.ts:111-121]()\n\n## 临时服务器管理\n\n### Ad-hoc 服务器解析\n\nmcporter 支持通过命令行直接定义临时 MCP 服务器：\n\n```mermaid\ngraph TD\n    A[--stdio 命令字符串] --> B[引号解析]\n    B --> C[命令+参数分离]\n    C --> D[生命周期决定]\n    D --> E[序列化配置]\n    E --> F[运行时注册]\n```\n\n### 命令字符串解析\n\n实现了完整的 shell 风格引号解析：\n\n```typescript\nfunction parseStdioCommand(input: string): string[] {\n  const result: string[] = [];\n  let current = '';\n  let inSingle = false;\n  let inDouble = false;\n  \n  for (let i = 0; i < input.length; i += 1) {\n    const char = input[i];\n    \n    if (char === '\\\\' && !inSingle) {\n      // 转义处理\n      continue;\n    }\n    \n    if (char === \"'\" && !inDouble) {\n      inSingle = !inSingle;\n      continue;\n    }\n    if (char === '\"' && !inSingle) {\n      inDouble = !inDouble;\n      continue;\n    }\n    // ...\n  }\n  \n  return result;\n}\n```\n\n资料来源：[src/cli/adhoc-server.ts:40-75]()\n\n## 环境变量控制\n\nmcporter 通过环境变量支持运行时行为控制：\n\n| 环境变量 | 作用 | 默认值 |\n|----------|------|--------|\n| `MCPORTER_LOG_LEVEL` | 日志级别 | info |\n| `MCPORTER_OAUTH_TIMEOUT_MS` | OAuth 超时 | 60000 |\n| `MCPORTER_DISABLE_KEEPALIVE` | 禁用 keep-alive | - |\n| `MCPORTER_NO_KEEPALIVE` | 同上（兼容） | - |\n\n```typescript\nfunction isFastPathKeepAliveDisabled(server: string): boolean {\n  const raw = process.env.MCPORTER_DISABLE_KEEPALIVE \n    ?? process.env.MCPORTER_NO_KEEPALIVE;\n  \n  if (!raw) {\n    return false;\n  }\n  \n  const disabled = new Set(\n    raw\n      .split(',')\n      .map((entry) => entry.trim().toLowerCase())\n      .filter(Boolean)\n  );\n  \n  return disabled.has('*') || disabled.has(server.toLowerCase());\n}\n```\n\n资料来源：[src/cli.ts:89-104]()\n\n## 数据流图\n\n### 列表命令完整数据流\n\n```mermaid\nsequenceDiagram\n    participant CLI as CLI 入口\n    participant Parse as 参数解析\n    participant Runtime as 运行时\n    participant Server as MCP 服务器\n    participant Format as 格式化输出\n    \n    CLI->>Parse: mcporter list [server]\n    Parse->>Runtime: 获取服务器定义\n    Runtime->>Server: 建立连接\n    Server-->>Runtime: 工具元数据\n    Runtime-->>Format: ListSummaryResult\n    Format->>Format: 状态分类\n    Format->>Format: 格式化输出\n    Format-->>CLI: 控制台输出\n```\n\n### 结果处理流程\n\n```mermaid\ngraph LR\n    A[Tool Call Response] --> B[类型检测]\n    B -->|文本| C[收集文本]\n    B -->|图片| D[收集图片]\n    B -->|资源| E[收集资源]\n    B -->|JSON| F[JSON 候选]\n    C --> G[合并输出]\n    D --> G\n    E --> G\n    F --> G\n    G --> H[CallResult]\n```\n\n## 错误处理策略\n\nmcporter 实现了多层次的错误处理机制：\n\n1. **超时处理**：通过 `withTimeout` 包装异步操作\n2. **认证错误分类**：区分 auth/offline/http/error 状态\n3. **解析容错**：对可忽略的解析错误进行特殊处理\n4. **类型安全转换**：使用 `asString()` 等工具函数避免类型错误\n\n```typescript\nfunction shouldIgnoreParseError(error: unknown): boolean {\n  if (error instanceof SyntaxError) {\n    return true;\n  }\n  if (!error || typeof error !== 'object') {\n    return false;\n  }\n  return 'fromTOML' in error;\n}\n```\n\n资料来源：[src/config/imports/external.ts:64-71]()\n\n## 扩展性设计\n\nmcporter 的架构设计支持多种扩展方式：\n\n1. **新命令添加**：在 `src/cli.ts` 中注册新命令处理器\n2. **配置格式扩展**：在 `src/config/imports/` 下添加新的导入器\n3. **输出格式扩展**：在 `src/cli/` 下添加新的格式化器\n4. **生命周期模式**：在 `src/lifecycle.ts` 中定义新的生命周期处理\n\n---\n\n<a id='page-runtime-system'></a>\n\n## 运行时系统\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [传输层](#page-transport-layer), [工具调用语法](#page-call-syntax)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/runtime.ts](https://github.com/steipete/mcporter/blob/main/src/runtime.ts)\n- [src/runtime/utils.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/utils.ts)\n- [src/runtime/errors.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/errors.ts)\n- [src/server-proxy.ts](https://github.com/steipete/mcporter/blob/main/src/server-proxy.ts)\n- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)\n</details>\n\n# 运行时系统\n\n## 概述\n\nmcporter 的**运行时系统**是整个工具调用框架的核心子系统，负责 MCP 服务器的创建、管理、工具调用及生命周期控制。该系统封装了与 MCP 服务器的通信细节，提供统一的运行时抽象，使 CLI 命令能够以一致的方式与不同类型的 MCP 服务器交互。\n\n运行时系统的主要职责包括：\n\n- **服务器运行时创建与管理**：通过 `createRuntime` 工厂函数实例化服务器运行时\n- **工具元数据加载**：获取 MCP 服务器提供的工具列表及参数模式\n- **工具调用执行**：将工具调用请求路由到目标服务器并处理响应\n- **生命周期管理**：支持 keep-alive 和 ephemeral 两种运行模式\n- **结果解析与格式化**：从服务器响应中提取文本、图像、JSON 等内容\n\n资料来源：[src/cli/list-command.ts:18-30]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n    subgraph \"运行时系统核心\"\n        RT[运行时实例]\n        SP[服务器代理 ServerProxy]\n        LC[生命周期管理器]\n        EU[结果工具]\n    end\n    \n    subgraph \"外部接口\"\n        CLI[CLI 命令层]\n        API[导出 API]\n    end\n    \n    subgraph \"服务器定义\"\n        DEF[ServerDefinition]\n        META[ToolMetadata]\n    end\n    \n    CLI --> RT\n    API --> RT\n    RT --> SP\n    RT --> LC\n    SP --> DEF\n    RT --> EU\n    EU --> META\n```\n\n### 运行时创建流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as CLI 命令\n    participant RT as createRuntime\n    participant SP as ServerProxy\n    participant DEF as ServerDefinition\n    participant LC as Lifecycle\n    \n    CLI->>RT: 创建运行时请求\n    RT->>DEF: 解析服务器定义\n    DEF-->>RT: 定义配置\n    RT->>LC: 初始化生命周期\n    LC-->>RT: 生命周期状态\n    RT->>SP: 创建服务器代理\n    SP-->>RT: 代理实例\n    RT-->>CLI: 运行时句柄\n```\n\n资料来源：[src/runtime.ts]()\n\n## 核心数据类型\n\n### ServerDefinition\n\n服务器定义是运行时系统的核心配置单元，描述单个 MCP 服务器的连接参数：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 服务器唯一标识名称 |\n| `command` | `CommandSpec` | 启动命令配置（stdio/http/sse） |\n| `description` | `string?` | 服务器描述文本 |\n| `source` | `ServerSource` | 配置来源（本地/导入/HTTP） |\n| `sources` | `readonly ServerSource[]?` | 多源配置 |\n| `lifecycle` | `ServerLifecycle?` | 生命周期模式 |\n| `auth` | `AuthConfig?` | 认证配置 |\n\n资料来源：[src/server-proxy.ts]()\n\n### ToolMetadata\n\n工具元数据描述 MCP 服务器暴露的单个工具：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | `string` | 工具名称 |\n| `description` | `string` | 工具功能描述 |\n| `inputSchema` | `JsonSchema` | 输入参数 JSON Schema |\n| `outputSchema` | `JsonSchema?` | 输出结果 JSON Schema |\n\n```typescript\ninterface ToolMetadata {\n  tool: { name: string; description: string };\n  inputSchema: JsonSchema;\n  outputSchema?: JsonSchema;\n}\n```\n\n资料来源：[src/cli/list-command.ts:31-36]()\n\n## 生命周期管理\n\n### 生命周期模式\n\n运行时系统支持两种服务器生命周期模式：\n\n```typescript\ntype ServerLifecycle =\n  | { mode: 'keep-alive'; idleTimeoutMs?: number }\n  | { mode: 'ephemeral' };\n```\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `keep-alive` | 服务器启动后保持运行，可复用连接 | 高频调用、资源充足环境 |\n| `ephemeral` | 每次工具调用后终止服务器 | 低频调用、资源受限环境 |\n\n### keep-alive 命令识别\n\n系统通过签名片段匹配识别需要保持连接的服务器命令：\n\n```typescript\nconst KEEP_ALIVE_COMMANDS = [\n  { label: 'docker', fragments: ['docker', 'run'] },\n  { label: 'npx', fragments: ['npx'] },\n  { label: 'bun', fragments: ['bun', 'x'] },\n  // 更多命令...\n];\n```\n\n当命令包含匹配的签名片段时，系统自动应用 keep-alive 生命周期。\n\n资料来源：[src/lifecycle.ts]()\n\n## 结果解析系统\n\n### ResultUtils 工具模块\n\n`result-utils.ts` 提供的工具函数负责从 MCP 服务器响应中提取结构化数据：\n\n```typescript\nexport interface ExtractedContent {\n  content: unknown;\n  structuredContent: unknown;\n  textEntries: string[];\n  markdownEntries: string[];\n  jsonCandidates: unknown[];\n  images: ImageContent[] | null;\n}\n```\n\n### 内容提取流程\n\n```mermaid\nflowchart TD\n    A[MCP 响应 envelope] --> B{遍历 content 数组}\n    B -->|image 类型| C[提取图像数据]\n    B -->|resource 类型| D[收集资源载荷]\n    B -->|text/markdown| E[文本处理]\n    B -->|其他类型| F[跳过]\n    \n    C --> G[合并图像列表]\n    D --> H[解析 text/blob]\n    E --> I[文本条目收集]\n    \n    H --> J[JSON 解析尝试]\n    I --> J\n    \n    G --> K[返回 ExtractedContent]\n    J --> K\n    K --> K\n```\n\n### 支持的内容类型\n\n| 内容类型 | 处理逻辑 |\n|----------|----------|\n| `text` | 直接添加到 `textEntries` |\n| `markdown` | 添加到 `textEntries` 和 `markdownEntries` |\n| `image` | 提取 data 和 mimeType，添加到 `images` |\n| `resource` | 递归解析 uri、mimeType、text、blob 字段 |\n| 其他 | 跳过处理 |\n\n资料来源：[src/result-utils.ts:1-80]()\n\n## 错误处理机制\n\n### 错误分类系统\n\n运行时系统包含完善的错误分类机制，为不同类型的连接问题提供诊断建议：\n\n```mermaid\nflowchart TD\n    A[错误发生] --> B{错误类型判定}\n    B -->|认证失败| C[auth 错误类别]\n    B -->|网络不可达| D[offline 错误类别]\n    B -->|HTTP 错误| E[http 错误类别]\n    B -->|其他| F[error 错误类别]\n    \n    C --> G[生成 authCommand 提示]\n    D --> H[提供连接检查建议]\n    E --> I[显示 HTTP 状态码]\n    F --> J[通用错误信息]\n```\n\n### 状态类别定义\n\n```typescript\ntype StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';\n```\n\n| 状态 | 含义 | 颜色标识 |\n|------|------|----------|\n| `ok` | 连接成功，工具正常 | 绿色 |\n| `auth` | 认证失败或缺失 | 黄色 |\n| `offline` | 服务器不可达 | 红色 |\n| `http` | HTTP 协议层错误 | 红色 |\n| `error` | 通用运行时错误 | 红色 |\n\n资料来源：[src/runtime/errors.ts](), [src/cli/list-format.ts:25-40]()\n\n## 工具调用流程\n\n### 标准工具调用序列\n\n```mermaid\nsequenceDiagram\n    participant User as 用户/CLI\n    participant RT as Runtime\n    participant SP as ServerProxy\n    participant Server as MCP Server\n    participant Utils as ResultUtils\n    \n    User->>RT: callTool(name, args)\n    RT->>SP: 路由到目标服务器\n    SP->>Server: 发送 JSON-RPC 请求\n    Server-->>SP: 工具响应\n    SP-->>RT: 响应 envelope\n    RT->>Utils: extractContent(envelope)\n    Utils-->>RT: ExtractedContent\n    RT-->>User: 格式化结果\n```\n\n### 工具选择器解析\n\n系统支持 `server.tool` 格式的工具选择器，简化跨服务器工具调用：\n\n```typescript\nfunction resolveConfiguredToolSelector(\n  runtime: Runtime,\n  target: string | undefined\n): { server: string; tool: string } | undefined {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  // 匹配 server.tool 格式\n  const match = definitions\n    .filter((name) => target.startsWith(`${name}.`))\n    .sort((a, b) => b.length - a.length)[0];\n  \n  if (!match) return undefined;\n  const tool = target.slice(match.length + 1);\n  return { server: match, tool };\n}\n```\n\n此函数自动从 `server.tool` 格式中提取服务器名称和工具名称。\n\n资料来源：[src/cli/list-command.ts:45-60]()\n\n## 配置与超时控制\n\n### 超时配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `LIST_TIMEOUT_MS` | 30000ms | 工具列表加载超时 |\n| `MCPORTER_OAUTH_TIMEOUT_MS` | 环境变量控制 | OAuth 流程超时 |\n\n### 运行时超时处理\n\n```typescript\nconst metadataEntries = await withTimeout(\n  loadToolMetadata(runtime, target, {\n    includeSchema: true,\n    autoAuthorize: false,\n    allowCachedAuth: true,\n  }),\n  timeoutMs\n);\n```\n\n工具元数据加载使用 `withTimeout` 包装，确保操作不会无限阻塞。\n\n资料来源：[src/cli/list-command.ts:85-95]()\n\n## 调试支持\n\n### 运行时调试模式\n\n`src/cli/runtime-debug.ts` 提供了详细的进程清理逻辑，用于调试挂起问题：\n\n```typescript\n// 强制销毁 Socket 句柄\nif (ctor === 'Socket' && typeof handle.destroy === 'function') {\n  handle.destroy?.();\n  handle.unref?.();\n}\n\n// 清理子进程 stdio\ncandidate.stdout?.destroy?.();\ncandidate.stderr?.destroy?.();\ncandidate.stdin?.end?.();\n\n// 可选强制 SIGKILL\nif (DEBUG_HANG) {\n  candidate.kill?.('SIGKILL');\n}\n```\n\n当启用 `DEBUG_HANG` 环境变量时，系统会记录详细的进程终止信息。\n\n资料来源：[src/cli/runtime-debug.ts]()\n\n## 导出 API\n\n运行时系统通过以下入口导出公共接口：\n\n```typescript\n// 主入口\nexport { createRuntime } from './runtime.js';\n\n// 工具函数\nexport { \n  loadToolMetadata,\n  callTool,\n  getDefinitions \n} from './runtime.js';\n\n// 结果处理\nexport { \n  extractContent,\n  extractText,\n  extractStructuredContent \n} from './result-utils.js';\n\n// 错误类型\nexport { \n  McpError,\n  ConnectionError,\n  TimeoutError \n} from './runtime/errors.js';\n```\n\n资料来源：[src/runtime.ts](), [src/result-utils.ts]()\n\n## 最佳实践\n\n### 1. 选择合适的生命周期模式\n\n```typescript\n// 高频调用场景 - 使用 keep-alive\nconst server = {\n  name: 'frequently-used',\n  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },\n  lifecycle: { mode: 'keep-alive', idleTimeoutMs: 60000 }\n};\n\n// 低频调用场景 - 使用 ephemeral\nconst server = {\n  name: 'rarely-used',\n  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },\n  lifecycle: { mode: 'ephemeral' }\n};\n```\n\n### 2. 配置合理的超时时间\n\n```bash\n# 启动时指定超时\nmcporter list --timeout-ms 60000\n\n# 或通过环境变量\nexport MCPORTER_OAUTH_TIMEOUT_MS=120000\n```\n\n### 3. 利用工具选择器\n\n```bash\n# 正确使用 server.tool 格式\nmcporter call context7.getComponents --prompt \"React button\"\n\n# 不需要显式指定服务器\nmcporter list linear.listProjects\n```\n\n## 总结\n\nmcporter 的运行时系统通过抽象 MCP 服务器的连接细节，提供了一个统一、可靠的工具调用平台。其核心设计包括：\n\n1. **声明式配置**：通过 `ServerDefinition` 描述服务器连接参数\n2. **生命周期管理**：支持 keep-alive 和 ephemeral 两种模式平衡资源与性能\n3. **结构化结果处理**：完善的响应解析支持多种内容类型\n4. **完善的错误诊断**：分类错误并提供可操作的修复建议\n5. **调试支持**：内置进程清理和挂起检测机制\n\n这些设计使得 mcporter 能够可靠地与各种 MCP 服务器交互，同时保持良好的开发体验。\n\n---\n\n<a id='page-transport-layer'></a>\n\n## 传输层\n\n### 相关页面\n\n相关主题：[运行时系统](#page-runtime-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/runtime/transport.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/transport.ts)\n- [src/cli/transport-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/transport-utils.ts)\n- [src/cli/http-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/http-utils.ts)\n- [src/runtime/node-http-fetch.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/node-http-fetch.ts)\n- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)\n- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)\n</details>\n\n# 传输层\n\n## 概述\n\n传输层是 mcporter 架构中连接 MCP 服务器与客户端的核心组件，负责处理不同通信协议之间的数据传输与协议协商。mcporter 支持多种传输方式，包括 HTTP、SSE（Server-Sent Events）和 stdio（标准输入输出），每种传输方式都有其特定的适用场景和配置要求。\n\n传输层的主要职责包括：\n\n- 建立与 MCP 服务器的连接\n- 处理请求与响应的序列化/反序列化\n- 管理传输生命周期（持久连接 vs 临时连接）\n- 处理认证和授权流程\n- 提供传输层面的错误处理与重试机制\n\n资料来源：[src/runtime/transport.ts:1-50]()\n\n## 支持的传输类型\n\nmcporter 支持三种主要的传输协议，开发者可通过 `--transport` 参数显式指定，或由系统自动检测：\n\n| 传输类型 | 标识符 | 说明 | 适用场景 |\n|---------|--------|------|---------|\n| HTTP | `http` | 基于 RESTful 风格的请求/响应模式 | 远程服务器、无状态服务 |\n| SSE | `sse` | Server-Sent Events，支持服务端推送 | 需要实时更新的场景 |\n| stdio | `stdio` | 标准输入输出流 | 本地进程、子进程通信 |\n\n资料来源：[src/cli/config/help.ts:3]()\n\n## HTTP 传输\n\n### 基本原理\n\nHTTP 传输是 mcporter 用于连接远程 MCP 服务器的主要方式。客户端通过 HTTP POST 请求发送工具调用请求，服务器返回 JSON 格式的响应。\n\n```mermaid\ngraph LR\n    A[mcporter 客户端] -->|POST /call-tool| B[HTTP MCP 服务器]\n    B -->|200 OK + JSON| A\n    A -->|GET /tools| B\n    B -->|200 OK + JSON Schema| A\n```\n\n### URL 处理\n\nHTTP 传输层支持完整的 URL 解析，包括：\n\n- 标准 HTTPS URL\n- 自定义端口指定\n- 路径前缀处理\n\n资料来源：[src/cli/http-utils.ts:1-30]()\n\n### 请求配置\n\nHTTP 传输支持多种请求头配置，用于认证和自定义元数据传递：\n\n```typescript\ninterface HttpTransportConfig {\n  url: string;\n  headers?: Record<string, string>;\n  timeout?: number;\n}\n```\n\n资料来源：[src/runtime/node-http-fetch.ts:1-40]()\n\n## SSE 传输\n\n### 基本原理\n\nSSE（Server-Sent Events）传输允许服务器主动向客户端推送消息，这在需要实时通知或长连接操作的场景中特别有用。\n\n```mermaid\ngraph TB\n    A[mcporter 客户端] -->|建立 SSE 连接| B[MCP 服务器]\n    B -->|事件流| A\n    A -->|POST 请求| B\n    B -->|响应| A\n```\n\nSSE 传输层会自动处理连接重连和心跳机制，确保连接的可靠性。\n\n资料来源：[src/runtime/transport.ts:100-150]()\n\n## stdio 传输\n\n### 基本原理\n\nstdio 传输通过标准输入输出与本地 MCP 服务器进程通信。这种方式适用于：\n\n- 本地安装的 MCP 服务器\n- 需要在同一进程中运行的服务\n- 调试和开发环境\n\n### 命令解析\n\nstdio 传输支持复杂的命令行解析，包括引号处理和参数转义：\n\n```mermaid\ngraph TD\n    A[原始命令字符串] --> B[字符逐个解析]\n    B --> C{检测引号状态}\n    C -->|\"单引号 ''\"| D[单引号模式]\n    C -->|\"双引号 \\\"\\\"\"| E[双引号模式]\n    C -->|普通字符| F[追加到当前 token]\n    D --> G{遇到单引号?}\n    E --> H{遇到双引号?}\n    G -->|是| I[结束引号模式]\n    G -->|否| D\n    H -->|是| J[结束引号模式]\n    H -->|否| E\n    I --> F\n    J --> F\n    F --> K{结束?}\n    K -->|否| B\n    K -->|是| L[返回 token 数组]\n```\n\n资料来源：[src/cli/adhoc-server.ts:50-100]()\n\n### 特殊命令识别\n\nstdio 传输包含对特定命令的自动识别机制：\n\n| 命令类型 | 标识 | 行为 |\n|---------|------|------|\n| Chrome DevTools | `chrome-devtools` 相关占位符 | 自动分配动态端口 |\n| 持久化命令 | 配置中的 keep-alive 列表 | 保持连接复用 |\n\n资料来源：[src/lifecycle.ts:30-80]()\n\n## 传输生命周期管理\n\n### 生命周期模式\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 标识 | 说明 |\n|------|------|------|\n| 持久化 | `keep-alive` | 服务器进程持续运行，支持连接复用 |\n| 临时 | `ephemeral` | 每次请求后终止服务器进程 |\n\n### 持久化配置\n\n```typescript\ninterface LifecycleConfig {\n  mode: 'keep-alive' | 'ephemeral';\n  idleTimeoutMs?: number;  // 可选的空闲超时配置\n}\n```\n\n资料来源：[src/lifecycle.ts:100-150]()\n\n### 生命周期序列化\n\n```mermaid\ngraph TD\n    A[生命周期配置] --> B{mode 检测}\n    B -->|keep-alive + 无超时| C[返回字符串 'keep-alive']\n    B -->|keep-alive + 有超时| D[返回对象 {mode, idleTimeoutMs}]\n    B -->|ephemeral| E[返回字符串 'ephemeral']\n    C --> F[序列化完成]\n    D --> F\n    E --> F\n```\n\n资料来源：[src/cli/adhoc-server.ts:120-140]()\n\n## 传输层工具函数\n\n### 传输摘要格式化\n\n`formatTransportSummary` 函数用于生成人类可读的传输信息摘要：\n\n```typescript\nfunction formatTransportSummary(\n  server: ServerDefinition,\n  options?: { verbose?: boolean }\n): string\n```\n\n返回值示例：\n\n- HTTP 传输：`https://api.example.com/mcp`\n- stdio 传输：`stdio /usr/local/bin/mcp-server`\n\n资料来源：[src/cli/transport-utils.ts:1-50]()\n\n### 传输类型检测\n\n传输层提供自动检测机制，根据服务器配置推断最合适的传输类型：\n\n```typescript\nfunction inferTransportType(config: ServerConfig): TransportType\n```\n\n检测优先级：\n\n1. 显式指定的 `--transport` 参数\n2. URL 格式（`http://`/`https://` → HTTP/SSE）\n3. 命令行配置（存在 `command` 字段 → stdio）\n4. 默认fallback\n\n资料来源：[src/runtime/transport.ts:50-100]()\n\n## HTTP 请求处理\n\n### Node.js 环境适配\n\nmcporter 在 Node.js 环境中使用原生 `fetch` API，并通过 `node-http-fetch.ts` 模块提供额外配置能力：\n\n```typescript\n// 超时配置示例\nconst response = await fetch(url, {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    ...customHeaders\n  },\n  body: JSON.stringify(payload),\n  signal: AbortSignal.timeout(timeoutMs)\n});\n```\n\n资料来源：[src/runtime/node-http-fetch.ts:40-80]()\n\n### 错误处理\n\nHTTP 传输层的错误分类：\n\n| 错误类型 | 状态码范围 | 处理策略 |\n|---------|-----------|---------|\n| 认证错误 | 401, 403 | 提示用户执行 `mcporter auth login` |\n| 网络错误 | - | 自动重试或返回离线状态 |\n| 服务器错误 | 5xx | 记录日志，返回错误状态 |\n| 超时 | - | 根据配置的超时时间终止请求 |\n\n资料来源：[src/cli/http-utils.ts:50-100]()\n\n## 进程清理与资源管理\n\n### 标准清理流程\n\n对于 stdio 传输，mcporter 在连接关闭时执行以下清理：\n\n```mermaid\ngraph TD\n    A[检测连接关闭信号] --> B[销毁 stdout 流]\n    B --> C[销毁 stderr 流]\n    C --> D[关闭 stdin 管道]\n    D --> E{DEBUG_HANG 启用?}\n    E -->|是| F[发送 SIGKILL]\n    E -->|否| G[正常退出]\n    F --> H[记录调试信息]\n```\n\n资料来源：[src/cli/runtime-debug.ts:20-60]()\n\n### 锁文件恢复\n\n传输层包含锁文件管理机制，用于处理异常进程退出：\n\n```typescript\nasync function removeRecoverableLock(lockPath: string): Promise<boolean>\n```\n\n恢复条件：\n\n- 锁文件持有进程已不存在\n- 锁文件创建时间超过阈值\n- breaker 文件存在且满足恢复条件\n\n资料来源：[src/fs-json.ts:60-100]()\n\n## 配置参考\n\n### 传输相关配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `transport` | `http` \\| `sse` \\| `stdio` | 自动检测 | 强制使用指定传输类型 |\n| `baseUrl` | string | - | HTTP 服务器基础 URL |\n| `command` | string | - | stdio 模式下的可执行命令 |\n| `args` | string[] | `[]` | 命令行参数 |\n| `env` | Record | `{}` | 环境变量 |\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--transport <http\\|sse\\|stdio>` | 指定传输类型 |\n| `--arg <value>` | 传递 stdio 额外参数（可重复） |\n| `--header KEY=value` | 添加 HTTP 请求头（可重复） |\n| `--env KEY=value` | 设置环境变量（可重复） |\n\n资料来源：[src/cli/config/help.ts:1-30]()\n\n## 最佳实践\n\n### 选择传输类型\n\n1. **远程 API 访问**：优先使用 HTTP 传输\n2. **需要实时推送**：选择 SSE 传输\n3. **本地工具集成**：使用 stdio 传输\n4. **混合场景**：在配置文件中为每个服务器单独指定\n\n### 性能优化\n\n- 对于频繁调用的服务器，启用 `keep-alive` 模式减少连接建立开销\n- HTTP 传输建议设置合理的超时时间（默认 60 秒）\n- stdio 传输注意进程清理，避免僵尸进程\n\n### 安全建议\n\n- 使用 HTTPS 替代 HTTP 传输敏感数据\n- 通过环境变量存储认证凭据，避免硬编码\n- 定期轮换 OAuth 客户端密钥\n\n## 相关文档\n\n- [配置管理](./config.md) - 传输层配置详解\n- [认证流程](./auth.md) - OAuth 和 API Key 认证\n- [工具调用](./tools.md) - 通过传输层执行工具调用\n- [CLI 生成](./cli-generation.md) - 生成独立 CLI 工具\n\n---\n\n<a id='page-cli-reference'></a>\n\n## CLI 命令参考\n\n### 相关页面\n\n相关主题：[工具调用语法](#page-call-syntax), [调用启发式与自动更正](#page-call-heuristic)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/cli-reference.md](https://github.com/steipete/mcporter/blob/main/docs/cli-reference.md)\n- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n- [src/cli/cli-factory.ts](https://github.com/steipete/mcporter/blob/main/src/cli/cli-factory.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/serve-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/serve-command.ts)\n- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)\n</details>\n\n# CLI 命令参考\n\n## 概述\n\nmcporter 提供了一套完整的命令行工具，用于管理、调用和调试 MCP（Model Context Protocol）服务器。该 CLI 是与 MCP 服务器交互的主要入口点，支持服务器发现、工具调用、配置管理以及代码生成等功能。\n\nCLI 工具的核心设计理念是统一处理不同类型的 MCP 服务器（HTTP、SSE、stdio），并提供一致的接口和输出格式。通过运行时抽象层，`mcporter` 能够自动发现已配置的服务器、处理 OAuth 认证、管理连接生命周期。资料来源：[README.md:1-50]()\n\n## 核心命令架构\n\nmcporter CLI 采用子命令架构，主要包含以下命令模块：\n\n```mermaid\ngraph TD\n    A[mcporter] --> B[list]\n    A --> C[call]\n    A --> D[config]\n    A --> E[generate-cli]\n    A --> F[emit-ts]\n    A --> G[inspect-cli]\n    \n    B --> B1[列出所有服务器]\n    C --> C1[调用指定工具]\n    D --> D1[增删改查配置]\n    E --> E1[生成独立CLI]\n    F --> F1[生成TypeScript类型]\n    G --> G1[检查CLI元数据]\n```\n\n## 全局选项\n\n所有 mcporter 命令支持以下全局选项：\n\n| 选项 | 说明 | 环境变量 |\n|------|------|----------|\n| `--config <path>` | 指定配置文件路径 | `MCPORTER_CONFIG` |\n| `--root <path>` | 设置工作目录 | - |\n| `--log-level <level>` | 设置日志级别（debug/info/warn/error） | `MCPORTER_LOG_LEVEL` |\n| `--oauth-timeout <ms>` | OAuth 超时时间 | `MCPORTER_OAUTH_TIMEOUT_MS` |\n| `--output <format>` | 控制输出格式 | - |\n\n资料来源：[src/cli/config/help.ts:1-30]()\n\n## mcporter list\n\n`list` 命令用于列出已配置的 MCP 服务器及其可用工具。\n\n### 基本用法\n\n```bash\nmcporter list [server]\nmcporter list --json\nmcporter list --signatures\n```\n\n### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `--json` | 以 JSON 格式输出结果 |\n| `--signatures` | 仅显示函数签名 |\n| `--brief` | 简化输出格式 |\n| `--all-parameters` | 显示所有参数（包括可选） |\n| `--required-only` | 仅显示必需参数 |\n| `--schema` | 显示 JSON Schema |\n\n资料来源：[src/cli/list-command.ts:1-50]()\n\n### 输出状态分类\n\n服务器状态分为以下几类：\n\n| 状态 | 含义 | 颜色标识 |\n|------|------|----------|\n| `ok` | 服务器正常，可调用工具 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 | 红色 |\n| `error` | 未知错误 | 红色 |\n\n资料来源：[src/cli/list-format.ts:40-80]()\n\n### 服务器信息格式化\n\n输出格式包括工具数量、响应耗时和来源信息：\n\n```typescript\n// 输出格式示例\n- context7 (5 tools, 1.2s) [npm:@context7/mcp]\n- firecrawl (3 tools, 0.8s) [local]\n```\n\n来源标签表示服务器的定义来源：\n- `[npm:xxx]` - npm 包\n- `[local]` - 本地配置\n- `[cursor]` - Cursor 导入\n- `[claude]` - Claude 导入\n\n资料来源：[src/cli/list-format.ts:80-120]()\n\n## mcporter call\n\n`call` 命令用于调用 MCP 服务器上的特定工具。\n\n### 基本用法\n\n```bash\nmcporter call <server>.<tool> [args...]\nmcporter call context7.resolve-library-id --query \"React hooks\"\n```\n\n### 选项说明\n\n| 选项 | 说明 |\n|------|------|\n| `--raw` | 保持原始输出格式 |\n| `--raw-strings` | 保持数字形式的字符串参数 |\n| `--no-coerce` | 禁用类型转换 |\n| `--save-images <dir>` | 保存图片内容到指定目录 |\n| `--tail-log` | 显示相关日志的最后 20 行 |\n\n### 参数传递规则\n\n`call` 命令支持多种参数格式：\n\n```bash\n# 关键字参数\nmcporter call server.tool --key value\n\n# 位置参数\nmcporter call server.tool arg1 arg2\n\n# 混合使用\nmcporter call server.tool --key value arg1\n```\n\n类型自动转换规则：\n- `true`/`false` → 布尔值\n- `null` → null\n- 数字形式字符串 → 数字\n- JSON 对象 → 对象\n\n资料来源：[README.md:50-100]()\n\n## mcporter config\n\n`config` 命令用于管理 mcporter.json 配置文件。\n\n### 子命令\n\n| 子命令 | 说明 |\n|--------|------|\n| `config list` | 列出本地配置 |\n| `config get <name>` | 获取指定配置项 |\n| `config add <name>` | 添加新配置 |\n| `config remove <name>` | 删除配置项 |\n| `config import <kind>` | 导入外部配置 |\n\n资料来源：[README.md:120-150]()\n\n### 配置示例\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n配置文件支持 JSONC 格式，允许内联注释和尾随逗号。资料来源：[README.md:140-180]()\n\n## mcporter generate-cli\n\n生成独立的可分享 CLI 工件，将 MCP 服务器转换为独立的命令行工具。\n\n### 基本用法\n\n```bash\nmcporter generate-cli --command https://mcp.context7.com/mcp\nmcporter generate-cli \"npx -y chrome-devtools-mcp@latest\"\nmcporter generate-cli linear --bundle dist/linear.js\n```\n\n### 生成选项\n\n| 选项 | 说明 |\n|------|------|\n| `--name <name>` | 覆盖推断的 CLI 名称 |\n| `--description <text>` | 设置帮助文本摘要 |\n| `--command <spec>` | MCP 服务器命令或 URL |\n| `--server <name>` | 从配置中选择服务器 |\n| `--bundle <path>` | 输出捆绑包路径 |\n| `--dry-run` | 预览生成结果 |\n| `--from <cli>` | 从现有 CLI 重新生成 |\n\n资料来源：[README.md:30-60]()\n\n### 工件元数据\n\n生成的 CLI 嵌入以下元数据：\n\n```bash\nnpx mcporter inspect-cli dist/context7.js     # 查看元数据摘要\nnpx mcporter generate-cli --from dist/context7.js  # 使用元数据重新生成\n```\n\n## mcporter emit-ts\n\n生成强类型的 TypeScript 客户端代码，无需完整的 CLI 即可使用 MCP 工具。\n\n### 基本用法\n\n```bash\n# 仅生成类型定义\nmcporter emit-ts linear --out types/linear-tools.d.ts\n\n# 生成客户端包装器\nmcporter emit-ts linear --mode client --out clients/linear.ts\n```\n\n### 输出模式\n\n| 模式 | 说明 | 输出文件 |\n|------|------|----------|\n| `types` | 仅接口定义 | `.d.ts` |\n| `client` | 接口 + 代理工厂 | `.d.ts` + `.ts` |\n\n### 附加选项\n\n| 选项 | 说明 |\n|------|------|\n| `--include-optional` | 展开所有可选字段 |\n| `--json` | 输出结构化摘要 |\n| `--server <name>` | 选择服务器（支持 URL） |\n\n生成的客户端模式与 `createRuntime()` API 保持同步。资料来源：[README.md:70-100]()\n\n## mcporter inspect-cli\n\n检查已生成 CLI 工件的元数据和签名信息。\n\n### 基本用法\n\n```bash\nmcporter inspect-cli dist/context7.js\n```\n\n## 服务器生命周期管理\n\nmcporter 支持两种服务器生命周期模式：\n\n| 模式 | 说明 | 配置值 |\n|------|------|--------|\n| `keep-alive` | 持续运行，复用连接 | `\"keep-alive\"` |\n| `ephemeral` | 每次调用后关闭 | `\"ephemeral\"` |\n\n### 生命周期配置\n\n```json\n{\n  \"lifecycle\": {\n    \"mode\": \"keep-alive\",\n    \"idleTimeoutMs\": 300000\n  }\n}\n```\n\n自动保活检测：mcporter 会识别特定的命令签名（如某些 chrome-devtools 命令），自动应用 `keep-alive` 策略。资料来源：[src/lifecycle.ts:1-50]()\n\n## 输出格式化\n\n### 文本模式\n\n默认使用人类可读的格式化输出：\n\n```\n✓ context7 (5 tools, 1.2s)\n  - resolve-library-id(query, libraryName)\n  - get-library-docs(libraryId, ...)\n```\n\n### JSON 模式\n\n使用 `--json` 选项获取机器可读输出：\n\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"context7\",\n      \"status\": \"ok\",\n      \"durationMs\": 1200,\n      \"tools\": [...]\n    }\n  ]\n}\n```\n\n资料来源：[src/cli/list-output.ts:1-80]()\n\n## OAuth 认证\n\nmcporter 自动处理 MCP 服务器的 OAuth 认证流程。\n\n### OAuth 配置选项\n\n| 选项 | 说明 |\n|------|------|\n| `--oauth-client-id <id>` | 使用预注册的客户端 ID |\n| `--oauth-client-secret-env <var>` | 从环境变量读取密钥 |\n| `--oauth-token-endpoint-auth-method <method>` | 设置令牌认证方式 |\n| `--oauth-redirect-url <url>` | 自定义重定向 URL |\n| `--token-cache-dir <path>` | OAuth 令牌缓存目录 |\n\n### 认证流程\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CLI as mcporter\n    participant Server as MCP Server\n    participant Browser\n    \n    User->>CLI: call <server>.<tool>\n    CLI->>Server: 发现需要 OAuth\n    Server->>Browser: 重定向到授权页面\n    Browser->>User: 显示授权页面\n    User->>Browser: 确认授权\n    Browser->>Server: 授权码\n    Server->>CLI: 颁发访问令牌\n    CLI->>Server: 调用工具\n```\n\n认证超时默认 5 分钟，可通过 `--oauth-timeout` 调整。资料来源：[src/cli/config/help.ts:1-40]()\n\n## 错误处理与调试\n\n### 常见错误状态\n\n| 状态码 | 含义 | 解决方案 |\n|--------|------|----------|\n| `auth` | 认证失败 | 运行 `mcporter config login <server>` |\n| `offline` | 服务器不可达 | 检查网络连接和服务器地址 |\n| `http` | HTTP 请求错误 | 检查服务器日志 |\n| `error` | 未知错误 | 使用 `--log-level debug` 调试 |\n\n### 调试模式\n\n```bash\nmcporter list --log-level debug\nDEBUG_HANG=1 mcporter call server tool\n```\n\n启用 `DEBUG_HANG` 后，mcporter 会在强制终止进程前留下调试标记，便于诊断连接问题。资料来源：[src/cli/runtime-debug.ts:1-50]()\n\n## 高级用法\n\n### 临时服务器（Ad-hoc）\n\n通过 `--command` 直接运行未配置的服务器：\n\n```bash\nmcporter list --command \"npx -y some-mcp-server\"\n```\n\n支持完整的命令参数传递和生命周期管理。资料来源：[src/cli/adhoc-server.ts:1-50]()\n\n### 工具选择器\n\n使用点号分隔符精确指定服务器和工具：\n\n```bash\nmcporter list context7.resolve-library-id\n```\n\n自动补全和纠错功能支持模糊匹配服务器名称。资料来源：[src/cli/list-command.ts:50-100]()\n\n## 最佳实践\n\n1. **配置管理**：优先使用 `mcporter config` 管理配置，避免直接编辑 JSON 文件\n2. **类型安全**：使用 `emit-ts` 生成 TypeScript 类型，集成到开发工作流\n3. **认证处理**：生产环境使用环境变量存储敏感信息，配合 `--oauth-client-secret-env`\n4. **调试技巧**：使用 `--tail-log` 查看工具调用的关联日志\n5. **性能优化**：高频调用场景选择 `keep-alive` 生命周期模式\n\n---\n\n*本文档最后更新于 2024 年 11 月，基于 mcporter 最新版本。*\n\n---\n\n<a id='page-call-syntax'></a>\n\n## 工具调用语法\n\n### 相关页面\n\n相关主题：[调用启发式与自动更正](#page-call-heuristic), [CLI 命令参考](#page-cli-reference)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/call-syntax.md](https://github.com/steipete/mcporter/blob/main/docs/call-syntax.md)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n- [src/cli/call-argument-expression.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-argument-expression.ts)\n- [src/cli/call-expression-parser.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-expression-parser.ts)\n- [src/cli/command-inference.ts](https://github.com/steipete/mcporter/blob/main/src/cli/command-inference.ts)\n</details>\n\n# 工具调用语法\n\n## 概述\n\nmcporter 的工具调用语法（Tool Calling Syntax）是连接用户命令行与 MCP（Model Context Protocol）服务器工具之间的核心桥接层。该系统负责解析用户输入的参数表达式，将其转换为符合工具 schema 的结构化参数，并最终传递给运行时执行调用。\n\n工具调用语法的主要职责包括：\n\n- **参数解析**：支持命名参数、位置参数、混合使用等多种调用方式\n- **类型强制转换**：自动将字符串形式的参数值转换为 schema 定义的正确类型\n- **工具发现**：根据服务器名称和工具名称定位目标工具\n- **参数验证**：验证参数是否符合工具定义的输入 schema\n\n资料来源：[src/cli/call-command.ts:1-50]()\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    A[用户输入] --> B[call-command.ts]\n    B --> C{参数类型判定}\n    C -->|命名参数| D[直接使用命名参数]\n    C -->|位置参数| E[call-expression-parser.ts]\n    C -->|字符串候选| F[类型强制转换]\n    C -->|数组候选| G[数组参数处理]\n    E --> H[loadToolMetadata]\n    H --> I[获取 Schema 信息]\n    I --> J[参数映射]\n    J --> K[参数验证]\n    K --> L[runtime.callTool]\n    F --> L\n    G --> L\n```\n\n### 主要模块说明\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| call-command | `src/cli/call-command.ts` | 命令入口、参数解析协调、调用执行 |\n| call-expression-parser | `src/cli/call-expression-parser.ts` | 解析位置参数表达式 |\n| call-argument-expression | `src/cli/call-argument-expression.ts` | 处理参数表达式求值 |\n| command-inference | `src/cli/command-inference.ts` | 服务器和工具名称推断 |\n| list-command | `src/cli/list-command.ts` | 工具元数据查询 |\n\n资料来源：[src/cli/call-command.ts:50-100]()\n\n## 调用方式\n\nmcporter 支持多种工具调用方式，以适应不同用户习惯和场景需求。\n\n### 1. 命名参数方式\n\n最直接的调用方式，用户显式指定每个参数的名称和值：\n\n```bash\nmcporter call <server>.<tool> --key1=value1 --key2=value2\n```\n\n示例：\n\n```bash\nmcporter call linear.create-issue --title=\"Bug Report\" --team_id=team123\n```\n\n### 2. 位置参数方式\n\n用户按照工具 schema 定义的参数顺序提供值，系统自动将位置参数映射到对应的字段：\n\n```bash\nmcporter call <server>.<tool> <arg1> <arg2> <arg3>\n```\n\n位置参数映射遵循以下规则：\n\n- 仅填充**未通过命名参数设置的字段**\n- 严格校验位置参数数量不超过剩余可填充字段数\n- 必须按照 schema 中 required 参数在前、optional 参数在后的顺序提供\n\n资料来源：[src/cli/call-command.ts:150-200]()\n\n```typescript\nconst remaining = options.filter((option) => !(option.property in namedArgs));\nif (positionalArgs.length > remaining.length) {\n  throw new Error(\n    `Too many positional arguments (${positionalArgs.length}) supplied; only ${remaining.length} parameter${remaining.length === 1 ? '' : 's'} remain on ${tool}.`\n  );\n}\n```\n\n### 3. 混合使用方式\n\n命名参数和位置参数可以混合使用，命名参数具有更高的优先级：\n\n```bash\nmcporter call <server>.<tool> <arg1> --key2=value2 <arg3>\n```\n\n### 4. 选择器语法（Selector Syntax）\n\n使用点号分隔符直接指定服务器和工具：\n\n```bash\nmcporter call <server>.<tool>\n```\n\n系统会从 `<server>.<tool>` 中提取服务器名称和工具名称，支持自动补全和建议功能。\n\n资料来源：[src/cli.ts:80-120]()\n\n## 参数类型强制转换\n\nmcporter 内置了智能的类型强制转换系统，能够自动将命令行输入的字符串值转换为工具 schema 定义的正确类型。\n\n### 支持的转换类型\n\n| 目标类型 | 转换规则 | 示例 |\n|----------|----------|------|\n| string | 保持原值 | `--name=value` → `\"value\"` |\n| number | 解析数值字符串 | `--count=42` → `42` |\n| boolean | 识别真值/假值 | `--verbose=true` → `true` |\n| null | 识别 null 字符串 | `--value=null` → `null` |\n| array | 逗号分隔或 JSON 数组 | `--ids=a,b,c` → `[\"a\",\"b\",\"c\"]` |\n| object | JSON 对象字符串 | `--config='{\"a\":1}'` → `{a:1}` |\n\n### 强制转换流程\n\n```mermaid\ngraph LR\n    A[原始输入] --> B{类型检测}\n    B -->|key=value| C[stringCandidate]\n    B -->|key:value| D[stringCandidate]\n    B -->|尾部位置参数| E[stringCandidate]\n    C --> F[loadToolMetadata]\n    D --> F\n    E --> F\n    F --> G[获取 Schema]\n    G --> H{字段类型匹配}\n    H -->|number| I[parseFloat]\n    H -->|boolean| J[布尔解析]\n    H -->|null| K[空值处理]\n    H -->|array| L[数组处理]\n    I --> M[最终参数]\n    J --> M\n    K --> M\n    L --> M\n```\n\n### 强制转换函数\n\n参数强制转换的核心逻辑位于 `enforceSchemaAwareArgumentTypes` 函数中：\n\n资料来源：[src/cli/call-command.ts:200-250]()\n\n```typescript\nasync function enforceSchemaAwareArgumentTypes(\n  runtime,\n  server,\n  tool,\n  args,\n  stringCandidates,\n  arrayCandidates,\n  timeoutMs\n): Promise<Record<string, unknown>> {\n  // 1. 获取工具 schema\n  const tools = await withTimeout(loadToolMetadata(runtime, server, { includeSchema: true }), timeoutMs);\n  const toolInfo = tools.find((entry) => entry.tool.name === tool);\n  const schema = toolInfo?.tool.inputSchema as { properties?: Record<string, unknown> } | undefined;\n  \n  // 2. 遍历候选参数进行类型转换\n  for (const [key, rawValue] of Object.entries(stringCandidates ?? {})) {\n    if (typeof args[key] !== 'number') {\n      continue; // 跳过已经是正确类型的参数\n    }\n    // 根据 schema 类型进行转换\n  }\n}\n```\n\n### 布尔值识别规则\n\nmcporter 识别以下字符串为真值（case-insensitive）：\n\n- `true`、`yes`、`1`、`on`\n\n识别以下字符串为假值（case-insensitive）：\n\n- `false`、`no`、`0`、`off`\n\n## 位置参数解析详解\n\n### Schema 顺序保证\n\n位置参数到命名参数的映射依赖于 schema 中定义的参数顺序。系统通过 `loadToolMetadata` 获取工具列表时，会同时返回符合 TypeScript 风格的签名顺序，确保 required 参数优先于 optional 参数。\n\n资料来源：[src/cli/call-command.ts:100-150]()\n\n### 解析步骤\n\n1. **加载工具元数据**：获取完整 schema 和参数选项列表\n2. **计算剩余字段**：排除已通过命名参数设置的字段\n3. **校验参数数量**：确保位置参数不超过剩余字段数\n4. **按顺序映射**：将位置参数依次赋给剩余字段\n\n```typescript\nconst tools = await loadToolMetadata(runtime, server, { includeSchema: true }).catch(() => undefined);\nconst toolInfo = tools.find((entry) => entry.tool.name === tool);\nconst options = toolInfo.options;\nconst remaining = options.filter((option) => !(option.property in namedArgs));\n```\n\n## 工具选择器解析\n\n### 服务器和工具名称推断\n\n系统支持通过多种方式指定目标服务器和工具：\n\n```mermaid\ngraph TD\n    A[用户输入] --> B{包含点号?}\n    B -->|是| C[解析 selector]\n    B -->|否| D[检查 --server 参数]\n    C --> E[提取服务器名]\n    C --> F[提取工具名]\n    D --> G{有 --server?|H}\n    H -->|是| I[使用 --server 值]\n    H -->|否| J[报错缺失服务器]\n    E --> K[定位服务器]\n    F --> L[定位工具]\n    I --> K\n    K --> M[执行调用]\n    L --> M\n```\n\n### 选择器解析规则\n\n资料来源：[src/cli.ts:60-80]()\n\n1. **点号分隔符**：`<server>.<tool>` 格式直接解析\n2. **服务器标志**：`--server <name>` 或 `--server=<name>`\n3. **工具标志**：`--tool <name>` 或 `--tool=<name>`\n4. **URL 识别**：包含 `://` 的输入视为 HTTP 服务器定义\n\n```typescript\nconst separator = token.indexOf('.');\nif (separator > 0) {\n  return token.slice(0, separator); // 返回服务器名\n}\n```\n\n### 自动补全建议\n\n当用户输入的服务器或工具名称不存在时，系统会使用 `chooseClosestIdentifier` 函数提供最接近的候选建议：\n\n```typescript\nfunction resolveConfiguredToolSelector(runtime, target: string | undefined) {\n  if (!target || !target.includes('.')) {\n    return undefined;\n  }\n  const definitions = runtime.getDefinitions();\n  const match = definitions\n    .map((definition) => definition.name)\n    .filter((name) => target.startsWith(`${name}.`))\n    .toSorted((a, b) => b.length - a.length)[0]; // 最长匹配优先\n}\n```\n\n## 错误处理与诊断\n\n### 常见错误类型\n\n| 错误场景 | 错误信息 | 解决方案 |\n|----------|----------|----------|\n| 工具不存在 | `Tool 'xxx' not found on 'yyy'` | 检查工具名称是否正确 |\n| 参数过多 | `Too many positional arguments` | 减少位置参数或使用命名参数 |\n| 参数缺失 | `Missing required parameter` | 检查 required 字段 |\n| 类型不匹配 | `Cannot convert 'xxx' to number` | 检查参数格式 |\n| Schema 不可用 | `Unable to load tool metadata` | 检查服务器连接 |\n\n### 参数类型错误处理\n\n当类型强制转换失败时，系统会保留原始字符串值并输出警告，而非直接报错。这允许某些工具接受灵活格式的输入。\n\n资料来源：[src/cli/call-command.ts:250-300]()\n\n### 超时处理\n\n所有涉及网络请求的操作都支持超时控制：\n\n```typescript\nconst tools = await withTimeout(\n  loadToolMetadata(runtime, server, { includeSchema: true }), \n  timeoutMs\n).catch(() => undefined);\n```\n\n## 调用流程完整图\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant CLI as mcporter CLI\n    participant Parser as 参数解析器\n    participant Runtime as 运行时\n    participant Server as MCP 服务器\n    \n    User->>CLI: mcporter call server.tool --arg=value\n    CLI->>Parser: 解析参数表达式\n    Parser->>Parser: 分离命名/位置参数\n    Parser->>CLI: 返回解析结果\n    CLI->>Runtime: 创建运行时实例\n    Runtime->>Server: 连接 MCP 服务器\n    Server-->>Runtime: 返回工具列表\n    CLI->>Parser: 获取 schema 信息\n    Parser-->>CLI: 返回参数映射\n    CLI->>CLI: 类型强制转换\n    CLI->>Runtime: callTool(name, args)\n    Runtime->>Server: 发送工具调用请求\n    Server-->>Runtime: 返回调用结果\n    Runtime-->>CLI: 返回 CallResult\n    CLI->>CLI: 格式化输出结果\n    CLI-->>User: 显示结果\n```\n\n## 高级用法\n\n### Raw Strings 模式\n\n使用 `--raw-strings` 标志可以禁用所有自动类型转换，保持参数值为原始字符串形式：\n\n```bash\nmcporter call server.tool --raw-strings --count=42 --enabled=true\n```\n\n此模式下，所有值都将作为字符串传递，不会进行数值或布尔值转换。\n\n### 禁用 Coerce 模式\n\n`--no-coerce` 标志完全禁用类型强制，包括 `key=value`、`key:value` 和尾部位置参数的所有转换：\n\n```bash\nmcporter call server.tool --no-coerce --id=12345 --data='{\"json\":\"value\"}'\n```\n\n### 双破折号分隔符\n\n使用 `--` 可以停止标志解析，使后续参数保持字面形式：\n\n```bash\nmcporter call server.tool -- --some-value --another-value\n```\n\n## 命令行参数速查表\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--server <name>` | 指定服务器名称 | `--server linear` |\n| `--tool <name>` | 指定工具名称 | `--tool create-issue` |\n| `--timeout <ms>` | 设置调用超时 | `--timeout 60000` |\n| `--raw-strings` | 禁用类型转换 | `--raw-strings` |\n| `--no-coerce` | 禁用所有强制转换 | `--no-coerce` |\n| `--output <format>` | 指定输出格式 | `--output json` |\n\n## 相关文档\n\n- [配置文件参考](docs/config.md) - mcporter.json 配置语法\n- [emit-ts 命令](docs/emit-ts.md) - 生成 TypeScript 类型定义\n- [generate-cli 命令](docs/generate-cli.md) - 生成独立 CLI 工具\n\n---\n\n<a id='page-call-heuristic'></a>\n\n## 调用启发式与自动更正\n\n### 相关页面\n\n相关主题：[工具调用语法](#page-call-syntax), [CLI 命令参考](#page-cli-reference)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/call-heuristic.md](https://github.com/steipete/mcporter/blob/main/docs/call-heuristic.md)\n- [src/cli/identifier-helpers.ts](https://github.com/steipete/mcporter/blob/main/src/cli/identifier-helpers.ts)\n- [src/cli/server-lookup.ts](https://github.com/steipete/mcporter/blob/main/src/cli/server-lookup.ts)\n- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)\n- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)\n</details>\n\n# 调用启发式与自动更正\n\nmcporter 的调用启发式与自动更正系统为 MCP 服务器和工具的调用提供了智能容错机制。该系统通过模糊匹配、选择建议和上下文感知解析，显著提升了命令行交互的用户体验，减少了因拼写错误或格式偏差导致的命令失败。\n\n## 核心概念\n\nmcporter 在处理服务器名称、工具选择器和命令参数时，采用了多层次的启发式策略。这些策略协同工作，形成了从输入解析到错误恢复的完整链路。\n\n### 模糊匹配算法\n\n当用户输入的服务器名称与配置中的实际名称不完全匹配时，mcporter 使用基于字符串相似度的算法进行自动更正。该算法不仅考虑精确匹配，还评估字符串之间的距离和公共子序列。资料来源：[src/cli/identifier-helpers.ts]()\n\n```typescript\n// 伪代码示例：chooseClosestIdentifier 的匹配逻辑\nfunction chooseClosestIdentifier(attempted: string, candidates: string[]): string | undefined {\n  // 计算编辑距离并选择最接近的候选者\n  // 优先处理前缀匹配，然后考虑编辑距离\n}\n```\n\n### 选择器解析规则\n\nmcporter 支持 `server.tool` 格式的工具选择器，通过分层解析策略确保准确识别目标服务器和工具。解析器首先尝试完整匹配，然后降级为服务器名称前缀匹配，最后进行模糊校正。资料来源：[src/cli/list-command.ts:35-52]()\n\n## 系统架构\n\n```\ngraph TD\n    A[用户输入命令] --> B[输入标准化]\n    B --> C{选择器格式检测}\n    C -->|包含 \".\"| D[server.tool 解析]\n    C -->|纯文本| E[服务器名称解析]\n    D --> F{精确匹配?}\n    E --> G{精确匹配?}\n    F -->|否| H[前缀匹配扫描]\n    G -->|否| I[模糊匹配搜索]\n    H --> J{唯一匹配?}\n    I --> K[返回最佳候选]\n    J -->|是| K\n    J -->|否| L[输出歧义提示]\n    K --> M[执行命令]\n    L --> N[显示建议列表]\n```\n\n## 核心组件\n\n### 1. 服务器定义解析器\n\n服务器定义解析器负责将用户提供的目标字符串映射到配置中的实际服务器定义。该组件支持多种输入格式，包括纯服务器名称、带选择器的复合名称、以及 HTTP URL。资料来源：[src/cli/list-command.ts:35-52]()\n\n| 输入类型 | 处理策略 | 示例 |\n|---------|---------|------|\n| 精确名称 | 直接映射 | `mcporter list context7` |\n| 带点分隔符 | 提取 server 和 tool | `mcporter call linear.listProjects` |\n| 前缀模糊 | 扫描配置匹配 | `sshadcn` → `shadcn` |\n| URL 格式 | 协议解析 | `https://mcp.context7.com/mcp` |\n\n### 2. 工具元数据加载器\n\n工具元数据加载器负责获取指定服务器的工具列表，并在存在请求的工具时进行过滤。该组件通过 MCP 协议的 `tools/list` 方法获取服务器提供的所有工具及其输入模式。资料来源：[src/cli/list-command.ts:54-71]()\n\n```typescript\n// 工具元数据过滤逻辑\nfunction filterToolMetadata(entries: ToolMetadata[], requestedTool: string | undefined): ToolMetadata[] {\n  if (!requestedTool) {\n    return entries;\n  }\n  return entries.filter((entry) => entry.tool.name === requestedTool);\n}\n```\n\n### 3. 错误分类器\n\n错误分类器对 MCP 服务器连接失败的情况进行系统化分类，并为每种错误类型提供诊断建议和可能的修复命令。该分类器区分认证错误、网络错误、协议错误和超时情况。资料来源：[src/cli/list-format.ts:15-24]()\n\n```typescript\nconst timeoutSeconds = Math.round(timeoutMs / 1000);\nconst advice = classifyListError(result.error, result.server.name, timeoutSeconds);\nreturn {\n  line: `${prefix} (${advice.colored}, ${durationLabel})${sourceSuffix}`,\n  summary: advice.summary,\n  category: advice.category,\n  authCommand: advice.authCommand,\n  issue: advice.issue,\n};\n```\n\n## 调用流程详解\n\n### 标准调用路径\n\n1. **参数接收**：mcporter CLI 接收 `mcporter call <target>` 形式的命令\n2. **选择器解析**：检测是否包含 `.` 分隔符，提取服务器和工具名称\n3. **定义解析**：调用 `resolveServerDefinition` 获取服务器定义\n4. **元数据加载**：获取工具列表并验证请求的工具是否存在\n5. **参数准备**：处理命名参数和位置参数的混合输入\n6. **工具调用**：通过 MCP 运行时执行实际的工具调用\n\n资料来源：[src/cli/call-command.ts:1-50]()\n\n### 位置参数推断\n\n当用户使用位置参数而非命名参数时，mcporter 会动态查询工具的输入模式来确定参数顺序。这种设计允许用户使用 `mcporter call server tool arg1 arg2` 的简洁格式，而无需手动指定参数名称。资料来源：[src/cli/call-command.ts:18-48]()\n\n```typescript\n// 从工具模式推断位置参数映射\nconst tools = await loadToolMetadata(runtime, server, { includeSchema: true });\nconst toolInfo = tools.find((entry) => entry.tool.name === tool);\nconst remaining = options.filter((option) => !(option.property in namedArgs));\n\n// 验证位置参数数量不超限\nif (positionalArgs.length > remaining.length) {\n  throw new Error(`Too many positional arguments supplied...`);\n}\n```\n\n### 临时服务器管理\n\n对于通过命令行直接定义的临时服务器（adhoc server），mcporter 提供特殊的管理机制。临时服务器使用特殊的生命周期配置，并在命令执行完毕后自动清理。资料来源：[src/cli/adhoc-server.ts:50-62]()\n\n```typescript\nfunction serializeLifecycle(lifecycle: ReturnType<typeof resolveLifecycle>): string | { mode: 'keep-alive'; idleTimeoutMs?: number } | undefined {\n  if (!lifecycle) {\n    return undefined;\n  }\n  if (lifecycle.mode === 'keep-alive' && lifecycle.idleTimeoutMs === undefined) {\n    return 'keep-alive';\n  }\n  if (lifecycle.mode === 'keep-alive') {\n    return { mode: 'keep-alive', idleTimeoutMs: lifecycle.idleTimeoutMs };\n  }\n  return 'ephemeral';\n}\n```\n\n## 自动更正机制\n\n### 拼写校正示例\n\nmcporter 的模糊匹配功能能够智能处理常见的拼写错误：\n\n| 用户输入 | 实际配置 | 校正行为 |\n|---------|---------|---------|\n| `sshadcn` | `shadcn` | 自动更正 + 提示消息 |\n| `contextt7` | `context7` | 自动更正 |\n| `linearr` | `linear` | 自动更正 |\n\n校正发生时，mcporter 会在输出中显示暗淡处理的提示信息，告知用户进行了自动更正，同时执行用户的实际意图。资料来源：[src/cli/server-lookup.ts]()\n\n### 歧义检测与建议\n\n当用户输入存在多种可能的匹配时，mcporter 不会盲目选择一个，而是输出清晰的歧义提示：\n\n```\nmcporter: ambiguous server 'db'. Did you mean one of: [db-mysql, db-postgres, db-sqlite]?\n```\n\n这种设计确保用户始终了解系统的行为，避免因自动选择导致的意外后果。\n\n## 配置与使用\n\n### 启用自动更正\n\n自动更正在 mcporter 的 `list`、`call`、`config` 等主要命令中默认启用。用户可以通过配置或命令行参数调整匹配算法的敏感度。\n\n### 匹配范围控制\n\n| 命令 | 默认行为 | 可配置选项 |\n|------|---------|-----------|\n| `mcporter list` | 匹配服务器名称 | `--exact` 禁用模糊匹配 |\n| `mcporter call` | 匹配服务器和工具 | `--strict` 严格模式 |\n| `mcporter config` | 匹配配置键名 | 无需配置 |\n\n## 错误处理\n\n### 缺失工具的诊断\n\n当用户请求的工具在服务器上不存在时，mcporter 提供友好的错误消息，列出该服务器实际提供的工具列表。资料来源：[src/cli/list-command.ts:72-79]()\n\n```typescript\nfunction printMissingToolText(\n  definition: ServerDefinition,\n  tool: string,\n  durationMs: number,\n  transportSummary: string,\n  sourcePath: string | undefined\n): void {\n  printSingleServerHeader(definition, 0, durationMs, transportSummary, sourcePath);\n  console.warn(`  Tool '${tool}' not found on '${definition.name}'.`);\n}\n```\n\n### 超时与重试策略\n\n对于网络请求，mcporter 实现了可配置的超时机制。默认超时时间因服务器类型而异，HTTP 服务器通常使用较短的超时，而 stdio 服务器则使用更宽松的时间限制。资料来源：[src/cli/list-format.ts:12-14]()\n\n```typescript\nconst timeoutSeconds = Math.round(timeoutMs / 1000);\nconst timeoutLabel = `${timeoutSeconds}s`;\n```\n\n## 性能考量\n\n### 缓存策略\n\nmcporter 对服务器元数据和认证状态实施智能缓存，以减少重复连接的开销。缓存策略考虑以下因素：\n\n- 服务器的连接稳定性\n- 上次成功连接的时间戳\n- 配置文件的修改时间\n\n### 并行检查优化\n\n在批量检查多个服务器状态时，mcporter 使用并行连接策略，同时对多个服务器发起探测请求，显著减少总体检查时间。资料来源：[src/cli/list-command.ts:100-130]()\n\n## 扩展与定制\n\n### 自定义选择器解析器\n\n开发者可以通过实现 `resolveConfiguredToolSelector` 接口来扩展选择器的解析逻辑，支持自定义的命名约定和别名系统。资料来源：[src/cli/list-command.ts:35-52]()\n\n### 错误分类插件\n\n通过扩展 `classifyListError` 函数，可以添加针对特定 MCP 服务器的自定义错误处理和诊断建议。这种机制允许维护者提供针对特定服务（如 Docker、Kubernetes 等）的专业故障排除指导。\n\n## 相关文档\n\n- [配置管理文档](docs/config.md) - 了解服务器配置的编写方式\n- [emit-ts 文档](docs/emit-ts.md) - 生成类型化客户端工具\n- [Agent Skills 文档](docs/agent-skills.md) - 为 AI 代理编写技能定义\n\n---\n\n<a id='page-configuration'></a>\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)\n- [src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)\n- [src/config/path-discovery.ts](https://github.com/steipete/mcporter/blob/main/src/config/path-discovery.ts)\n- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n- [src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)\n- [src/cli/config/index.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/index.ts)\n</details>\n\n# 配置管理\n\nmcporter 的配置管理系统负责定义、加载和组织 MCP 服务器的连接信息。该系统支持多种配置源、灵活的命名匹配、跨编辑器的配置导入以及完整的 XDG 标准兼容。\n\n## 配置架构概述\n\nmcporter 采用分层配置架构，支持本地项目配置、全局用户配置和系统级配置的组合使用。\n\n```mermaid\ngraph TD\n    A[CLI 参数] --> B[环境变量<br/>MCPORTER_CONFIG]\n    B --> C[项目配置<br/>config/mcporter.json]\n    C --> D[XDG 配置<br/>$XDG_CONFIG_HOME/mcporter/mcporter.json]\n    D --> E[默认配置<br/>~/.mcporter/mcporter.json]\n    \n    F[MCP Servers 定义] --> C\n    G[导入配置<br/>Cursor/Claude/Windsurf] --> C\n    H[OAuth Vault 存储] -.-> D\n```\n\n配置加载按优先级从高到低依次为：\n\n1. **CLI 参数**：`--config <path>` 或 `--root <dir>`\n2. **环境变量**：`MCPORTER_CONFIG`\n3. **项目配置**：`<root>/config/mcporter.json`\n4. **XDG 配置**：`$XDG_CONFIG_HOME/mcporter/mcporter.json`\n5. **默认配置**：`~/.mcporter/mcporter.json`\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 配置文件格式\n\nmcporter 支持 JSONC 格式的配置文件，允许使用行内注释和尾随逗号。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"description\": \"Context7 docs MCP\",\n      \"baseUrl\": \"https://mcp.context7.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"$env:CONTEXT7_API_KEY\"\n      }\n    },\n    \"chrome-devtools\": {\n      // 内联注释\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chrome-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n### 服务器定义结构\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `command` | `string` | 条件 | stdio 传输时的启动命令 |\n| `args` | `string[]` | 否 | 命令行参数数组 |\n| `env` | `Record<string, string>` | 否 | 环境变量 |\n| `baseUrl` | `string` | 条件 | HTTP 传输时的服务器地址 |\n| `headers` | `Record<string, string>` | 否 | HTTP 请求头 |\n| `transport` | `http \\| sse \\| stdio` | 否 | 强制指定传输类型 |\n| `description` | `string` | 否 | 服务器描述文本 |\n| `allowedTools` | `string[]` | 否 | 允许的工具列表（白名单） |\n| `blockedTools` | `string[]` | 否 | 屏蔽的工具列表（黑名单） |\n| `lifecycle` | `keep-alive \\| ephemeral` | 否 | 服务器生命周期模式 |\n\n资料来源：[src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)\n\n## 路径发现机制\n\n配置路径发现遵循标准化的优先级规则，支持显式覆盖和 XDG 标准。\n\n```mermaid\ngraph LR\n    A[Config CLI] --> B{存在 --config?}\n    B -->|是| C[使用指定路径]\n    B -->|否| D{存在环境变量?}\n    D -->|MCPORTER_CONFIG| E[使用环境变量路径]\n    D -->|否| F{项目配置存在?}\n    F -->|是| G[config/mcporter.json]\n    F -->|否| H{XDG_CONFIG_HOME?}\n    H -->|是| I[$XDG_CONFIG_HOME/mcporter/mcporter.json]\n    H -->|否| J[~/.mcporter/mcporter.json]\n```\n\n路径发现逻辑实现于 `src/config/path-discovery.ts`，支持以下环境变量：\n\n| 环境变量 | 用途 | 默认值 |\n|----------|------|--------|\n| `MCPORTER_CONFIG` | 直接指定配置文件路径 | - |\n| `XDG_CONFIG_HOME` | XDG 配置根目录 | `~/.config` |\n| `XDG_DATA_HOME` | OAuth 令牌存储目录 | `~/.local/share` |\n| `XDG_CACHE_HOME` | Schema 缓存目录 | `~/.cache` |\n| `XDG_STATE_HOME` | 守护进程状态目录 | `~/.local/state` |\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 工具过滤配置\n\n服务器定义支持细粒度的工具访问控制，通过 `allowedTools` 和 `blockedTools` 实现白名单和黑名单机制。\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"slack-readonly\": {\n      \"baseUrl\": \"https://example.com/slack/mcp\",\n      \"allowedTools\": [\"channels_list\", \"conversations_history\"]\n    },\n    \"devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chrome-devtools-mcp\"],\n      \"blockedTools\": [\"screenshot_fullpage\", \"performance_metrics\"]\n    }\n  }\n}\n```\n\n过滤机制在列表查询和工具调用时均生效，确保只有授权的工具可被访问。\n\n资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)\n\n## 配置管理命令\n\n`mcporter config` 提供交互式配置管理功能，支持列表、查询、添加、删除和导入操作。\n\n### 子命令概览\n\n| 命令 | 功能 |\n|------|------|\n| `mcporter config list` | 列出当前配置的服务器 |\n| `mcporter config get <name>` | 获取指定服务器配置详情 |\n| `mcporter config add <name> <command>` | 添加新服务器配置 |\n| `mcporter config remove <name>` | 删除服务器配置 |\n| `mcporter config import <kind>` | 从编辑器导入配置 |\n| `mcporter config logout <name>` | 清除 OAuth 认证信息 |\n\n资料来源：[src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)\n\n### 添加服务器配置\n\n```bash\n# 基本 stdio 服务器\nmcporter config add myserver npx -y my-mcp-server\n\n# HTTP 服务器\nmcporter config add context7 https://mcp.context7.com/mcp\n\n# 带 OAuth 认证\nmcporter config add github --auth oauth --oauth-client-id $CLIENT_ID\n\n# 带环境变量\nmcporter config add api --env OPENAI_API_KEY=$OPENAI_API_KEY\n```\n\n支持的添加参数：\n\n| 参数 | 说明 |\n|------|------|\n| `--command <cmd>` | stdio 传输的启动命令 |\n| `--transport <http\\|sse\\|stdio>` | 强制指定传输类型 |\n| `--arg <value>` | 附加 stdio 参数（可重复） |\n| `--env KEY=value` | 环境变量（可重复） |\n| `--header KEY=value` | HTTP 请求头（可重复） |\n| `--auth <strategy>` | 强制认证类型 |\n| `--oauth-client-id <id>` | OAuth 客户端 ID |\n| `--oauth-client-secret-env <env>` | OAuth 密钥环境变量名 |\n| `--token-cache-dir <path>` | OAuth 令牌缓存目录 |\n| `--persist <path>` | 写入指定配置文件路径 |\n| `--scope <home\\|project>` | 配置文件作用域 |\n| `--copy-from <import:name>` | 从导入配置复制 |\n\n资料来源：[src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)\n\n## 配置导入系统\n\nmcporter 支持从主流编辑器的配置中导入 MCP 服务器定义，实现配置迁移。\n\n### 支持的导入源\n\n| 编辑器 | 导入标识 | 配置格式 |\n|--------|----------|----------|\n| Cursor | `cursor` | `cursor/mcp.json` |\n| Claude Code | `claude-code` | `.claude/mcp.json` |\n| Windsurf | `windsurf` | `windsurf/mcp.json` |\n| VS Code | `vscode` | `mcp.json` |\n\n```bash\n# 列出可导入的服务器\nmcporter config import cursor --list\n\n# 交互式导入\nmcporter config import cursor\n\n# 直接复制到本地配置\nmcporter config import cursor --copy\n```\n\n导入过程会处理多种配置格式，包括 `mcpServers`、`servers` 和 `mcp` 容器结构。\n\n资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n\n### 导入安全规则\n\n不同来源的导入有不同的安全限制：\n\n```typescript\n{\n  allowMcpServers: true,    // 标准 mcpServers 容器\n  allowServers: true,        // servers 容器\n  allowMcp: true,            // mcp 容器\n  allowRootFallback: boolean // 是否允许根目录回退\n}\n```\n\nClaude Code 配置有特殊处理，仅在 `.claude.json` 或 `.claude/mcp.json` 路径下允许根目录回退。\n\n资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)\n\n## 模糊匹配与自动纠正\n\nmcporter 在配置管理中内置了智能模糊匹配机制，支持输入纠错和歧义提示。\n\n```bash\n# 拼写错误自动纠正\nmcporter config get sshadcn\n# 输出: sshadcn → shadcn (已纠正)\n\n# 歧义时提示选择\nmcporter config get linear\n# 输出: \"Did you mean linear-api or linear-tools?\"\n```\n\n匹配逻辑实现于 `src/cli/list-command.ts`，使用最长前缀匹配策略：\n\n```typescript\nconst match = definitions\n  .map((definition) => definition.name)\n  .filter((name) => target.startsWith(`${name}.`))\n  .toSorted((a, b) => b.length - a.length)[0];\n```\n\n资料来源：[src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)\n\n## 配置输出格式化\n\n`mcporter list` 命令以表格形式展示配置，支持文本和 JSON 两种输出格式。\n\n### 状态分类\n\n| 状态 | 说明 | 颜色编码 |\n|------|------|----------|\n| `ok` | 服务器在线，工具可用 | 绿色 |\n| `auth` | 需要认证 | 黄色 |\n| `offline` | 服务器离线 | 灰色 |\n| `http` | HTTP 错误 |\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：steipete/mcporter\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)。\n\n## 1. 安全/权限坑 · 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor\n\n## 4. 配置坑 · 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：`daemonIdleTimeoutMs` missing?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`daemonIdleTimeoutMs` missing?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Add `mcporter vault set <server>` to seed credentials non-interactively\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add `mcporter vault set <server>` to seed credentials non-interactively\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b63d0f3f42e046488953064089bf8025 | https://github.com/openclaw/mcporter/issues/156 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d76f84533e8406d965b1762634996dd | https://github.com/openclaw/mcporter/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：MCPorter not using OAuth credentials\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCPorter not using OAuth credentials\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2705d784929e4996bcb34f3a71543ed7 | https://github.com/openclaw/mcporter/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78f73e8e0c9d4cca9e886fa2d89ef296 | https://github.com/openclaw/mcporter/issues/158 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocat…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocations\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9439129321d048dabb2ad6f14b4ab11e | https://github.com/openclaw/mcporter/issues/167 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Support refreshable bearer token auth for stdio MCP servers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support refreshable bearer token auth for stdio MCP servers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88f8026283fc46309d02fbb7f6a3186f | https://github.com/openclaw/mcporter/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1aff56feb584e23ac8b345ddc61934f | https://github.com/openclaw/mcporter/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：list reports auth required on expired access_token even when refresh_token is valid\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：list reports auth required on expired access_token even when refresh_token is valid\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcd9da058a8b48df94395fee1f995805 | https://github.com/openclaw/mcporter/issues/166 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | release_recency=unknown\n\n<!-- canonical_name: steipete/mcporter; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：steipete/mcporter\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)。\n\n## 1. 安全/权限坑 · 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor\n\n## 4. 配置坑 · 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：`daemonIdleTimeoutMs` missing?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`daemonIdleTimeoutMs` missing?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：why bothering with MCPs if I can call almost anything via CLI? - Reddit 26 Mar 2026 · yeah but again, WHY I need a tool like https://github.com/steipete/mcporter. ... mcp is worth it when the agent needs to pick which tool to call ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_2c950dd9704e4fd2afc80b980e214b96 | https://www.reddit.com/r/LocalLLaMA/comments/1s41ltp/please_explain_why_bothering_with_mcps_if_i_can/ | why bothering with MCPs if I can call almost anything via CLI? - Reddit\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Add `mcporter vault set <server>` to seed credentials non-interactively\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add `mcporter vault set <server>` to seed credentials non-interactively\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b63d0f3f42e046488953064089bf8025 | https://github.com/openclaw/mcporter/issues/156 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d76f84533e8406d965b1762634996dd | https://github.com/openclaw/mcporter/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：MCPorter not using OAuth credentials\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCPorter not using OAuth credentials\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2705d784929e4996bcb34f3a71543ed7 | https://github.com/openclaw/mcporter/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78f73e8e0c9d4cca9e886fa2d89ef296 | https://github.com/openclaw/mcporter/issues/158 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocat…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocations\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9439129321d048dabb2ad6f14b4ab11e | https://github.com/openclaw/mcporter/issues/167 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Support refreshable bearer token auth for stdio MCP servers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support refreshable bearer token auth for stdio MCP servers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88f8026283fc46309d02fbb7f6a3186f | https://github.com/openclaw/mcporter/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b1aff56feb584e23ac8b345ddc61934f | https://github.com/openclaw/mcporter/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：list reports auth required on expired access_token even when refresh_token is valid\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：list reports auth required on expired access_token even when refresh_token is valid\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dcd9da058a8b48df94395fee1f995805 | https://github.com/openclaw/mcporter/issues/166 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# mcporter - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcporter 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: MCPorter 🧳 - Call MCPs from TypeScript or as CLI 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation-guide：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：核心架构。围绕“核心架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-runtime-system：运行时系统。围绕“运行时系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation-guide\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“核心架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-runtime-system\n输入：用户提供的“运行时系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation-guide：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quick-start：Step 3 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“核心架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-runtime-system：Step 5 必须围绕“运行时系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/steipete/mcporter#readme\n- README.md\n- package.json\n- src/index.ts\n- docs/install.md\n- docs/windows.md\n- docs/quickstart.md\n- src/cli.ts\n- src/cli/call-command.ts\n- src/config.ts\n- src/config/read-config.ts\n- src/config-normalize.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcporter 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：steipete/mcporter\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx mcporter\n```\n\n来源：https://github.com/steipete/mcporter#readme\n\n## 来源\n\n- docs: https://github.com/steipete/mcporter#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_294a3b2a7aa64f6797760813f127ea78"
}