核心定位

mcporter 的设计目标是为 MCP 服务器提供统一的入口层：

• 配置管理：集中管理多个 MCP 服务器配置
• 工具调用：通过 CLI 直接调用 MCP 工具
• 类型生成：自动生成 TypeScript 类型定义和客户端代码
• 跨编辑器兼容：支持导入/导出 Cursor、Claude、VS Code 等编辑器的 MCP 配置

资料来源：README.md:1-15

核心命令

mcporter 提供了以下主要命令：

资料来源：README.md:60-85

系统架构

graph TD
    A[用户 CLI] --> B[mcporter 核心]
    B --> C{命令路由}
    C -->|config| D[配置管理模块]
    C -->|list| E[服务器列表模块]
    C -->|call| F[工具调用模块]
    C -->|generate-cli| G[代码生成模块]
    C -->|emit-ts| H[类型生成模块]
    D --> I[配置文件<br/>mcporter.json]
    D --> J[外部导入<br/>Cursor/Claude/VS Code]
    E --> K[运行时引擎]
    F --> K
    K --> L[MCP 协议栈]
    L --> M[HTTP 传输]
    L --> N[SSE 传输]
    L --> O[STDIO 传输]

配置系统

配置文件格式

mcporter 使用 config/mcporter.json 作为主配置文件，格式兼容 JSONC（支持注释和尾随逗号）：

{
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "$env:CONTEXT7_API_KEY"
      }
    }
  }
}

资料来源：README.md:30-50

配置导入功能

mcporter 支持从多种编辑器和工具导入 MCP 配置：

资料来源：README.md:35-40

配置导入时支持模糊匹配和自动纠错，例如输入 sshadcn 会自动纠正为 shadcn。

资料来源：README.md:45-47

运行时引擎

运行时引擎是 mcporter 的核心，负责与 MCP 服务器建立连接并执行调用：

sequenceDiagram
    用户 ->> CLI: mcporter call server.tool
    CLI ->> Runtime: createRuntime(config)
    Runtime ->> Definition: getDefinitions()
    Definition -->> Runtime: ServerDefinition[]
    Runtime ->> Transport: 建立连接
    Transport -->> Runtime: 连接就绪
    Runtime ->> MCP: callTool(name, args)
    MCP -->> Runtime: CallResult
    Runtime -->> CLI: 格式化输出
    CLI ->> 用户: 显示结果

资料来源：src/cli/list-command.ts:1-30

传输类型支持

资料来源：src/cli/config/help.ts:5-10

生命周期管理

mcporter 支持两种服务器生命周期模式：

graph LR
    A[生命周期] --> B[keep-alive]
    A --> C[ephemeral]
    B --> D{空闲超时}
    D -->|无超时| E[持续运行]
    D -->|设置超时| F[idleTimeoutMs]
    C --> G[调用后立即关闭]

资料来源：src/lifecycle.ts:25-40

工具调用与结果处理

调用语法

mcporter call <server>.<tool> [key=value ...] [--tool-arg <json>]

mcporter 支持多种参数格式：

• key=value 形式
• key:value 形式
• 尾随位置参数
• --tool-arg JSON 格式

资料来源：README.md:70-80

结果类型

调用结果包装在 CallResult 对象中，提供多种访问方式：

资料来源：README.md:110-120

资源收集逻辑

graph TD
    A[CallResult] --> B{内容类型}
    B -->|text| C[直接添加]
    B -->|markdown| D[添加并标记]
    B -->|image| E[收集 mimeType + data]
    B -->|resource| F{资源类型}
    F -->|text| G[解析 JSON 后添加]
    F -->|blob| H[输出为文本占位符]
    C --> I[textEntries]
    D --> I
    G --> I
    E --> J[images]
    H --> I

资料来源：src/result-utils.ts:15-55

代码生成功能

生成独立 CLI

npx mcporter generate-cli \
  --command https://mcp.context7.com/mcp

输出文件：

• context7.ts - TypeScript 模板
• context7.js - 打包后的可执行 CLI

生成的 CLI 嵌入元数据，支持通过 mcporter inspect-cli 查看信息或 mcporter generate-cli --from 重新生成。

资料来源：README.md:90-110

生成 TypeScript 类型

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

# 生成客户端包装器
npx mcporter emit-ts linear --mode client --out clients/linear.ts

资料来源：README.md:125-140

命令行选项参考

全局选项

资料来源：README.md:55-65

list 命令选项

资料来源：src/cli/list-command.ts:80-100

call 命令选项

资料来源：README.md:75-80

错误处理与诊断

状态分类

资料来源：src/cli/list-format.ts:10-25

诊断命令

# 查看服务器状态摘要
mcporter list --json

# 尾随相关日志
mcporter call <server>.<tool> --tail-log

技术栈

资料来源：README.md:100-105

总结

mcporter 作为一个 MCP 统一管理工具，提供了从配置管理到工具调用、再到代码生成的完整工具链。它的设计强调：

1. 统一性：多种 MCP 服务器的集中管理
2. 兼容性：支持多种编辑器和工具的配置导入
3. 开发者体验：模糊匹配、自动纠错、类型生成
4. 灵活性：多种传输协议和生命周期管理

通过 mcporter，开发者可以快速集成 MCP 服务器到自己的工作流程中，无需关心底层协议细节。

环境要求

运行时依赖

系统要求

• macOS、Linux 或 Windows（通过 WSL 或 Git Bash）
• 网络连接（用于访问远程 MCP 服务器）
• OAuth 认证需要浏览器环境

安装方式

通过 pnpm 安装（推荐）

将 mcporter 添加为项目依赖：

pnpm add mcporter

这种方式适合在项目内部使用 mcporter API，或者通过 pnpm exec mcporter 调用。资料来源：README.md

通过 npm 全局安装

npm install -g mcporter

安装后可在任意目录直接使用 mcporter 命令。资料来源：README.md

通过 Homebrew 安装（macOS/Linux）

brew tap steipete/tap
brew install steipete/tap/mcporter

提示：Homebrew tap 与 npm 同步发布。如果遇到问题，运行 brew update 后重新安装。资料来源：README.md

配置管理

配置文件位置

mcporter 默认从以下位置读取配置（按优先级排序）：

1. ./config/mcporter.json（项目本地）
2. ./config/mcporter.jsonc（支持注释的配置）
3. ~/.mcporter/config.json（用户级别）

配置命令

资料来源：README.md

配置文件格式

mcporter 使用 JSONC 格式，支持注释和尾随逗号：

{
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "$env:CONTEXT7_API_KEY"
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-chrome-devtools"]
    }
  }
}

命令行用法

常用命令

全局选项

资料来源：README.md, src/cli/config/help.ts

编程接口

One-shot 调用

适合单次执行任务的场景：

import { callOnce } from 'mcporter';

const result = await callOnce({
  server: 'firecrawl',
  toolName: 'crawl',
  args: { url: 'https://anthropic.com' },
});

console.log(result);

callOnce 会自动发现服务器、处理 OAuth 认证并在完成后关闭传输。资料来源：README.md

运行时 API

适合需要多次调用或高级配置的场景：

import { createRuntime } from 'mcporter';

const runtime = await createRuntime();

const tools = await runtime.listTools('context7');
const result = await runtime.callTool('context7', 'resolve-library-id', {
  args: { query: 'React hooks docs', libraryName: 'react' },
});

await runtime.close();

生成类型化客户端

#### 仅生成类型定义

npx mcporter emit-ts linear --out types/linear-tools.d.ts

#### 生成客户端包装器

npx mcporter emit-ts linear --mode client --out clients/linear.ts

可用选项：

资料来源：README.md, docs/emit-ts.md

OAuth 认证配置

OAuth 选项

清除认证

mcporter config logout <server-name>

资料来源：README.md, src/cli/config/help.ts

生命周期管理

mcporter 支持两种服务器生命周期模式：

可通过配置文件或命令行设置：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-server"],
      "lifecycle": "keep-alive"
    }
  }
}

资料来源：src/lifecycle.ts

工具列表与调用

列出服务器工具

# 列出所有服务器的工具
mcporter list

# 列出单个服务器的详细工具信息
mcporter list context7

# 输出 JSON 格式
mcporter list --json

调用工具

# 基本调用
mcporter call context7.resolve-library-id --args query="React hooks"

# 使用参数文件
mcporter call server.tool --args-file params.json

# 保存图片输出
mcporter call server.tool --save-images ./output-dir

参数值默认会自动转换类型。使用 --raw-strings 可保持原始字符串格式，--no-coerce 可禁用所有类型转换。资料来源：README.md, src/cli/list-command.ts

故障排除

常见问题

1. 服务器连接超时

• 检查网络连接
• 使用 --log-level debug 查看详细日志
• 调整 --oauth-timeout 值

1. OAuth 认证失败

• 确认浏览器可以打开重定向 URL
• 检查 --oauth-redirect-url 配置
• 清除旧的认证：mcporter config logout <server>

1. 配置找不到

• 使用 --config <path> 指定配置文件
• 使用 mcporter config list 查看已加载的配置

日志调试

mcporter list --log-level debug --tail-log

--tail-log 选项会流式输出相关日志文件的最后 20 行。资料来源：README.md

安装与基础配置

安装方式

mcporter 支持多种包管理器安装方式，开发者可根据项目环境选择最适合的方案：

资料来源：README.md:1-15

配置文件位置

mcporter 默认使用 ./config/mcporter.json 作为配置文件，同时也支持 JSONC 格式，允许使用 // 和 /* ... */ 注释以及尾随逗号。

{
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "$env:CONTEXT7_API_KEY",
      }
    }
  }
}

资料来源：README.md:45-60

常用命令行参数

资料来源：README.md:20-35

列出可用服务器与工具

基础列表命令

使用 mcporter list 命令查看所有已配置的 MCP 服务器及其状态：

mcporter list

该命令会检查每个服务器的可访问性，并显示工具数量、连接耗时和状态信息。状态分类包括：

资料来源：src/cli/list-format.ts:1-30

查看特定服务器的工具

当您指定服务器名称时，mcporter 会显示该服务器的所有可用工具及其详细签名：

mcporter list <server>
mcporter list context7

工具详情包括：

• 工具名称：MCP 服务器暴露的函数名
• 输入模式（Input Schema）：参数定义，包含类型和约束
• 描述信息：工具功能说明
• 示例调用：常用参数组合示例

资料来源：src/cli/list-command.ts:1-50

过滤工具输出

# 简要输出
mcporter list context7 --brief

# 显示所有参数
mcporter list context7 --all-parameters

# 指定特定工具
mcporter list context7.shadcn_getComponents

资料来源：src/cli/list-command.ts:50-100

调用 MCP 工具

基础调用语法

使用 mcporter call 命令调用服务器上的工具：

mcporter call <server>.<tool> [参数...]
mcporter call context7.resolve-library library_name="shadcn"

mcporter 会自动处理：

• 参数类型转换（布尔值、数字、JSON）
• 必需参数验证
• 位置参数到命名参数的映射

资料来源：src/cli/call-command.ts:1-40

参数传递方式

#### 命名参数

# 使用 key=value 格式
mcporter call server.tool arg1=value1 arg2=value2

# 使用 key:value 格式
mcporter call server.tool arg1:value1 arg2:value2

#### 位置参数

当工具参数按声明顺序传递时，mcporter 会根据工具的输入模式自动匹配：

mcporter call context7.resolve-library shadcn

如果位置参数数量超过剩余必需参数数量，命令会报错并提示正确的参数数量。

资料来源：src/cli/call-command.ts:40-80

参数类型处理

mcporter 支持智能类型推断：

使用 --no-coerce 可禁用类型推断，保持所有值为原始字符串。

# 禁用类型转换
mcporter call server.tool --no-coerce arg1=value1

资料来源：src/cli/call-command.ts:80-120

处理工具输出

mcporter call 返回的结果封装在 CallResult 对象中，支持多种访问方式：

# 格式化输出（默认）
mcporter call context7.resolve-library library_name="shadcn"

# 原始输出
mcporter call context7.resolve-library --raw library_name="shadcn"

# JSON 格式
mcporter call context7.resolve-library --json library_name="shadcn"

资料来源：src/result-utils.ts:1-50

保存图片内容

某些 MCP 工具会返回图片内容，使用 --save-images 参数可以将其保存到指定目录：

mcporter call server.tool --save-images ./output_dir arg1=value1

图片会按工具响应中的顺序编号保存，输出形状保持不变。

资料来源：README.md:30-35

服务器生命周期管理

mcporter 支持不同的服务器生命周期模式，决定工具调用后服务器的运行行为：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "lifecycle": {
        "mode": "keep-alive",
        "idleTimeoutMs": 300000
      }
    }
  }
}

资料来源：src/lifecycle.ts:1-30

动态端口处理

某些服务器（如 chrome-devtools）需要动态分配端口。mcporter 会自动检测并处理以下场景：

• 检测命令参数中的端口占位符
• 在运行时分配可用端口
• 将端口信息传递给子进程

配置管理

交互式配置命令

使用 mcporter config 子命令进行配置管理：

# 查看所有配置
mcporter config list

# 获取特定配置
mcporter config get context7

# 添加新服务器
mcporter config add my-server --command "npx" --arg "-y" --arg "my-mcp-server"

# 导入其他编辑器的配置
mcporter config import cursor --copy

资料来源：src/cli/config/help.ts:1-50

配置查找与自动补全

mcporter 使用模糊匹配来查找服务器名称，即使输入有拼写错误也能找到正确的配置：

# 错误拼写会自动纠正
mcporter list sshadcn
# 输出: sshadcn → shadcn (自动纠正提示)

# 服务器选择器支持 .tool 语法
mcporter list context7.resolve-library

资料来源：src/cli/list-command.ts:100-150

多环境配置

支持使用 --config 和 --root 参数切换不同的配置环境：

# 使用项目级配置
mcporter list --config ./project/config/mcporter.json

# 设置工作目录
mcporter call server.tool --root /path/to/project arg1=value1

生成工具客户端

生成 TypeScript 类型定义

使用 emit-ts 命令生成强类型工具接口：

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

# 生成带客户端包装器
npx mcporter emit-ts linear --mode client --out clients/linear.ts

附加选项：

• --include-optional：展开所有可选字段
• --json：输出结构化摘要而非纯文本

资料来源：README.md:100-120

生成独立 CLI 工具

将 MCP 服务器转换为独立的可分发 CLI：

# 从 URL 生成
npx mcporter generate-cli --command https://mcp.context7.com/mcp

# 从 npm 包生成
npx mcporter generate-cli "npx -y chrome-devtools-mcp@latest"

# 指定输出名称
npx mcporter generate-cli --command https://mcp.context7.com/mcp --name context7

生成的工件包含：

• context7.ts：TypeScript 模板 + 嵌入的 schema
• context7.js：打包后的 CLI（使用 Rolldown 或 Bun）

# 检查已生成的 CLI
npx mcporter inspect-cli dist/context7.js

# 重新生成（使用嵌入的元数据）
npx mcporter generate-cli --from dist/context7.js

资料来源：README.md:80-100

常见工作流程

流程图：基础调用流程

graph TD
    A[开始] --> B[配置 mcporter.json]
    B --> C[运行 mcporter list]
    C --> D{服务器可用?}
    D -->|是| E[运行 mcporter call]
    D -->|否| F[检查配置和网络]
    F --> C
    E --> G[解析 CallResult]
    G --> H[提取所需格式]
    H --> I[结束]

流程图：工具调用处理

graph TD
    A[mcporter call 命令] --> B[解析参数]
    B --> C{使用 --no-coerce?}
    C -->|是| D[保持字符串类型]
    C -->|否| E[智能类型推断]
    E --> F[验证必需参数]
    F --> G{参数完整?}
    G -->|否| H[显示错误信息]
    G -->|是| I[构建 MCP 请求]
    I --> J[发送请求到服务器]
    J --> K[接收响应]
    K --> L[包装为 CallResult]
    L --> M[返回给调用者]

典型使用场景

#### 场景一：快速查询文档

# 1. 列出可用服务器
mcporter list

# 2. 查看特定服务器工具
mcporter list context7

# 3. 调用文档查询工具
mcporter call context7.resolve-library library_name="shadcn"

#### 场景二：调试 MCP 服务器

# 使用 verbose 模式查看详细信息
mcporter list context7 --verbose

# 启用调试日志
mcporter list --log-level debug

# 查看日志尾随内容
mcporter call server.tool --tail-log

#### 场景三：自动化脚本集成

#!/bin/bash
# 批量调用脚本

SERVERS=("context7" "shadcn" "linear")
for server in "${SERVERS[@]}"; do
    echo "检查服务器: $server"
    mcporter list "$server" --json | jq -r '.status'
done

故障排除

常见问题与解决方案

调试模式

启用详细日志进行问题排查：

# 设置日志级别
export MCPORTER_LOG_LEVEL=debug

# 运行命令
mcporter call server.tool arg=value

# 或直接在命令中指定
mcporter call server.tool arg=value --log-level debug

使用 --tail-log 查看关联的日志文件：

mcporter call server.tool --tail-log

下一步

• 阅读 配置参考文档 了解更多配置选项
• 查看 Agent Skills 指南 了解如何为 AI Agent 创建技能
• 参考 emit-ts 文档 生成强类型客户端

架构总览

mcporter 的设计采用了分层架构模式，核心组件包括：

配置管理模块

配置解析流程

配置管理模块负责加载和规范化用户配置。mcporter 支持多种配置格式，包括 mcporter.json 和 mcporter.jsonc（支持注释和尾随逗号的 JSON）。

配置导入机制

外部配置导入功能支持从多种编辑器配置中读取 MCP 服务器定义：

// 支持的配置容器
{
  allowMcpServers: true,   // 标准 mcpServers
  allowServers: true,      // servers 容器
  allowMcp: true,          // mcp 容器
  allowRootFallback: true  // 根目录回退
}

资料来源：src/config/imports/external.ts:15-25

对于 Claude Code 配置，有特殊的路径规范化逻辑：

const allowRootFallback =
  normalized.endsWith('.claude.json') || 
  normalized.endsWith(`${path.sep}.claude${path.sep}mcp.json`);

资料来源：src/config/imports/external.ts:11-14

配置值转换

配置导入模块提供了类型安全的数据转换工具：

资料来源：src/config/imports/external.ts:40-62

生命周期管理

生命周期模式

mcporter 支持两种服务端生命周期模式：

graph TD
    A[MCP 服务器定义] --> B{生命周期模式}
    B -->|keep-alive| C[持续运行]
    B -->|ephemeral| D[按需启动]
    C --> E[idleTimeoutMs 配置]
    D --> F[调用后终止]

资料来源：src/lifecycle.ts:45-50

生命周期序列化函数 serializeLifecycle 处理以下返回值格式：

// 三种序列化形式
'keep-alive'                                    // 无超时
{ mode: 'keep-alive', idleTimeoutMs?: number }  // 带超时
'ephemeral'                                     // 临时模式

资料来源：src/cli/adhoc-server.ts:89-97

动态端口检测

对于 Chrome DevTools 相关的 MCP 服务器，mcporter 支持动态端口分配：

const CHROME_DEVTOOLS_URL_PLACEHOLDERS = [
  '__MCP_PORT_3000__',
  '__MCP_PORT_9222__',
  // ...其他占位符
];

function commandRequiresDynamicChromePort(command: CommandSpec): boolean {
  if (command.kind !== 'stdio') {
    return false;
  }
  const tokens = [command.command, ...command.args];
  return tokens.some((token) => 
    CHROME_DEVTOOLS_URL_PLACEHOLDERS.some(
      (placeholder) => token.includes(placeholder)
    )
  );
}

资料来源：src/lifecycle.ts:19-33

Keep-Alive 命令识别

mcporter 内置了对常见持续运行命令的识别：

const KEEP_ALIVE_COMMANDS = [
  { label: 'docker', fragments: ['docker'] },
  { label: 'npx', fragments: ['npx', 'npm exec'] },
  // ...更多命令模式
];

function commandRequiresKeepAlive(command: CommandSpec): string | undefined {
  if (command.kind !== 'stdio') {
    return undefined;
  }
  const tokens = [command.command, ...command.args].map(
    (token) => token.toLowerCase()
  );
  const match = KEEP_ALIVE_COMMANDS.find((signature) =>
    signature.fragments.some((fragment) =>
      tokens.some((token) => token.includes(fragment))
    )
  );
  return match?.label;
}

资料来源：src/lifecycle.ts:6-18

覆盖集合解析

配置中的覆盖设置使用集合匹配机制：

function parseList(value: string | undefined): OverrideSet {
  if (!value) {
    return { all: false, names: new Set() };
  }
  const names = value
    .split(',')
    .map((token) => token.trim().toLowerCase())
    .filter((token) => token.length > 0);
  
  if (names.includes('*')) {
    return { all: true, names: new Set() };
  }
  return { all: false, names: new Set(names) };
}

function matchesOverride(names: Set<string>, candidates: Set<string>): boolean {
  for (const candidate of candidates) {
    if (names.has(candidate)) {
      return true;
    }
  }
  return false;
}

资料来源：src/lifecycle.ts:35-62

CLI 命令系统

命令路由

CLI 入口点 src/cli.ts 负责将命令行参数路由到相应的处理函数：

graph TD
    A[CLI 入口] --> B[命令解析]
    B --> C{命令类型}
    C -->|list| D[list-command.ts]
    C -->|call| E[call-command.ts]
    C -->|config| F[config 子系统]
    C -->|generate-cli| G[CLI 生成]
    C -->|emit-ts| H[类型导出]
    C -->|inspect-cli| I[CLI 检查]

工具选择器解析

list-command.ts 实现了智能工具选择器解析，支持 server.tool 格式的直接调用：

function resolveConfiguredToolSelector(
  runtime: Runtime,
  target: string | undefined
): { server: string; tool: string } | undefined {
  if (!target || !target.includes('.')) {
    return undefined;
  }
  const definitions = runtime.getDefinitions();
  const match = definitions
    .map((definition) => definition.name)
    .filter((name) => target.startsWith(`${name}.`))
    .toSorted((a, b) => b.length - a.length)[0];
  
  if (!match) {
    return undefined;
  }
  const tool = target.slice(match.length + 1);
  if (!tool) {
    return undefined;
  }
  return { server: match, tool };
}

资料来源：src/cli/list-command.ts:90-109

服务器定义解析

解析流程如下：

1. 检查目标是否为配置的 server.tool 格式
2. 尝试从运行时获取服务器定义
3. 解析超时配置
4. 格式化传输层摘要

const resolved = resolveServerDefinition(runtime, target);
if (!resolved) {
  return;
}
target = resolved.name;
const definition = resolved.definition;
const timeoutMs = flags.timeoutMs ?? LIST_TIMEOUT_MS;

资料来源：src/cli/list-command.ts:40-50

列表输出系统

状态分类

mcporter 使用标准化的状态分类系统：

type StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';

export function createEmptyStatusCounts(): Record<StatusCategory, number> {
  return {
    ok: 0,
    auth: 0,
    offline: 0,
    http: 0,
    error: 0,
  };
}

资料来源：src/cli/list-output.ts:42-50

列表格式化

列表格式化模块负责生成用户友好的输出：

export function truncateForSpinner(text: string, maxLength = 72): string {
  if (text.length <= maxLength) {
    return text;
  }
  return `${text.slice(0, Math.max(0, maxLength - 1))}…`;
}

资料来源：src/cli/list-format.ts:29-34

工具元数据过滤

支持按工具名称过滤返回的元数据：

function filterToolMetadata(
  entries: ToolMetadata[], 
  requestedTool: string | undefined
): ToolMetadata[] {
  if (!requestedTool) {
    return entries;
  }
  return entries.filter((entry) => entry.tool.name === requestedTool);
}

资料来源：src/cli/list-command.ts:111-117

结果处理系统

内容类型提取

result-utils.ts 实现了复杂的内容解析逻辑：

graph TD
    A[CallResult] --> B{内容类型判断}
    B -->|text| C[textEntries]
    B -->|markdown| D[markdownEntries + textEntries]
    B -->|image| E[images]
    B -->|resource| F[资源处理]
    B -->|JSON| G[jsonCandidates]

资源负载收集

function collectResourcePayload(
  resource: unknown,
  textEntries: string[],
  markdownEntries: string[],
  jsonCandidates: unknown[]
): void {
  if (!resource || typeof resource !== 'object') {
    return;
  }
  const record = resource as Record<string, unknown>;
  const mimeType = typeof record.mimeType === 'string' 
    ? record.mimeType 
    : '';
  
  if (typeof record.text === 'string') {
    textEntries.push(record.text);
    if (mimeType.toLowerCase().includes('markdown')) {
      markdownEntries.push(record.text);
    }
    const parsed = tryParseJson(record.text);
    if (parsed !== null) {
      jsonCandidates.push(parsed);
    }
  } else if (typeof record.blob === 'string') {
    textEntries.push(`[Binary resource: ${uri}]`);
  }
}

资料来源：src/result-utils.ts:77-101

JSON 信封展开

支持从标准信封格式中提取 JSON 数据：

function unwrapJsonEnvelope(
  record: Record<string, unknown>, 
  fallback: unknown
): unknown {
  if ('json' in record) {
    return record.json ?? null;
  }
  if ('data' in record) {
    return Object.keys(record).length === 1 
      ? (record.data ?? null) 
      : fallback;
  }
  return null;
}

资料来源：src/result-utils.ts:111-121

临时服务器管理

Ad-hoc 服务器解析

mcporter 支持通过命令行直接定义临时 MCP 服务器：

graph TD
    A[--stdio 命令字符串] --> B[引号解析]
    B --> C[命令+参数分离]
    C --> D[生命周期决定]
    D --> E[序列化配置]
    E --> F[运行时注册]

命令字符串解析

实现了完整的 shell 风格引号解析：

function parseStdioCommand(input: string): string[] {
  const result: string[] = [];
  let current = '';
  let inSingle = false;
  let inDouble = false;
  
  for (let i = 0; i < input.length; i += 1) {
    const char = input[i];
    
    if (char === '\\' && !inSingle) {
      // 转义处理
      continue;
    }
    
    if (char === "'" && !inDouble) {
      inSingle = !inSingle;
      continue;
    }
    if (char === '"' && !inSingle) {
      inDouble = !inDouble;
      continue;
    }
    // ...
  }
  
  return result;
}

资料来源：src/cli/adhoc-server.ts:40-75

环境变量控制

mcporter 通过环境变量支持运行时行为控制：

function isFastPathKeepAliveDisabled(server: string): boolean {
  const raw = process.env.MCPORTER_DISABLE_KEEPALIVE 
    ?? process.env.MCPORTER_NO_KEEPALIVE;
  
  if (!raw) {
    return false;
  }
  
  const disabled = new Set(
    raw
      .split(',')
      .map((entry) => entry.trim().toLowerCase())
      .filter(Boolean)
  );
  
  return disabled.has('*') || disabled.has(server.toLowerCase());
}

资料来源：src/cli.ts:89-104

数据流图

列表命令完整数据流

sequenceDiagram
    participant CLI as CLI 入口
    participant Parse as 参数解析
    participant Runtime as 运行时
    participant Server as MCP 服务器
    participant Format as 格式化输出
    
    CLI->>Parse: mcporter list [server]
    Parse->>Runtime: 获取服务器定义
    Runtime->>Server: 建立连接
    Server-->>Runtime: 工具元数据
    Runtime-->>Format: ListSummaryResult
    Format->>Format: 状态分类
    Format->>Format: 格式化输出
    Format-->>CLI: 控制台输出

结果处理流程

graph LR
    A[Tool Call Response] --> B[类型检测]
    B -->|文本| C[收集文本]
    B -->|图片| D[收集图片]
    B -->|资源| E[收集资源]
    B -->|JSON| F[JSON 候选]
    C --> G[合并输出]
    D --> G
    E --> G
    F --> G
    G --> H[CallResult]

错误处理策略

mcporter 实现了多层次的错误处理机制：

1. 超时处理：通过 withTimeout 包装异步操作
2. 认证错误分类：区分 auth/offline/http/error 状态
3. 解析容错：对可忽略的解析错误进行特殊处理
4. 类型安全转换：使用 asString() 等工具函数避免类型错误

function shouldIgnoreParseError(error: unknown): boolean {
  if (error instanceof SyntaxError) {
    return true;
  }
  if (!error || typeof error !== 'object') {
    return false;
  }
  return 'fromTOML' in error;
}

资料来源：src/config/imports/external.ts:64-71

扩展性设计

mcporter 的架构设计支持多种扩展方式：

1. 新命令添加：在 src/cli.ts 中注册新命令处理器
2. 配置格式扩展：在 src/config/imports/ 下添加新的导入器
3. 输出格式扩展：在 src/cli/ 下添加新的格式化器
4. 生命周期模式：在 src/lifecycle.ts 中定义新的生命周期处理

概述

mcporter 的运行时系统是整个工具调用框架的核心子系统，负责 MCP 服务器的创建、管理、工具调用及生命周期控制。该系统封装了与 MCP 服务器的通信细节，提供统一的运行时抽象，使 CLI 命令能够以一致的方式与不同类型的 MCP 服务器交互。

运行时系统的主要职责包括：

• 服务器运行时创建与管理：通过 createRuntime 工厂函数实例化服务器运行时
• 工具元数据加载：获取 MCP 服务器提供的工具列表及参数模式
• 工具调用执行：将工具调用请求路由到目标服务器并处理响应
• 生命周期管理：支持 keep-alive 和 ephemeral 两种运行模式
• 结果解析与格式化：从服务器响应中提取文本、图像、JSON 等内容

资料来源：src/cli/list-command.ts:18-30

架构设计

核心组件关系

graph TD
    subgraph "运行时系统核心"
        RT[运行时实例]
        SP[服务器代理 ServerProxy]
        LC[生命周期管理器]
        EU[结果工具]
    end
    
    subgraph "外部接口"
        CLI[CLI 命令层]
        API[导出 API]
    end
    
    subgraph "服务器定义"
        DEF[ServerDefinition]
        META[ToolMetadata]
    end
    
    CLI --> RT
    API --> RT
    RT --> SP
    RT --> LC
    SP --> DEF
    RT --> EU
    EU --> META

运行时创建流程

sequenceDiagram
    participant CLI as CLI 命令
    participant RT as createRuntime
    participant SP as ServerProxy
    participant DEF as ServerDefinition
    participant LC as Lifecycle
    
    CLI->>RT: 创建运行时请求
    RT->>DEF: 解析服务器定义
    DEF-->>RT: 定义配置
    RT->>LC: 初始化生命周期
    LC-->>RT: 生命周期状态
    RT->>SP: 创建服务器代理
    SP-->>RT: 代理实例
    RT-->>CLI: 运行时句柄

资料来源：src/runtime.ts

核心数据类型

ServerDefinition

服务器定义是运行时系统的核心配置单元，描述单个 MCP 服务器的连接参数：

资料来源：src/server-proxy.ts

ToolMetadata

工具元数据描述 MCP 服务器暴露的单个工具：

interface ToolMetadata {
  tool: { name: string; description: string };
  inputSchema: JsonSchema;
  outputSchema?: JsonSchema;
}

资料来源：src/cli/list-command.ts:31-36

生命周期管理

生命周期模式

运行时系统支持两种服务器生命周期模式：

type ServerLifecycle =
  | { mode: 'keep-alive'; idleTimeoutMs?: number }
  | { mode: 'ephemeral' };

keep-alive 命令识别

系统通过签名片段匹配识别需要保持连接的服务器命令：

const KEEP_ALIVE_COMMANDS = [
  { label: 'docker', fragments: ['docker', 'run'] },
  { label: 'npx', fragments: ['npx'] },
  { label: 'bun', fragments: ['bun', 'x'] },
  // 更多命令...
];

当命令包含匹配的签名片段时，系统自动应用 keep-alive 生命周期。

资料来源：src/lifecycle.ts

结果解析系统

ResultUtils 工具模块

result-utils.ts 提供的工具函数负责从 MCP 服务器响应中提取结构化数据：

export interface ExtractedContent {
  content: unknown;
  structuredContent: unknown;
  textEntries: string[];
  markdownEntries: string[];
  jsonCandidates: unknown[];
  images: ImageContent[] | null;
}

内容提取流程

flowchart TD
    A[MCP 响应 envelope] --> B{遍历 content 数组}
    B -->|image 类型| C[提取图像数据]
    B -->|resource 类型| D[收集资源载荷]
    B -->|text/markdown| E[文本处理]
    B -->|其他类型| F[跳过]
    
    C --> G[合并图像列表]
    D --> H[解析 text/blob]
    E --> I[文本条目收集]
    
    H --> J[JSON 解析尝试]
    I --> J
    
    G --> K[返回 ExtractedContent]
    J --> K
    K --> K

支持的内容类型

资料来源：src/result-utils.ts:1-80

错误处理机制

错误分类系统

运行时系统包含完善的错误分类机制，为不同类型的连接问题提供诊断建议：

flowchart TD
    A[错误发生] --> B{错误类型判定}
    B -->|认证失败| C[auth 错误类别]
    B -->|网络不可达| D[offline 错误类别]
    B -->|HTTP 错误| E[http 错误类别]
    B -->|其他| F[error 错误类别]
    
    C --> G[生成 authCommand 提示]
    D --> H[提供连接检查建议]
    E --> I[显示 HTTP 状态码]
    F --> J[通用错误信息]

状态类别定义

type StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';

资料来源：src/runtime/errors.ts, src/cli/list-format.ts:25-40

工具调用流程

标准工具调用序列

sequenceDiagram
    participant User as 用户/CLI
    participant RT as Runtime
    participant SP as ServerProxy
    participant Server as MCP Server
    participant Utils as ResultUtils
    
    User->>RT: callTool(name, args)
    RT->>SP: 路由到目标服务器
    SP->>Server: 发送 JSON-RPC 请求
    Server-->>SP: 工具响应
    SP-->>RT: 响应 envelope
    RT->>Utils: extractContent(envelope)
    Utils-->>RT: ExtractedContent
    RT-->>User: 格式化结果

工具选择器解析

系统支持 server.tool 格式的工具选择器，简化跨服务器工具调用：

function resolveConfiguredToolSelector(
  runtime: Runtime,
  target: string | undefined
): { server: string; tool: string } | undefined {
  if (!target || !target.includes('.')) {
    return undefined;
  }
  // 匹配 server.tool 格式
  const match = definitions
    .filter((name) => target.startsWith(`${name}.`))
    .sort((a, b) => b.length - a.length)[0];
  
  if (!match) return undefined;
  const tool = target.slice(match.length + 1);
  return { server: match, tool };
}

此函数自动从 server.tool 格式中提取服务器名称和工具名称。

资料来源：src/cli/list-command.ts:45-60

配置与超时控制

超时配置参数

运行时超时处理

const metadataEntries = await withTimeout(
  loadToolMetadata(runtime, target, {
    includeSchema: true,
    autoAuthorize: false,
    allowCachedAuth: true,
  }),
  timeoutMs
);

工具元数据加载使用 withTimeout 包装，确保操作不会无限阻塞。

资料来源：src/cli/list-command.ts:85-95

调试支持

运行时调试模式

src/cli/runtime-debug.ts 提供了详细的进程清理逻辑，用于调试挂起问题：

// 强制销毁 Socket 句柄
if (ctor === 'Socket' && typeof handle.destroy === 'function') {
  handle.destroy?.();
  handle.unref?.();
}

// 清理子进程 stdio
candidate.stdout?.destroy?.();
candidate.stderr?.destroy?.();
candidate.stdin?.end?.();

// 可选强制 SIGKILL
if (DEBUG_HANG) {
  candidate.kill?.('SIGKILL');
}

当启用 DEBUG_HANG 环境变量时，系统会记录详细的进程终止信息。

资料来源：src/cli/runtime-debug.ts

导出 API

运行时系统通过以下入口导出公共接口：

// 主入口
export { createRuntime } from './runtime.js';

// 工具函数
export { 
  loadToolMetadata,
  callTool,
  getDefinitions 
} from './runtime.js';

// 结果处理
export { 
  extractContent,
  extractText,
  extractStructuredContent 
} from './result-utils.js';

// 错误类型
export { 
  McpError,
  ConnectionError,
  TimeoutError 
} from './runtime/errors.js';

资料来源：src/runtime.ts, src/result-utils.ts

最佳实践

1. 选择合适的生命周期模式

// 高频调用场景 - 使用 keep-alive
const server = {
  name: 'frequently-used',
  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },
  lifecycle: { mode: 'keep-alive', idleTimeoutMs: 60000 }
};

// 低频调用场景 - 使用 ephemeral
const server = {
  name: 'rarely-used',
  command: { kind: 'stdio', command: 'npx', args: ['-y', 'some-mcp'] },
  lifecycle: { mode: 'ephemeral' }
};

2. 配置合理的超时时间

# 启动时指定超时
mcporter list --timeout-ms 60000

# 或通过环境变量
export MCPORTER_OAUTH_TIMEOUT_MS=120000

3. 利用工具选择器

# 正确使用 server.tool 格式
mcporter call context7.getComponents --prompt "React button"

# 不需要显式指定服务器
mcporter list linear.listProjects

总结

mcporter 的运行时系统通过抽象 MCP 服务器的连接细节，提供了一个统一、可靠的工具调用平台。其核心设计包括：

1. 声明式配置：通过 ServerDefinition 描述服务器连接参数
2. 生命周期管理：支持 keep-alive 和 ephemeral 两种模式平衡资源与性能
3. 结构化结果处理：完善的响应解析支持多种内容类型
4. 完善的错误诊断：分类错误并提供可操作的修复建议
5. 调试支持：内置进程清理和挂起检测机制

这些设计使得 mcporter 能够可靠地与各种 MCP 服务器交互，同时保持良好的开发体验。

概述

传输层是 mcporter 架构中连接 MCP 服务器与客户端的核心组件，负责处理不同通信协议之间的数据传输与协议协商。mcporter 支持多种传输方式，包括 HTTP、SSE（Server-Sent Events）和 stdio（标准输入输出），每种传输方式都有其特定的适用场景和配置要求。

传输层的主要职责包括：

• 建立与 MCP 服务器的连接
• 处理请求与响应的序列化/反序列化
• 管理传输生命周期（持久连接 vs 临时连接）
• 处理认证和授权流程
• 提供传输层面的错误处理与重试机制

资料来源：src/runtime/transport.ts:1-50

支持的传输类型

mcporter 支持三种主要的传输协议，开发者可通过 --transport 参数显式指定，或由系统自动检测：

资料来源：src/cli/config/help.ts:3

HTTP 传输

基本原理

HTTP 传输是 mcporter 用于连接远程 MCP 服务器的主要方式。客户端通过 HTTP POST 请求发送工具调用请求，服务器返回 JSON 格式的响应。

graph LR
    A[mcporter 客户端] -->|POST /call-tool| B[HTTP MCP 服务器]
    B -->|200 OK + JSON| A
    A -->|GET /tools| B
    B -->|200 OK + JSON Schema| A

URL 处理

HTTP 传输层支持完整的 URL 解析，包括：

• 标准 HTTPS URL
• 自定义端口指定
• 路径前缀处理

资料来源：src/cli/http-utils.ts:1-30

请求配置

HTTP 传输支持多种请求头配置，用于认证和自定义元数据传递：

interface HttpTransportConfig {
  url: string;
  headers?: Record<string, string>;
  timeout?: number;
}

资料来源：src/runtime/node-http-fetch.ts:1-40

SSE 传输

基本原理

SSE（Server-Sent Events）传输允许服务器主动向客户端推送消息，这在需要实时通知或长连接操作的场景中特别有用。

graph TB
    A[mcporter 客户端] -->|建立 SSE 连接| B[MCP 服务器]
    B -->|事件流| A
    A -->|POST 请求| B
    B -->|响应| A

SSE 传输层会自动处理连接重连和心跳机制，确保连接的可靠性。

资料来源：src/runtime/transport.ts:100-150

stdio 传输

基本原理

stdio 传输通过标准输入输出与本地 MCP 服务器进程通信。这种方式适用于：

• 本地安装的 MCP 服务器
• 需要在同一进程中运行的服务
• 调试和开发环境

命令解析

stdio 传输支持复杂的命令行解析，包括引号处理和参数转义：

graph TD
    A[原始命令字符串] --> B[字符逐个解析]
    B --> C{检测引号状态}
    C -->|"单引号 ''"| D[单引号模式]
    C -->|"双引号 \"\""| E[双引号模式]
    C -->|普通字符| F[追加到当前 token]
    D --> G{遇到单引号?}
    E --> H{遇到双引号?}
    G -->|是| I[结束引号模式]
    G -->|否| D
    H -->|是| J[结束引号模式]
    H -->|否| E
    I --> F
    J --> F
    F --> K{结束?}
    K -->|否| B
    K -->|是| L[返回 token 数组]

资料来源：src/cli/adhoc-server.ts:50-100

特殊命令识别

stdio 传输包含对特定命令的自动识别机制：

资料来源：src/lifecycle.ts:30-80

传输生命周期管理

生命周期模式

mcporter 支持两种服务器生命周期模式：

持久化配置

interface LifecycleConfig {
  mode: 'keep-alive' | 'ephemeral';
  idleTimeoutMs?: number;  // 可选的空闲超时配置
}

资料来源：src/lifecycle.ts:100-150

生命周期序列化

graph TD
    A[生命周期配置] --> B{mode 检测}
    B -->|keep-alive + 无超时| C[返回字符串 'keep-alive']
    B -->|keep-alive + 有超时| D[返回对象 {mode, idleTimeoutMs}]
    B -->|ephemeral| E[返回字符串 'ephemeral']
    C --> F[序列化完成]
    D --> F
    E --> F

资料来源：src/cli/adhoc-server.ts:120-140

传输层工具函数

传输摘要格式化

formatTransportSummary 函数用于生成人类可读的传输信息摘要：

function formatTransportSummary(
  server: ServerDefinition,
  options?: { verbose?: boolean }
): string

返回值示例：

• HTTP 传输：https://api.example.com/mcp
• stdio 传输：stdio /usr/local/bin/mcp-server

资料来源：src/cli/transport-utils.ts:1-50

传输类型检测

传输层提供自动检测机制，根据服务器配置推断最合适的传输类型：

function inferTransportType(config: ServerConfig): TransportType

检测优先级：

1. 显式指定的 --transport 参数
2. URL 格式（http:///https:// → HTTP/SSE）
3. 命令行配置（存在 command 字段 → stdio）
4. 默认fallback

资料来源：src/runtime/transport.ts:50-100

HTTP 请求处理

Node.js 环境适配

mcporter 在 Node.js 环境中使用原生 fetch API，并通过 node-http-fetch.ts 模块提供额外配置能力：

// 超时配置示例
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    ...customHeaders
  },
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(timeoutMs)
});

资料来源：src/runtime/node-http-fetch.ts:40-80

错误处理

HTTP 传输层的错误分类：

资料来源：src/cli/http-utils.ts:50-100

进程清理与资源管理

标准清理流程

对于 stdio 传输，mcporter 在连接关闭时执行以下清理：

graph TD
    A[检测连接关闭信号] --> B[销毁 stdout 流]
    B --> C[销毁 stderr 流]
    C --> D[关闭 stdin 管道]
    D --> E{DEBUG_HANG 启用?}
    E -->|是| F[发送 SIGKILL]
    E -->|否| G[正常退出]
    F --> H[记录调试信息]

资料来源：src/cli/runtime-debug.ts:20-60

锁文件恢复

传输层包含锁文件管理机制，用于处理异常进程退出：

async function removeRecoverableLock(lockPath: string): Promise<boolean>

恢复条件：

• 锁文件持有进程已不存在
• 锁文件创建时间超过阈值
• breaker 文件存在且满足恢复条件

资料来源：src/fs-json.ts:60-100

配置参考

传输相关配置项

命令行参数

资料来源：src/cli/config/help.ts:1-30

最佳实践

选择传输类型

1. 远程 API 访问：优先使用 HTTP 传输
2. 需要实时推送：选择 SSE 传输
3. 本地工具集成：使用 stdio 传输
4. 混合场景：在配置文件中为每个服务器单独指定

性能优化

• 对于频繁调用的服务器，启用 keep-alive 模式减少连接建立开销
• HTTP 传输建议设置合理的超时时间（默认 60 秒）
• stdio 传输注意进程清理，避免僵尸进程

安全建议

• 使用 HTTPS 替代 HTTP 传输敏感数据
• 通过环境变量存储认证凭据，避免硬编码
• 定期轮换 OAuth 客户端密钥

相关文档

• 配置管理 - 传输层配置详解
• 认证流程 - OAuth 和 API Key 认证
• 工具调用 - 通过传输层执行工具调用
• CLI 生成 - 生成独立 CLI 工具

概述

mcporter 提供了一套完整的命令行工具，用于管理、调用和调试 MCP（Model Context Protocol）服务器。该 CLI 是与 MCP 服务器交互的主要入口点，支持服务器发现、工具调用、配置管理以及代码生成等功能。

CLI 工具的核心设计理念是统一处理不同类型的 MCP 服务器（HTTP、SSE、stdio），并提供一致的接口和输出格式。通过运行时抽象层，mcporter 能够自动发现已配置的服务器、处理 OAuth 认证、管理连接生命周期。资料来源：README.md:1-50

核心命令架构

mcporter CLI 采用子命令架构，主要包含以下命令模块：

graph TD
    A[mcporter] --> B[list]
    A --> C[call]
    A --> D[config]
    A --> E[generate-cli]
    A --> F[emit-ts]
    A --> G[inspect-cli]
    
    B --> B1[列出所有服务器]
    C --> C1[调用指定工具]
    D --> D1[增删改查配置]
    E --> E1[生成独立CLI]
    F --> F1[生成TypeScript类型]
    G --> G1[检查CLI元数据]

全局选项

所有 mcporter 命令支持以下全局选项：

资料来源：src/cli/config/help.ts:1-30

mcporter list

list 命令用于列出已配置的 MCP 服务器及其可用工具。

基本用法

mcporter list [server]
mcporter list --json
mcporter list --signatures

选项说明

资料来源：src/cli/list-command.ts:1-50

输出状态分类

服务器状态分为以下几类：

资料来源：src/cli/list-format.ts:40-80

服务器信息格式化

输出格式包括工具数量、响应耗时和来源信息：

// 输出格式示例
- context7 (5 tools, 1.2s) [npm:@context7/mcp]
- firecrawl (3 tools, 0.8s) [local]

来源标签表示服务器的定义来源：

• [npm:xxx] - npm 包
• [local] - 本地配置
• [cursor] - Cursor 导入
• [claude] - Claude 导入

资料来源：src/cli/list-format.ts:80-120

mcporter call

call 命令用于调用 MCP 服务器上的特定工具。

基本用法

mcporter call <server>.<tool> [args...]
mcporter call context7.resolve-library-id --query "React hooks"

选项说明

参数传递规则

call 命令支持多种参数格式：

# 关键字参数
mcporter call server.tool --key value

# 位置参数
mcporter call server.tool arg1 arg2

# 混合使用
mcporter call server.tool --key value arg1

类型自动转换规则：

• true/false → 布尔值
• null → null
• 数字形式字符串 → 数字
• JSON 对象 → 对象

资料来源：README.md:50-100

mcporter config

config 命令用于管理 mcporter.json 配置文件。

子命令

资料来源：README.md:120-150

配置示例

{
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "$env:CONTEXT7_API_KEY"
      }
    }
  }
}

配置文件支持 JSONC 格式，允许内联注释和尾随逗号。资料来源：README.md:140-180

mcporter generate-cli

生成独立的可分享 CLI 工件，将 MCP 服务器转换为独立的命令行工具。

基本用法

mcporter generate-cli --command https://mcp.context7.com/mcp
mcporter generate-cli "npx -y chrome-devtools-mcp@latest"
mcporter generate-cli linear --bundle dist/linear.js

生成选项

资料来源：README.md:30-60

工件元数据

生成的 CLI 嵌入以下元数据：

npx mcporter inspect-cli dist/context7.js     # 查看元数据摘要
npx mcporter generate-cli --from dist/context7.js  # 使用元数据重新生成

mcporter emit-ts

生成强类型的 TypeScript 客户端代码，无需完整的 CLI 即可使用 MCP 工具。

基本用法

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

# 生成客户端包装器
mcporter emit-ts linear --mode client --out clients/linear.ts

输出模式

附加选项

生成的客户端模式与 createRuntime() API 保持同步。资料来源：README.md:70-100

mcporter inspect-cli

检查已生成 CLI 工件的元数据和签名信息。

基本用法

mcporter inspect-cli dist/context7.js

服务器生命周期管理

mcporter 支持两种服务器生命周期模式：

生命周期配置

{
  "lifecycle": {
    "mode": "keep-alive",
    "idleTimeoutMs": 300000
  }
}

自动保活检测：mcporter 会识别特定的命令签名（如某些 chrome-devtools 命令），自动应用 keep-alive 策略。资料来源：src/lifecycle.ts:1-50

输出格式化

文本模式

默认使用人类可读的格式化输出：

✓ context7 (5 tools, 1.2s)
  - resolve-library-id(query, libraryName)
  - get-library-docs(libraryId, ...)

JSON 模式

使用 --json 选项获取机器可读输出：

{
  "servers": [
    {
      "name": "context7",
      "status": "ok",
      "durationMs": 1200,
      "tools": [...]
    }
  ]
}

资料来源：src/cli/list-output.ts:1-80

OAuth 认证

mcporter 自动处理 MCP 服务器的 OAuth 认证流程。

OAuth 配置选项

认证流程

sequenceDiagram
    participant User
    participant CLI as mcporter
    participant Server as MCP Server
    participant Browser
    
    User->>CLI: call <server>.<tool>
    CLI->>Server: 发现需要 OAuth
    Server->>Browser: 重定向到授权页面
    Browser->>User: 显示授权页面
    User->>Browser: 确认授权
    Browser->>Server: 授权码
    Server->>CLI: 颁发访问令牌
    CLI->>Server: 调用工具

认证超时默认 5 分钟，可通过 --oauth-timeout 调整。资料来源：src/cli/config/help.ts:1-40

错误处理与调试

常见错误状态

调试模式

mcporter list --log-level debug
DEBUG_HANG=1 mcporter call server tool

启用 DEBUG_HANG 后，mcporter 会在强制终止进程前留下调试标记，便于诊断连接问题。资料来源：src/cli/runtime-debug.ts:1-50

高级用法

临时服务器（Ad-hoc）

通过 --command 直接运行未配置的服务器：

mcporter list --command "npx -y some-mcp-server"

支持完整的命令参数传递和生命周期管理。资料来源：src/cli/adhoc-server.ts:1-50

工具选择器

使用点号分隔符精确指定服务器和工具：

mcporter list context7.resolve-library-id

自动补全和纠错功能支持模糊匹配服务器名称。资料来源：src/cli/list-command.ts:50-100

最佳实践

1. 配置管理：优先使用 mcporter config 管理配置，避免直接编辑 JSON 文件
2. 类型安全：使用 emit-ts 生成 TypeScript 类型，集成到开发工作流
3. 认证处理：生产环境使用环境变量存储敏感信息，配合 --oauth-client-secret-env
4. 调试技巧：使用 --tail-log 查看工具调用的关联日志
5. 性能优化：高频调用场景选择 keep-alive 生命周期模式

概述

mcporter 的工具调用语法（Tool Calling Syntax）是连接用户命令行与 MCP（Model Context Protocol）服务器工具之间的核心桥接层。该系统负责解析用户输入的参数表达式，将其转换为符合工具 schema 的结构化参数，并最终传递给运行时执行调用。

工具调用语法的主要职责包括：

• 参数解析：支持命名参数、位置参数、混合使用等多种调用方式
• 类型强制转换：自动将字符串形式的参数值转换为 schema 定义的正确类型
• 工具发现：根据服务器名称和工具名称定位目标工具
• 参数验证：验证参数是否符合工具定义的输入 schema

资料来源：src/cli/call-command.ts:1-50

核心组件架构

组件关系图

graph TD
    A[用户输入] --> B[call-command.ts]
    B --> C{参数类型判定}
    C -->|命名参数| D[直接使用命名参数]
    C -->|位置参数| E[call-expression-parser.ts]
    C -->|字符串候选| F[类型强制转换]
    C -->|数组候选| G[数组参数处理]
    E --> H[loadToolMetadata]
    H --> I[获取 Schema 信息]
    I --> J[参数映射]
    J --> K[参数验证]
    K --> L[runtime.callTool]
    F --> L
    G --> L

主要模块说明

资料来源：src/cli/call-command.ts:50-100

调用方式

mcporter 支持多种工具调用方式，以适应不同用户习惯和场景需求。

1. 命名参数方式

最直接的调用方式，用户显式指定每个参数的名称和值：

mcporter call <server>.<tool> --key1=value1 --key2=value2

示例：

mcporter call linear.create-issue --title="Bug Report" --team_id=team123

2. 位置参数方式

用户按照工具 schema 定义的参数顺序提供值，系统自动将位置参数映射到对应的字段：

mcporter call <server>.<tool> <arg1> <arg2> <arg3>

位置参数映射遵循以下规则：

• 仅填充未通过命名参数设置的字段
• 严格校验位置参数数量不超过剩余可填充字段数
• 必须按照 schema 中 required 参数在前、optional 参数在后的顺序提供

资料来源：src/cli/call-command.ts:150-200

const remaining = options.filter((option) => !(option.property in namedArgs));
if (positionalArgs.length > remaining.length) {
  throw new Error(
    `Too many positional arguments (${positionalArgs.length}) supplied; only ${remaining.length} parameter${remaining.length === 1 ? '' : 's'} remain on ${tool}.`
  );
}

3. 混合使用方式

命名参数和位置参数可以混合使用，命名参数具有更高的优先级：

mcporter call <server>.<tool> <arg1> --key2=value2 <arg3>

4. 选择器语法（Selector Syntax）

使用点号分隔符直接指定服务器和工具：

mcporter call <server>.<tool>

系统会从 <server>.<tool> 中提取服务器名称和工具名称，支持自动补全和建议功能。

资料来源：src/cli.ts:80-120

参数类型强制转换

mcporter 内置了智能的类型强制转换系统，能够自动将命令行输入的字符串值转换为工具 schema 定义的正确类型。

支持的转换类型

强制转换流程

graph LR
    A[原始输入] --> B{类型检测}
    B -->|key=value| C[stringCandidate]
    B -->|key:value| D[stringCandidate]
    B -->|尾部位置参数| E[stringCandidate]
    C --> F[loadToolMetadata]
    D --> F
    E --> F
    F --> G[获取 Schema]
    G --> H{字段类型匹配}
    H -->|number| I[parseFloat]
    H -->|boolean| J[布尔解析]
    H -->|null| K[空值处理]
    H -->|array| L[数组处理]
    I --> M[最终参数]
    J --> M
    K --> M
    L --> M

强制转换函数

参数强制转换的核心逻辑位于 enforceSchemaAwareArgumentTypes 函数中：

资料来源：src/cli/call-command.ts:200-250

async function enforceSchemaAwareArgumentTypes(
  runtime,
  server,
  tool,
  args,
  stringCandidates,
  arrayCandidates,
  timeoutMs
): Promise<Record<string, unknown>> {
  // 1. 获取工具 schema
  const tools = await withTimeout(loadToolMetadata(runtime, server, { includeSchema: true }), timeoutMs);
  const toolInfo = tools.find((entry) => entry.tool.name === tool);
  const schema = toolInfo?.tool.inputSchema as { properties?: Record<string, unknown> } | undefined;
  
  // 2. 遍历候选参数进行类型转换
  for (const [key, rawValue] of Object.entries(stringCandidates ?? {})) {
    if (typeof args[key] !== 'number') {
      continue; // 跳过已经是正确类型的参数
    }
    // 根据 schema 类型进行转换
  }
}

布尔值识别规则

mcporter 识别以下字符串为真值（case-insensitive）：

• true、yes、1、on

识别以下字符串为假值（case-insensitive）：

• false、no、0、off

位置参数解析详解

Schema 顺序保证

位置参数到命名参数的映射依赖于 schema 中定义的参数顺序。系统通过 loadToolMetadata 获取工具列表时，会同时返回符合 TypeScript 风格的签名顺序，确保 required 参数优先于 optional 参数。

资料来源：src/cli/call-command.ts:100-150

解析步骤

1. 加载工具元数据：获取完整 schema 和参数选项列表
2. 计算剩余字段：排除已通过命名参数设置的字段
3. 校验参数数量：确保位置参数不超过剩余字段数
4. 按顺序映射：将位置参数依次赋给剩余字段

const tools = await loadToolMetadata(runtime, server, { includeSchema: true }).catch(() => undefined);
const toolInfo = tools.find((entry) => entry.tool.name === tool);
const options = toolInfo.options;
const remaining = options.filter((option) => !(option.property in namedArgs));

工具选择器解析

服务器和工具名称推断

系统支持通过多种方式指定目标服务器和工具：

graph TD
    A[用户输入] --> B{包含点号?}
    B -->|是| C[解析 selector]
    B -->|否| D[检查 --server 参数]
    C --> E[提取服务器名]
    C --> F[提取工具名]
    D --> G{有 --server?|H}
    H -->|是| I[使用 --server 值]
    H -->|否| J[报错缺失服务器]
    E --> K[定位服务器]
    F --> L[定位工具]
    I --> K
    K --> M[执行调用]
    L --> M

选择器解析规则

资料来源：src/cli.ts:60-80

1. 点号分隔符：<server>.<tool> 格式直接解析
2. 服务器标志：--server <name> 或 --server=<name>
3. 工具标志：--tool <name> 或 --tool=<name>
4. URL 识别：包含 :// 的输入视为 HTTP 服务器定义

const separator = token.indexOf('.');
if (separator > 0) {
  return token.slice(0, separator); // 返回服务器名
}

自动补全建议

当用户输入的服务器或工具名称不存在时，系统会使用 chooseClosestIdentifier 函数提供最接近的候选建议：

function resolveConfiguredToolSelector(runtime, target: string | undefined) {
  if (!target || !target.includes('.')) {
    return undefined;
  }
  const definitions = runtime.getDefinitions();
  const match = definitions
    .map((definition) => definition.name)
    .filter((name) => target.startsWith(`${name}.`))
    .toSorted((a, b) => b.length - a.length)[0]; // 最长匹配优先
}

错误处理与诊断

常见错误类型

参数类型错误处理

当类型强制转换失败时，系统会保留原始字符串值并输出警告，而非直接报错。这允许某些工具接受灵活格式的输入。

资料来源：src/cli/call-command.ts:250-300

超时处理

所有涉及网络请求的操作都支持超时控制：

const tools = await withTimeout(
  loadToolMetadata(runtime, server, { includeSchema: true }), 
  timeoutMs
).catch(() => undefined);

调用流程完整图

sequenceDiagram
    participant User as 用户
    participant CLI as mcporter CLI
    participant Parser as 参数解析器
    participant Runtime as 运行时
    participant Server as MCP 服务器
    
    User->>CLI: mcporter call server.tool --arg=value
    CLI->>Parser: 解析参数表达式
    Parser->>Parser: 分离命名/位置参数
    Parser->>CLI: 返回解析结果
    CLI->>Runtime: 创建运行时实例
    Runtime->>Server: 连接 MCP 服务器
    Server-->>Runtime: 返回工具列表
    CLI->>Parser: 获取 schema 信息
    Parser-->>CLI: 返回参数映射
    CLI->>CLI: 类型强制转换
    CLI->>Runtime: callTool(name, args)
    Runtime->>Server: 发送工具调用请求
    Server-->>Runtime: 返回调用结果
    Runtime-->>CLI: 返回 CallResult
    CLI->>CLI: 格式化输出结果
    CLI-->>User: 显示结果

高级用法

Raw Strings 模式

使用 --raw-strings 标志可以禁用所有自动类型转换，保持参数值为原始字符串形式：

mcporter call server.tool --raw-strings --count=42 --enabled=true

此模式下，所有值都将作为字符串传递，不会进行数值或布尔值转换。

禁用 Coerce 模式

--no-coerce 标志完全禁用类型强制，包括 key=value、key:value 和尾部位置参数的所有转换：

mcporter call server.tool --no-coerce --id=12345 --data='{"json":"value"}'

双破折号分隔符

使用 -- 可以停止标志解析，使后续参数保持字面形式：

mcporter call server.tool -- --some-value --another-value

命令行参数速查表

相关文档

• 配置文件参考 - mcporter.json 配置语法
• emit-ts 命令 - 生成 TypeScript 类型定义
• generate-cli 命令 - 生成独立 CLI 工具

核心概念

mcporter 在处理服务器名称、工具选择器和命令参数时，采用了多层次的启发式策略。这些策略协同工作，形成了从输入解析到错误恢复的完整链路。

模糊匹配算法

当用户输入的服务器名称与配置中的实际名称不完全匹配时，mcporter 使用基于字符串相似度的算法进行自动更正。该算法不仅考虑精确匹配，还评估字符串之间的距离和公共子序列。资料来源：src/cli/identifier-helpers.ts

// 伪代码示例：chooseClosestIdentifier 的匹配逻辑
function chooseClosestIdentifier(attempted: string, candidates: string[]): string | undefined {
  // 计算编辑距离并选择最接近的候选者
  // 优先处理前缀匹配，然后考虑编辑距离
}

选择器解析规则

mcporter 支持 server.tool 格式的工具选择器，通过分层解析策略确保准确识别目标服务器和工具。解析器首先尝试完整匹配，然后降级为服务器名称前缀匹配，最后进行模糊校正。资料来源：src/cli/list-command.ts:35-52

系统架构

graph TD
    A[用户输入命令] --> B[输入标准化]
    B --> C{选择器格式检测}
    C -->|包含 "."| D[server.tool 解析]
    C -->|纯文本| E[服务器名称解析]
    D --> F{精确匹配?}
    E --> G{精确匹配?}
    F -->|否| H[前缀匹配扫描]
    G -->|否| I[模糊匹配搜索]
    H --> J{唯一匹配?}
    I --> K[返回最佳候选]
    J -->|是| K
    J -->|否| L[输出歧义提示]
    K --> M[执行命令]
    L --> N[显示建议列表]

核心组件

1. 服务器定义解析器

服务器定义解析器负责将用户提供的目标字符串映射到配置中的实际服务器定义。该组件支持多种输入格式，包括纯服务器名称、带选择器的复合名称、以及 HTTP URL。资料来源：src/cli/list-command.ts:35-52

2. 工具元数据加载器

工具元数据加载器负责获取指定服务器的工具列表，并在存在请求的工具时进行过滤。该组件通过 MCP 协议的 tools/list 方法获取服务器提供的所有工具及其输入模式。资料来源：src/cli/list-command.ts:54-71

// 工具元数据过滤逻辑
function filterToolMetadata(entries: ToolMetadata[], requestedTool: string | undefined): ToolMetadata[] {
  if (!requestedTool) {
    return entries;
  }
  return entries.filter((entry) => entry.tool.name === requestedTool);
}

3. 错误分类器

错误分类器对 MCP 服务器连接失败的情况进行系统化分类，并为每种错误类型提供诊断建议和可能的修复命令。该分类器区分认证错误、网络错误、协议错误和超时情况。资料来源：src/cli/list-format.ts:15-24

const timeoutSeconds = Math.round(timeoutMs / 1000);
const advice = classifyListError(result.error, result.server.name, timeoutSeconds);
return {
  line: `${prefix} (${advice.colored}, ${durationLabel})${sourceSuffix}`,
  summary: advice.summary,
  category: advice.category,
  authCommand: advice.authCommand,
  issue: advice.issue,
};

调用流程详解

标准调用路径

1. 参数接收：mcporter CLI 接收 mcporter call <target> 形式的命令
2. 选择器解析：检测是否包含 . 分隔符，提取服务器和工具名称
3. 定义解析：调用 resolveServerDefinition 获取服务器定义
4. 元数据加载：获取工具列表并验证请求的工具是否存在
5. 参数准备：处理命名参数和位置参数的混合输入
6. 工具调用：通过 MCP 运行时执行实际的工具调用

资料来源：src/cli/call-command.ts:1-50

位置参数推断

当用户使用位置参数而非命名参数时，mcporter 会动态查询工具的输入模式来确定参数顺序。这种设计允许用户使用 mcporter call server tool arg1 arg2 的简洁格式，而无需手动指定参数名称。资料来源：src/cli/call-command.ts:18-48

// 从工具模式推断位置参数映射
const tools = await loadToolMetadata(runtime, server, { includeSchema: true });
const toolInfo = tools.find((entry) => entry.tool.name === tool);
const remaining = options.filter((option) => !(option.property in namedArgs));

// 验证位置参数数量不超限
if (positionalArgs.length > remaining.length) {
  throw new Error(`Too many positional arguments supplied...`);
}

临时服务器管理

对于通过命令行直接定义的临时服务器（adhoc server），mcporter 提供特殊的管理机制。临时服务器使用特殊的生命周期配置，并在命令执行完毕后自动清理。资料来源：src/cli/adhoc-server.ts:50-62

function serializeLifecycle(lifecycle: ReturnType<typeof resolveLifecycle>): string | { mode: 'keep-alive'; idleTimeoutMs?: number } | undefined {
  if (!lifecycle) {
    return undefined;
  }
  if (lifecycle.mode === 'keep-alive' && lifecycle.idleTimeoutMs === undefined) {
    return 'keep-alive';
  }
  if (lifecycle.mode === 'keep-alive') {
    return { mode: 'keep-alive', idleTimeoutMs: lifecycle.idleTimeoutMs };
  }
  return 'ephemeral';
}

自动更正机制

拼写校正示例

mcporter 的模糊匹配功能能够智能处理常见的拼写错误：

校正发生时，mcporter 会在输出中显示暗淡处理的提示信息，告知用户进行了自动更正，同时执行用户的实际意图。资料来源：src/cli/server-lookup.ts

歧义检测与建议

当用户输入存在多种可能的匹配时，mcporter 不会盲目选择一个，而是输出清晰的歧义提示：

mcporter: ambiguous server 'db'. Did you mean one of: [db-mysql, db-postgres, db-sqlite]?

这种设计确保用户始终了解系统的行为，避免因自动选择导致的意外后果。

配置与使用

启用自动更正

自动更正在 mcporter 的 list、call、config 等主要命令中默认启用。用户可以通过配置或命令行参数调整匹配算法的敏感度。

匹配范围控制

错误处理

缺失工具的诊断

当用户请求的工具在服务器上不存在时，mcporter 提供友好的错误消息，列出该服务器实际提供的工具列表。资料来源：src/cli/list-command.ts:72-79

function printMissingToolText(
  definition: ServerDefinition,
  tool: string,
  durationMs: number,
  transportSummary: string,
  sourcePath: string | undefined
): void {
  printSingleServerHeader(definition, 0, durationMs, transportSummary, sourcePath);
  console.warn(`  Tool '${tool}' not found on '${definition.name}'.`);
}

超时与重试策略

对于网络请求，mcporter 实现了可配置的超时机制。默认超时时间因服务器类型而异，HTTP 服务器通常使用较短的超时，而 stdio 服务器则使用更宽松的时间限制。资料来源：src/cli/list-format.ts:12-14

const timeoutSeconds = Math.round(timeoutMs / 1000);
const timeoutLabel = `${timeoutSeconds}s`;

性能考量

缓存策略

mcporter 对服务器元数据和认证状态实施智能缓存，以减少重复连接的开销。缓存策略考虑以下因素：

• 服务器的连接稳定性
• 上次成功连接的时间戳
• 配置文件的修改时间

并行检查优化

在批量检查多个服务器状态时，mcporter 使用并行连接策略，同时对多个服务器发起探测请求，显著减少总体检查时间。资料来源：src/cli/list-command.ts:100-130

扩展与定制

自定义选择器解析器

开发者可以通过实现 resolveConfiguredToolSelector 接口来扩展选择器的解析逻辑，支持自定义的命名约定和别名系统。资料来源：src/cli/list-command.ts:35-52

错误分类插件

通过扩展 classifyListError 函数，可以添加针对特定 MCP 服务器的自定义错误处理和诊断建议。这种机制允许维护者提供针对特定服务（如 Docker、Kubernetes 等）的专业故障排除指导。

相关文档

• 配置管理文档 - 了解服务器配置的编写方式
• emit-ts 文档 - 生成类型化客户端工具
• Agent Skills 文档 - 为 AI 代理编写技能定义

配置架构概述

mcporter 采用分层配置架构，支持本地项目配置、全局用户配置和系统级配置的组合使用。

graph TD
    A[CLI 参数] --> B[环境变量<br/>MCPORTER_CONFIG]
    B --> C[项目配置<br/>config/mcporter.json]
    C --> D[XDG 配置<br/>$XDG_CONFIG_HOME/mcporter/mcporter.json]
    D --> E[默认配置<br/>~/.mcporter/mcporter.json]
    
    F[MCP Servers 定义] --> C
    G[导入配置<br/>Cursor/Claude/Windsurf] --> C
    H[OAuth Vault 存储] -.-> D

配置加载按优先级从高到低依次为：

1. CLI 参数：--config <path> 或 --root <dir>
2. 环境变量：MCPORTER_CONFIG
3. 项目配置：<root>/config/mcporter.json
4. XDG 配置：$XDG_CONFIG_HOME/mcporter/mcporter.json
5. 默认配置：~/.mcporter/mcporter.json

资料来源：README.md

配置文件格式

mcporter 支持 JSONC 格式的配置文件，允许使用行内注释和尾随逗号。

{
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "$env:CONTEXT7_API_KEY"
      }
    },
    "chrome-devtools": {
      // 内联注释
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

资料来源：README.md

服务器定义结构

资料来源：src/config.ts

路径发现机制

配置路径发现遵循标准化的优先级规则，支持显式覆盖和 XDG 标准。

graph LR
    A[Config CLI] --> B{存在 --config?}
    B -->|是| C[使用指定路径]
    B -->|否| D{存在环境变量?}
    D -->|MCPORTER_CONFIG| E[使用环境变量路径]
    D -->|否| F{项目配置存在?}
    F -->|是| G[config/mcporter.json]
    F -->|否| H{XDG_CONFIG_HOME?}
    H -->|是| I[$XDG_CONFIG_HOME/mcporter/mcporter.json]
    H -->|否| J[~/.mcporter/mcporter.json]

路径发现逻辑实现于 src/config/path-discovery.ts，支持以下环境变量：

资料来源：README.md

工具过滤配置

服务器定义支持细粒度的工具访问控制，通过 allowedTools 和 blockedTools 实现白名单和黑名单机制。

{
  "mcpServers": {
    "slack-readonly": {
      "baseUrl": "https://example.com/slack/mcp",
      "allowedTools": ["channels_list", "conversations_history"]
    },
    "devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp"],
      "blockedTools": ["screenshot_fullpage", "performance_metrics"]
    }
  }
}

过滤机制在列表查询和工具调用时均生效，确保只有授权的工具可被访问。

资料来源：README.md

配置管理命令

mcporter config 提供交互式配置管理功能，支持列表、查询、添加、删除和导入操作。

子命令概览

资料来源：src/cli/config-command.ts

添加服务器配置

# 基本 stdio 服务器
mcporter config add myserver npx -y my-mcp-server

# HTTP 服务器
mcporter config add context7 https://mcp.context7.com/mcp

# 带 OAuth 认证
mcporter config add github --auth oauth --oauth-client-id $CLIENT_ID

# 带环境变量
mcporter config add api --env OPENAI_API_KEY=$OPENAI_API_KEY

支持的添加参数：

资料来源：src/cli/config/help.ts

配置导入系统

mcporter 支持从主流编辑器的配置中导入 MCP 服务器定义，实现配置迁移。

支持的导入源

# 列出可导入的服务器
mcporter config import cursor --list

# 交互式导入
mcporter config import cursor

# 直接复制到本地配置
mcporter config import cursor --copy

导入过程会处理多种配置格式，包括 mcpServers、servers 和 mcp 容器结构。

资料来源：src/config/imports/external.ts

导入安全规则

不同来源的导入有不同的安全限制：

{
  allowMcpServers: true,    // 标准 mcpServers 容器
  allowServers: true,        // servers 容器
  allowMcp: true,            // mcp 容器
  allowRootFallback: boolean // 是否允许根目录回退
}

Claude Code 配置有特殊处理，仅在 .claude.json 或 .claude/mcp.json 路径下允许根目录回退。

资料来源：src/config/imports/external.ts

模糊匹配与自动纠正

mcporter 在配置管理中内置了智能模糊匹配机制，支持输入纠错和歧义提示。

# 拼写错误自动纠正
mcporter config get sshadcn
# 输出: sshadcn → shadcn (已纠正)

# 歧义时提示选择
mcporter config get linear
# 输出: "Did you mean linear-api or linear-tools?"

匹配逻辑实现于 src/cli/list-command.ts，使用最长前缀匹配策略：

const match = definitions
  .map((definition) => definition.name)
  .filter((name) => target.startsWith(`${name}.`))
  .toSorted((a, b) => b.length - a.length)[0];

资料来源：src/cli/list-command.ts

配置输出格式化

mcporter list 命令以表格形式展示配置，支持文本和 JSON 两种输出格式。

状态分类

Error with Openai API: output new_sensitive (1027)

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

Pitfall Log / 踩坑日志

项目：steipete/mcporter

摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)。

1. 安全/权限坑 · 来源证据：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth callback server not reachable when run via process managers that use process groups (e.g. OpenClaw exec)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_31a16607bb834bd0923ee11f793cb841 | https://github.com/openclaw/mcporter/issues/177 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Residual structuredContent regression in 0.10.2: memory-* servers fail at position 164
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4d2546b7ce5f4d1380944bbe50fd8589 | https://github.com/openclaw/mcporter/issues/168 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | host_targets=mcp_host, claude, claude_code, cursor

4. 配置坑 · 来源证据：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8ca5737a0b664b86824d31b306936dc1 | https://github.com/openclaw/mcporter/issues/160 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：`daemonIdleTimeoutMs` missing?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：daemonIdleTimeoutMs missing?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c6f31e6244584baa9dac3842902ac8c5 | https://github.com/openclaw/mcporter/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | README/documentation is current enough for a first validation pass.

7. 运行坑 · 社区讨论暴露的待验证问题：why bothering with MCPs if I can call almost anything via CLI? - Reddit

• 严重度：medium
• 证据强度：source_linked
• 发现：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 ...
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：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

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | last_activity_observed missing

9. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | no_demo; severity=medium

11. 安全/权限坑 · 来源证据：Add `mcporter vault set <server>` to seed credentials non-interactively

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add mcporter vault set <server> to seed credentials non-interactively
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b63d0f3f42e046488953064089bf8025 | https://github.com/openclaw/mcporter/issues/156 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：Add a flag to suppress browser launch in `auth` / `config login` for headless workflows

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add a flag to suppress browser launch in auth / config login for headless workflows
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2d76f84533e8406d965b1762634996dd | https://github.com/openclaw/mcporter/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：MCPorter not using OAuth credentials

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCPorter not using OAuth credentials
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2705d784929e4996bcb34f3a71543ed7 | https://github.com/openclaw/mcporter/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Node.js 25 fetch() (undici) gets 403 from Sunsama MCP endpoint — HTTP/2 incompatibility with Google Frontend
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_78f73e8e0c9d4cca9e886fa2d89ef296 | https://github.com/openclaw/mcporter/issues/158 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocat…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Serialize concurrent file writes — credentials.json, mcporter.json, OAuth persistence files race under parallel invocations
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9439129321d048dabb2ad6f14b4ab11e | https://github.com/openclaw/mcporter/issues/167 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：Support refreshable bearer token auth for stdio MCP servers

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support refreshable bearer token auth for stdio MCP servers
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_88f8026283fc46309d02fbb7f6a3186f | https://github.com/openclaw/mcporter/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：generate-cli produces non-deterministic bundles: tmp paths and schema key order leak into artifact
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b1aff56feb584e23ac8b345ddc61934f | https://github.com/openclaw/mcporter/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：list reports auth required on expired access_token even when refresh_token is valid

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：list reports auth required on expired access_token even when refresh_token is valid
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dcd9da058a8b48df94395fee1f995805 | https://github.com/openclaw/mcporter/issues/166 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_dff4c80f0d4d4ac1a1ab1697d13faf8d | https://github.com/steipete/mcporter#readme | release_recency=unknown