# https://github.com/steipete/mcporter 项目说明书
生成时间：2026-05-18 21:37:46 UTC
## 目录
- [项目概述](#page-project-overview)
- [安装指南](#page-installation-guide)
- [快速入门](#page-quick-start)
- [核心架构](#page-core-architecture)
- [运行时系统](#page-runtime-system)
- [传输层](#page-transport-layer)
- [CLI 命令参考](#page-cli-reference)
- [工具调用语法](#page-call-syntax)
- [调用启发式与自动更正](#page-call-heuristic)
- [配置管理](#page-configuration)
## 项目概述
### 相关页面
相关主题：[核心架构](#page-core-architecture), [快速入门](#page-quick-start), [安装指南](#page-installation-guide)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)
- [src/index.ts](https://github.com/steipete/mcporter/blob/main/src/index.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)
- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)
- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)
# 项目概述
mcporter 是一个命令行工具，用于统一管理和调用 MCP（Model Context Protocol）服务器。它提供了配置管理、服务器调用、工具生成等核心功能，帮助开发者更高效地集成和操作 MCP 服务。
## 核心定位
mcporter 的设计目标是为 MCP 服务器提供统一的入口层：
- **配置管理**：集中管理多个 MCP 服务器配置
- **工具调用**：通过 CLI 直接调用 MCP 工具
- **类型生成**：自动生成 TypeScript 类型定义和客户端代码
- **跨编辑器兼容**：支持导入/导出 Cursor、Claude、VS Code 等编辑器的 MCP 配置
资料来源：[README.md:1-15]()
## 核心命令
mcporter 提供了以下主要命令：
| 命令 | 功能 | 典型用法 |
|------|------|----------|
| `config` | 管理 MCP 配置 | `mcporter config list`、`mcporter config add` |
| `list` | 列出可用工具 | `mcporter list ` |
| `call` | 调用 MCP 工具 | `mcporter call .` |
| `generate-cli` | 生成独立 CLI | `mcporter generate-cli --command ` |
| `emit-ts` | 生成 TypeScript 类型 | `mcporter emit-ts --out types/` |
资料来源：[README.md:60-85]()
## 系统架构
```mermaid
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[配置文件
mcporter.json]
D --> J[外部导入
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（支持注释和尾随逗号）：
```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 配置：
| 来源 | 支持的容器 |
|------|-----------|
| Cursor | `mcpServers`、`servers`、`mcp` |
| Claude Code | `mcpServers`、`servers`、`mcp` |
| VS Code | `mcpServers`、`servers`、`mcp` |
| Windsurf | `mcpServers`、`servers`、`mcp` |
资料来源：[README.md:35-40]()
配置导入时支持模糊匹配和自动纠错，例如输入 `sshadcn` 会自动纠正为 `shadcn`。
资料来源：[README.md:45-47]()
## 运行时引擎
运行时引擎是 mcporter 的核心，负责与 MCP 服务器建立连接并执行调用：
```mermaid
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]()
### 传输类型支持
| 传输类型 | 说明 | 配置字段 |
|----------|------|----------|
| HTTP | 基于 HTTP 的请求-响应模式 | `baseUrl` |
| SSE | Server-Sent Events 模式 | `baseUrl` + `sse` |
| STDIO | 标准输入输出通信 | `command` + `args` |
资料来源：[src/cli/config/help.ts:5-10]()
## 生命周期管理
mcporter 支持两种服务器生命周期模式：
```mermaid
graph LR
A[生命周期] --> B[keep-alive]
A --> C[ephemeral]
B --> D{空闲超时}
D -->|无超时| E[持续运行]
D -->|设置超时| F[idleTimeoutMs]
C --> G[调用后立即关闭]
```
| 模式 | 说明 | 配置值 |
|------|------|--------|
| `keep-alive` | 服务器持续运行，可复用连接 | `"keep-alive"` 或 `{ mode: "keep-alive", idleTimeoutMs: number }` |
| `ephemeral` | 每次调用后关闭服务器 | `"ephemeral"` |
资料来源：[src/lifecycle.ts:25-40]()
## 工具调用与结果处理
### 调用语法
```bash
mcporter call . [key=value ...] [--tool-arg ]
```
mcporter 支持多种参数格式：
- `key=value` 形式
- `key:value` 形式
- 尾随位置参数
- `--tool-arg` JSON 格式
资料来源：[README.md:70-80]()
### 结果类型
调用结果包装在 `CallResult` 对象中，提供多种访问方式：
| 方法 | 返回类型 | 说明 |
|------|----------|------|
| `.text()` | `string \| null` | 获取文本内容 |
| `.markdown()` | `string \| null` | 获取 Markdown 内容 |
| `.json()` | `unknown` | 获取 JSON 数据 |
| `.images()` | `ImageContent[] \| null` | 获取图片内容 |
| `.content()` | `string[]` | 获取所有文本内容 |
| `.raw` | `CallResultEnvelope` | 获取原始响应 |
资料来源：[README.md:110-120]()
### 资源收集逻辑
```mermaid
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
```bash
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 类型
```bash
# 仅生成类型定义
npx mcporter emit-ts linear --out types/linear-tools.d.ts
# 生成客户端包装器
npx mcporter emit-ts linear --mode client --out clients/linear.ts
```
| 模式 | 输出内容 |
|------|----------|
| `types`（默认） | `.d.ts` 接口定义 |
| `client` | `.d.ts` + `.ts` 客户端包装 |
资料来源：[README.md:125-140]()
## 命令行选项参考
### 全局选项
| 选项 | 说明 | 环境变量 |
|------|------|----------|
| `--config ` | 自定义配置文件路径 | `MCPORTER_CONFIG` |
| `--root ` | 工作目录（用于 stdio 命令） | `MCPORTER_ROOT` |
| `--log-level ` | 日志级别 | `MCPORTER_LOG_LEVEL` |
| `--oauth-timeout ` | OAuth 等待超时 | `MCPORTER_OAUTH_TIMEOUT_MS` |
| `--tail-log` | 尾随日志输出 | - |
资料来源：[README.md:55-65]()
### list 命令选项
| 选项 | 说明 |
|------|------|
| `--all-parameters` | 显示所有可选参数 |
| `--schema` | 显示 JSON Schema |
| `--brief` | 简洁输出 |
| `--json` | JSON 格式输出 |
| `--timeout ` | 连接超时 |
资料来源：[src/cli/list-command.ts:80-100]()
### call 命令选项
| 选项 | 说明 |
|------|------|
| `--raw-strings` | 保持数值型参数为字符串 |
| `--no-coerce` | 禁用类型转换 |
| `--save-images ` | 保存图片到目录 |
| `--raw` | 原始输出格式 |
| `--` | 停止标志解析 |
资料来源：[README.md:75-80]()
## 错误处理与诊断
### 状态分类
| 状态 | 说明 | 颜色标识 |
|------|------|----------|
| `ok` | 调用成功 | 绿色 |
| `auth` | 认证失败 | 黄色 |
| `offline` | 服务器离线 | 灰色 |
| `http` | HTTP 错误 | 橙色 |
| `error` | 一般错误 | 红色 |
资料来源：[src/cli/list-format.ts:10-25]()
### 诊断命令
```bash
# 查看服务器状态摘要
mcporter list --json
# 尾随相关日志
mcporter call . --tail-log
```
## 技术栈
| 组件 | 技术 | 用途 |
|------|------|------|
| CLI 框架 | TypeScript | 类型安全 |
| 传输层 | Bun/Node.js | HTTP/SSE/STDIO |
| 配置解析 | JSONC | 支持注释的 JSON |
| 代码打包 | Rolldown/Bun | 生成可执行 CLI |
资料来源：[README.md:100-105]()
## 总结
mcporter 作为一个 MCP 统一管理工具，提供了从配置管理到工具调用、再到代码生成的完整工具链。它的设计强调：
1. **统一性**：多种 MCP 服务器的集中管理
2. **兼容性**：支持多种编辑器和工具的配置导入
3. **开发者体验**：模糊匹配、自动纠错、类型生成
4. **灵活性**：多种传输协议和生命周期管理
通过 mcporter，开发者可以快速集成 MCP 服务器到自己的工作流程中，无需关心底层协议细节。
---
## 安装指南
### 相关页面
相关主题：[快速入门](#page-quick-start), [项目概述](#page-project-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)
- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)
- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)
- [docs/emit-ts.md](https://github.com/steipete/mcporter/blob/main/docs/emit-ts.md)
# 安装指南
mcporter 是一个 MCP（Model Context Protocol）服务器启动器和客户端工具，用于连接和管理各种 MCP 服务器。本指南详细介绍 mcporter 的多种安装方式、项目配置以及进阶用法。
## 环境要求
### 运行时依赖
| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Node.js | 18.0+ | 支持 ES Modules 和原生 HTTP 客户端 |
| pnpm | 推荐使用 | 项目首选包管理器 |
| npm | 兼容 | 可作为替代方案 |
| Homebrew | 最新版 | macOS/Linux 用户可选 |
### 系统要求
- macOS、Linux 或 Windows（通过 WSL 或 Git Bash）
- 网络连接（用于访问远程 MCP 服务器）
- OAuth 认证需要浏览器环境
## 安装方式
### 通过 pnpm 安装（推荐）
将 mcporter 添加为项目依赖：
```bash
pnpm add mcporter
```
这种方式适合在项目内部使用 mcporter API，或者通过 `pnpm exec mcporter` 调用。资料来源：[README.md]()
### 通过 npm 全局安装
```bash
npm install -g mcporter
```
安装后可在任意目录直接使用 `mcporter` 命令。资料来源：[README.md]()
### 通过 Homebrew 安装（macOS/Linux）
```bash
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`（用户级别）
### 配置命令
| 命令 | 功能 |
|------|------|
| `mcporter config list` | 列出所有本地 MCP 服务器配置 |
| `mcporter config get ` | 获取指定服务器的配置详情 |
| `mcporter config add` | 交互式添加新服务器 |
| `mcporter config remove ` | 删除服务器配置 |
| `mcporter config import ` | 从编辑器（Cursor/Claude）导入配置 |
资料来源：[README.md]()
### 配置文件格式
mcporter 使用 JSONC 格式，支持注释和尾随逗号：
```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"]
}
}
}
```
## 命令行用法
### 常用命令
| 命令 | 说明 |
|------|------|
| `mcporter list` | 列出所有已配置的 MCP 服务器及其工具 |
| `mcporter call .` | 调用指定服务器的指定工具 |
| `mcporter generate-cli` | 从 MCP 服务器生成独立的 CLI |
| `mcporter emit-ts` | 生成 TypeScript 类型定义 |
| `mcporter inspect-cli` | 检查已生成的 CLI 元数据 |
### 全局选项
| 选项 | 说明 |
|------|------|
| `--config ` | 指定配置文件路径（默认 `./config/mcporter.json`） |
| `--root ` | 设置 stdio 命令的工作目录 |
| `--log-level ` | 日志级别：`debug`、`info`、`warn`、`error` |
| `--oauth-timeout ` | OAuth 浏览器等待超时 |
| `--output ` | 输出格式：`json` 或美化输出 |
资料来源：[README.md](), [src/cli/config/help.ts]()
## 编程接口
### One-shot 调用
适合单次执行任务的场景：
```typescript
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
适合需要多次调用或高级配置的场景：
```typescript
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();
```
### 生成类型化客户端
#### 仅生成类型定义
```bash
npx mcporter emit-ts linear --out types/linear-tools.d.ts
```
#### 生成客户端包装器
```bash
npx mcporter emit-ts linear --mode client --out clients/linear.ts
```
可用选项：
| 选项 | 说明 |
|------|------|
| `--mode types` | 仅生成 `.d.ts` 接口（默认） |
| `--mode client` | 生成 `.d.ts` 和 `.ts` 包装器 |
| `--include-optional` | 展开所有可选字段 |
| `--json` | 输出结构化摘要（用于脚本） |
资料来源：[README.md](), [docs/emit-ts.md]()
## OAuth 认证配置
### OAuth 选项
| 选项 | 说明 |
|------|------|
| `--oauth-client-id ` | 使用预注册的 OAuth 客户端 ID |
| `--oauth-client-secret-env ` | 从环境变量读取客户端密钥 |
| `--oauth-redirect-url ` | 设置自定义重定向 URL |
| `--token-cache-dir ` | 覆盖 OAuth 令牌持久化位置 |
### 清除认证
```bash
mcporter config logout
```
资料来源：[README.md](), [src/cli/config/help.ts]()
## 生命周期管理
mcporter 支持两种服务器生命周期模式：
| 模式 | 说明 |
|------|------|
| `ephemeral` | 每次调用后自动终止服务器（默认） |
| `keep-alive` | 保持服务器运行，复用连接 |
可通过配置文件或命令行设置：
```json
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "example-server"],
"lifecycle": "keep-alive"
}
}
}
```
资料来源：[src/lifecycle.ts]()
## 工具列表与调用
### 列出服务器工具
```bash
# 列出所有服务器的工具
mcporter list
# 列出单个服务器的详细工具信息
mcporter list context7
# 输出 JSON 格式
mcporter list --json
```
### 调用工具
```bash
# 基本调用
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` 值
2. **OAuth 认证失败**
- 确认浏览器可以打开重定向 URL
- 检查 `--oauth-redirect-url` 配置
- 清除旧的认证：`mcporter config logout `
3. **配置找不到**
- 使用 `--config ` 指定配置文件
- 使用 `mcporter config list` 查看已加载的配置
### 日志调试
```bash
mcporter list --log-level debug --tail-log
```
`--tail-log` 选项会流式输出相关日志文件的最后 20 行。资料来源：[README.md]()
---
## 快速入门
### 相关页面
相关主题：[CLI 命令参考](#page-cli-reference), [工具调用语法](#page-call-syntax), [配置管理](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)
- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)
- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)
- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)
# 快速入门
mcporter 是一个强大的 MCP（Model Context Protocol）客户端工具，提供命令行界面来管理、调用和调试 MCP 服务器。本指南将帮助您快速掌握 mcporter 的核心功能，从安装配置到日常使用。
## 安装与基础配置
### 安装方式
mcporter 支持多种包管理器安装方式，开发者可根据项目环境选择最适合的方案：
| 包管理器 | 安装命令 |
|---------|---------|
| pnpm | `pnpm add -g mcporter` |
| npm | `npm install -g mcporter` |
| npx | `npx mcporter` |
资料来源：[README.md:1-15]()
### 配置文件位置
mcporter 默认使用 `./config/mcporter.json` 作为配置文件，同时也支持 JSONC 格式，允许使用 `//` 和 `/* ... */` 注释以及尾随逗号。
```jsonc
{
"mcpServers": {
"context7": {
"description": "Context7 docs MCP",
"baseUrl": "https://mcp.context7.com/mcp",
"headers": {
"Authorization": "$env:CONTEXT7_API_KEY",
}
}
}
}
```
资料来源：[README.md:45-60]()
### 常用命令行参数
| 参数 | 说明 | 默认值 |
|-----|------|-------|
| `--config ` | 指定配置文件路径 | `./config/mcporter.json` |
| `--root ` | 设置 stdio 命令的工作目录 | 当前目录 |
| `--log-level ` | 日志级别（debug/info/warn/error） | 参考 `MCPORTER_LOG_LEVEL` |
| `--oauth-timeout ` | OAuth 浏览器等待超时 | 参考 `MCPORTER_OAUTH_TIMEOUT_MS` |
| `--output ` | 输出格式控制 | 自动检测 |
| `--raw` | 原始输出，不进行格式化 | - |
资料来源：[README.md:20-35]()
## 列出可用服务器与工具
### 基础列表命令
使用 `mcporter list` 命令查看所有已配置的 MCP 服务器及其状态：
```bash
mcporter list
```
该命令会检查每个服务器的可访问性，并显示工具数量、连接耗时和状态信息。状态分类包括：
| 状态类别 | 说明 | 颜色标识 |
|---------|------|---------|
| `ok` | 服务器正常响应 | 绿色 |
| `auth` | 需要认证 | 黄色 |
| `offline` | 服务器离线 | 灰色 |
| `http` | HTTP 错误 | 蓝色 |
| `error` | 连接错误 | 红色 |
资料来源：[src/cli/list-format.ts:1-30]()
### 查看特定服务器的工具
当您指定服务器名称时，mcporter 会显示该服务器的所有可用工具及其详细签名：
```bash
mcporter list
mcporter list context7
```
工具详情包括：
- **工具名称**：MCP 服务器暴露的函数名
- **输入模式（Input Schema）**：参数定义，包含类型和约束
- **描述信息**：工具功能说明
- **示例调用**：常用参数组合示例
资料来源：[src/cli/list-command.ts:1-50]()
### 过滤工具输出
| 过滤选项 | 说明 |
|---------|------|
| `--brief` | 仅显示简要签名 |
| `--signatures` | 显示紧凑签名 |
| `--required-only` | 仅显示必需参数 |
| `--all-parameters` | 显示所有参数（包括可选） |
| `--schema` | 显示完整 JSON Schema |
```bash
# 简要输出
mcporter list context7 --brief
# 显示所有参数
mcporter list context7 --all-parameters
# 指定特定工具
mcporter list context7.shadcn_getComponents
```
资料来源：[src/cli/list-command.ts:50-100]()
## 调用 MCP 工具
### 基础调用语法
使用 `mcporter call` 命令调用服务器上的工具：
```bash
mcporter call . [参数...]
mcporter call context7.resolve-library library_name="shadcn"
```
mcporter 会自动处理：
- 参数类型转换（布尔值、数字、JSON）
- 必需参数验证
- 位置参数到命名参数的映射
资料来源：[src/cli/call-command.ts:1-40]()
### 参数传递方式
#### 命名参数
```bash
# 使用 key=value 格式
mcporter call server.tool arg1=value1 arg2=value2
# 使用 key:value 格式
mcporter call server.tool arg1:value1 arg2:value2
```
#### 位置参数
当工具参数按声明顺序传递时，mcporter 会根据工具的输入模式自动匹配：
```bash
mcporter call context7.resolve-library shadcn
```
如果位置参数数量超过剩余必需参数数量，命令会报错并提示正确的参数数量。
资料来源：[src/cli/call-command.ts:40-80]()
### 参数类型处理
mcporter 支持智能类型推断：
| 输入格式 | 推断类型 | 示例 |
|---------|---------|------|
| `true` / `false` | 布尔值 | `enabled=true` |
| `123` / `3.14` | 数字 | `count=42` |
| `"text"` 或 `'text'` | 字符串 | `name="test"` |
| `{...}` / `[...]` | JSON 对象/数组 | `config={"key":1}` |
| 不符合以上格式 | 字符串 | `text=abc` |
使用 `--no-coerce` 可禁用类型推断，保持所有值为原始字符串。
```bash
# 禁用类型转换
mcporter call server.tool --no-coerce arg1=value1
```
资料来源：[src/cli/call-command.ts:80-120]()
### 处理工具输出
`mcporter call` 返回的结果封装在 `CallResult` 对象中，支持多种访问方式：
| 方法 | 说明 | 返回类型 |
|-----|------|---------|
| `.text()` | 获取纯文本内容 | `string \| null` |
| `.markdown()` | 获取 Markdown 内容 | `string \| null` |
| `.json()` | 解析 JSON 内容 | `object \| null` |
| `.images()` | 获取图片内容 | `ImageContent[] \| null` |
| `.content()` | 获取原始内容项 | `ContentBlock[]` |
| `.raw` | 获取完整响应信封 | `CallResponse` |
```bash
# 格式化输出（默认）
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` 参数可以将其保存到指定目录：
```bash
mcporter call server.tool --save-images ./output_dir arg1=value1
```
图片会按工具响应中的顺序编号保存，输出形状保持不变。
资料来源：[README.md:30-35]()
## 服务器生命周期管理
mcporter 支持不同的服务器生命周期模式，决定工具调用后服务器的运行行为：
| 生命周期模式 | 说明 | 配置方式 |
|------------|------|---------|
| `ephemeral` | 调用后立即关闭（默认） | `lifecycle: "ephemeral"` |
| `keep-alive` | 保持运行状态 | `lifecycle: "keep-alive"` |
| `keep-alive` + `idleTimeoutMs` | 空闲超时后关闭 | `lifecycle: { mode: "keep-alive", idleTimeoutMs: 60000 }` |
```jsonc
{
"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` 子命令进行配置管理：
| 子命令 | 说明 |
|-------|------|
| `config list` | 列出本地配置 |
| `config get ` | 获取配置项详情 |
| `config add ` | 添加新配置 |
| `config remove ` | 删除配置 |
| `config import ` | 导入其他编辑器的配置 |
| `config logout ` | 清除认证信息 |
```bash
# 查看所有配置
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 使用模糊匹配来查找服务器名称，即使输入有拼写错误也能找到正确的配置：
```bash
# 错误拼写会自动纠正
mcporter list sshadcn
# 输出: sshadcn → shadcn (自动纠正提示)
# 服务器选择器支持 .tool 语法
mcporter list context7.resolve-library
```
资料来源：[src/cli/list-command.ts:100-150]()
### 多环境配置
支持使用 `--config` 和 `--root` 参数切换不同的配置环境：
```bash
# 使用项目级配置
mcporter list --config ./project/config/mcporter.json
# 设置工作目录
mcporter call server.tool --root /path/to/project arg1=value1
```
## 生成工具客户端
### 生成 TypeScript 类型定义
使用 `emit-ts` 命令生成强类型工具接口：
```bash
# 仅生成类型定义
npx mcporter emit-ts linear --out types/linear-tools.d.ts
# 生成带客户端包装器
npx mcporter emit-ts linear --mode client --out clients/linear.ts
```
| 模式 | 输出 | 说明 |
|-----|------|------|
| `types`（默认） | `.d.ts` | 仅包含 Promise 签名的接口 |
| `client` | `.d.ts` + `.ts` | 包含类型定义和 `createRuntime`/`createServerProxy` 包装器 |
附加选项：
- `--include-optional`：展开所有可选字段
- `--json`：输出结构化摘要而非纯文本
资料来源：[README.md:100-120]()
### 生成独立 CLI 工具
将 MCP 服务器转换为独立的可分发 CLI：
```bash
# 从 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）
```bash
# 检查已生成的 CLI
npx mcporter inspect-cli dist/context7.js
# 重新生成（使用嵌入的元数据）
npx mcporter generate-cli --from dist/context7.js
```
资料来源：[README.md:80-100]()
## 常见工作流程
### 流程图：基础调用流程
```mermaid
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[结束]
```
### 流程图：工具调用处理
```mermaid
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[返回给调用者]
```
### 典型使用场景
#### 场景一：快速查询文档
```bash
# 1. 列出可用服务器
mcporter list
# 2. 查看特定服务器工具
mcporter list context7
# 3. 调用文档查询工具
mcporter call context7.resolve-library library_name="shadcn"
```
#### 场景二：调试 MCP 服务器
```bash
# 使用 verbose 模式查看详细信息
mcporter list context7 --verbose
# 启用调试日志
mcporter list --log-level debug
# 查看日志尾随内容
mcporter call server.tool --tail-log
```
#### 场景三：自动化脚本集成
```bash
#!/bin/bash
# 批量调用脚本
SERVERS=("context7" "shadcn" "linear")
for server in "${SERVERS[@]}"; do
echo "检查服务器: $server"
mcporter list "$server" --json | jq -r '.status'
done
```
## 故障排除
### 常见问题与解决方案
| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 连接超时 | 服务器未启动或网络问题 | 检查 `--timeout` 设置，使用 `--tail-log` 查看日志 |
| 认证失败 | OAuth token 过期 | 运行 `mcporter config logout ` 后重新认证 |
| 工具未找到 | 名称拼写错误或服务器未启动 | 使用 `mcporter list` 确认工具存在 |
| 参数类型错误 | 字符串被错误解析为数字 | 使用 `--no-coerce` 或显式使用引号 |
### 调试模式
启用详细日志进行问题排查：
```bash
# 设置日志级别
export MCPORTER_LOG_LEVEL=debug
# 运行命令
mcporter call server.tool arg=value
# 或直接在命令中指定
mcporter call server.tool arg=value --log-level debug
```
使用 `--tail-log` 查看关联的日志文件：
```bash
mcporter call server.tool --tail-log
```
## 下一步
- 阅读 [配置参考文档](docs/config.md) 了解更多配置选项
- 查看 [Agent Skills 指南](docs/agent-skills.md) 了解如何为 AI Agent 创建技能
- 参考 [emit-ts 文档](docs/emit-ts.md) 生成强类型客户端
---
## 核心架构
### 相关页面
相关主题：[运行时系统](#page-runtime-system), [传输层](#page-transport-layer), [配置管理](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)
- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)
- [src/cli.ts](https://github.com/steipete/mcporter/blob/main/src/cli.ts)
- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)
# 核心架构
mcporter 是一个用于管理 MCP（Model Context Protocol）服务器的 CLI 工具，其核心架构围绕配置管理、运行时生命周期、CLI 命令解析和结果处理四大模块展开。
## 架构总览
mcporter 的设计采用了分层架构模式，核心组件包括：
| 层级 | 组件 | 职责 |
|------|------|------|
| CLI 层 | `src/cli.ts` | 命令行入口、参数解析、路由分发 |
| 命令层 | `src/cli/list-command.ts` | list/list-format/list-output 子系统 |
| 配置层 | `src/config/` | 配置读取、规范化、导入 |
| 运行时层 | `src/runtime.ts` | MCP 服务器生命周期管理 |
| 工具层 | `src/lifecycle.ts` | 服务端生命周期控制 |
## 配置管理模块
### 配置解析流程
配置管理模块负责加载和规范化用户配置。mcporter 支持多种配置格式，包括 `mcporter.json` 和 `mcporter.jsonc`（支持注释和尾随逗号的 JSON）。
### 配置导入机制
外部配置导入功能支持从多种编辑器配置中读取 MCP 服务器定义：
```typescript
// 支持的配置容器
{
allowMcpServers: true, // 标准 mcpServers
allowServers: true, // servers 容器
allowMcp: true, // mcp 容器
allowRootFallback: true // 根目录回退
}
```
资料来源：[src/config/imports/external.ts:15-25]()
对于 Claude Code 配置，有特殊的路径规范化逻辑：
```typescript
const allowRootFallback =
normalized.endsWith('.claude.json') ||
normalized.endsWith(`${path.sep}.claude${path.sep}mcp.json`);
```
资料来源：[src/config/imports/external.ts:11-14]()
### 配置值转换
配置导入模块提供了类型安全的数据转换工具：
| 函数 | 作用 |
|------|------|
| `asString()` | 提取非空字符串值 |
| `asStringRecord()` | 将混合类型对象转换为字符串记录 |
| `shouldIgnoreParseError()` | 判断是否应忽略解析错误 |
资料来源：[src/config/imports/external.ts:40-62]()
## 生命周期管理
### 生命周期模式
mcporter 支持两种服务端生命周期模式：
```mermaid
graph TD
A[MCP 服务器定义] --> B{生命周期模式}
B -->|keep-alive| C[持续运行]
B -->|ephemeral| D[按需启动]
C --> E[idleTimeoutMs 配置]
D --> F[调用后终止]
```
资料来源：[src/lifecycle.ts:45-50]()
生命周期序列化函数 `serializeLifecycle` 处理以下返回值格式：
```typescript
// 三种序列化形式
'keep-alive' // 无超时
{ mode: 'keep-alive', idleTimeoutMs?: number } // 带超时
'ephemeral' // 临时模式
```
资料来源：[src/cli/adhoc-server.ts:89-97]()
### 动态端口检测
对于 Chrome DevTools 相关的 MCP 服务器，mcporter 支持动态端口分配：
```typescript
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 内置了对常见持续运行命令的识别：
```typescript
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]()
### 覆盖集合解析
配置中的覆盖设置使用集合匹配机制：
```typescript
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, candidates: Set): boolean {
for (const candidate of candidates) {
if (names.has(candidate)) {
return true;
}
}
return false;
}
```
资料来源：[src/lifecycle.ts:35-62]()
## CLI 命令系统
### 命令路由
CLI 入口点 `src/cli.ts` 负责将命令行参数路由到相应的处理函数：
```mermaid
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` 格式的直接调用：
```typescript
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. 格式化传输层摘要
```typescript
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 使用标准化的状态分类系统：
```typescript
type StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';
export function createEmptyStatusCounts(): Record {
return {
ok: 0,
auth: 0,
offline: 0,
http: 0,
error: 0,
};
}
```
资料来源：[src/cli/list-output.ts:42-50]()
### 列表格式化
列表格式化模块负责生成用户友好的输出：
```typescript
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]()
### 工具元数据过滤
支持按工具名称过滤返回的元数据：
```typescript
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` 实现了复杂的内容解析逻辑：
```mermaid
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]
```
### 资源负载收集
```typescript
function collectResourcePayload(
resource: unknown,
textEntries: string[],
markdownEntries: string[],
jsonCandidates: unknown[]
): void {
if (!resource || typeof resource !== 'object') {
return;
}
const record = resource as Record;
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 数据：
```typescript
function unwrapJsonEnvelope(
record: Record,
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 服务器：
```mermaid
graph TD
A[--stdio 命令字符串] --> B[引号解析]
B --> C[命令+参数分离]
C --> D[生命周期决定]
D --> E[序列化配置]
E --> F[运行时注册]
```
### 命令字符串解析
实现了完整的 shell 风格引号解析：
```typescript
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 通过环境变量支持运行时行为控制：
| 环境变量 | 作用 | 默认值 |
|----------|------|--------|
| `MCPORTER_LOG_LEVEL` | 日志级别 | info |
| `MCPORTER_OAUTH_TIMEOUT_MS` | OAuth 超时 | 60000 |
| `MCPORTER_DISABLE_KEEPALIVE` | 禁用 keep-alive | - |
| `MCPORTER_NO_KEEPALIVE` | 同上（兼容） | - |
```typescript
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]()
## 数据流图
### 列表命令完整数据流
```mermaid
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: 控制台输出
```
### 结果处理流程
```mermaid
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()` 等工具函数避免类型错误
```typescript
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` 中定义新的生命周期处理
---
## 运行时系统
### 相关页面
相关主题：[核心架构](#page-core-architecture), [传输层](#page-transport-layer), [工具调用语法](#page-call-syntax)
相关源码文件
以下源码文件用于生成本页说明：
- [src/runtime.ts](https://github.com/steipete/mcporter/blob/main/src/runtime.ts)
- [src/runtime/utils.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/utils.ts)
- [src/runtime/errors.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/errors.ts)
- [src/server-proxy.ts](https://github.com/steipete/mcporter/blob/main/src/server-proxy.ts)
- [src/result-utils.ts](https://github.com/steipete/mcporter/blob/main/src/result-utils.ts)
# 运行时系统
## 概述
mcporter 的**运行时系统**是整个工具调用框架的核心子系统，负责 MCP 服务器的创建、管理、工具调用及生命周期控制。该系统封装了与 MCP 服务器的通信细节，提供统一的运行时抽象，使 CLI 命令能够以一致的方式与不同类型的 MCP 服务器交互。
运行时系统的主要职责包括：
- **服务器运行时创建与管理**：通过 `createRuntime` 工厂函数实例化服务器运行时
- **工具元数据加载**：获取 MCP 服务器提供的工具列表及参数模式
- **工具调用执行**：将工具调用请求路由到目标服务器并处理响应
- **生命周期管理**：支持 keep-alive 和 ephemeral 两种运行模式
- **结果解析与格式化**：从服务器响应中提取文本、图像、JSON 等内容
资料来源：[src/cli/list-command.ts:18-30]()
## 架构设计
### 核心组件关系
```mermaid
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
```
### 运行时创建流程
```mermaid
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 服务器的连接参数：
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | `string` | 服务器唯一标识名称 |
| `command` | `CommandSpec` | 启动命令配置（stdio/http/sse） |
| `description` | `string?` | 服务器描述文本 |
| `source` | `ServerSource` | 配置来源（本地/导入/HTTP） |
| `sources` | `readonly ServerSource[]?` | 多源配置 |
| `lifecycle` | `ServerLifecycle?` | 生命周期模式 |
| `auth` | `AuthConfig?` | 认证配置 |
资料来源：[src/server-proxy.ts]()
### ToolMetadata
工具元数据描述 MCP 服务器暴露的单个工具：
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | `string` | 工具名称 |
| `description` | `string` | 工具功能描述 |
| `inputSchema` | `JsonSchema` | 输入参数 JSON Schema |
| `outputSchema` | `JsonSchema?` | 输出结果 JSON Schema |
```typescript
interface ToolMetadata {
tool: { name: string; description: string };
inputSchema: JsonSchema;
outputSchema?: JsonSchema;
}
```
资料来源：[src/cli/list-command.ts:31-36]()
## 生命周期管理
### 生命周期模式
运行时系统支持两种服务器生命周期模式：
```typescript
type ServerLifecycle =
| { mode: 'keep-alive'; idleTimeoutMs?: number }
| { mode: 'ephemeral' };
```
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `keep-alive` | 服务器启动后保持运行，可复用连接 | 高频调用、资源充足环境 |
| `ephemeral` | 每次工具调用后终止服务器 | 低频调用、资源受限环境 |
### keep-alive 命令识别
系统通过签名片段匹配识别需要保持连接的服务器命令：
```typescript
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 服务器响应中提取结构化数据：
```typescript
export interface ExtractedContent {
content: unknown;
structuredContent: unknown;
textEntries: string[];
markdownEntries: string[];
jsonCandidates: unknown[];
images: ImageContent[] | null;
}
```
### 内容提取流程
```mermaid
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
```
### 支持的内容类型
| 内容类型 | 处理逻辑 |
|----------|----------|
| `text` | 直接添加到 `textEntries` |
| `markdown` | 添加到 `textEntries` 和 `markdownEntries` |
| `image` | 提取 data 和 mimeType，添加到 `images` |
| `resource` | 递归解析 uri、mimeType、text、blob 字段 |
| 其他 | 跳过处理 |
资料来源：[src/result-utils.ts:1-80]()
## 错误处理机制
### 错误分类系统
运行时系统包含完善的错误分类机制，为不同类型的连接问题提供诊断建议：
```mermaid
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[通用错误信息]
```
### 状态类别定义
```typescript
type StatusCategory = 'ok' | 'auth' | 'offline' | 'http' | 'error';
```
| 状态 | 含义 | 颜色标识 |
|------|------|----------|
| `ok` | 连接成功，工具正常 | 绿色 |
| `auth` | 认证失败或缺失 | 黄色 |
| `offline` | 服务器不可达 | 红色 |
| `http` | HTTP 协议层错误 | 红色 |
| `error` | 通用运行时错误 | 红色 |
资料来源：[src/runtime/errors.ts](), [src/cli/list-format.ts:25-40]()
## 工具调用流程
### 标准工具调用序列
```mermaid
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` 格式的工具选择器，简化跨服务器工具调用：
```typescript
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]()
## 配置与超时控制
### 超时配置参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `LIST_TIMEOUT_MS` | 30000ms | 工具列表加载超时 |
| `MCPORTER_OAUTH_TIMEOUT_MS` | 环境变量控制 | OAuth 流程超时 |
### 运行时超时处理
```typescript
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` 提供了详细的进程清理逻辑，用于调试挂起问题：
```typescript
// 强制销毁 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
运行时系统通过以下入口导出公共接口：
```typescript
// 主入口
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. 选择合适的生命周期模式
```typescript
// 高频调用场景 - 使用 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. 配置合理的超时时间
```bash
# 启动时指定超时
mcporter list --timeout-ms 60000
# 或通过环境变量
export MCPORTER_OAUTH_TIMEOUT_MS=120000
```
### 3. 利用工具选择器
```bash
# 正确使用 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 服务器交互，同时保持良好的开发体验。
---
## 传输层
### 相关页面
相关主题：[运行时系统](#page-runtime-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/runtime/transport.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/transport.ts)
- [src/cli/transport-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/transport-utils.ts)
- [src/cli/http-utils.ts](https://github.com/steipete/mcporter/blob/main/src/cli/http-utils.ts)
- [src/runtime/node-http-fetch.ts](https://github.com/steipete/mcporter/blob/main/src/runtime/node-http-fetch.ts)
- [src/lifecycle.ts](https://github.com/steipete/mcporter/blob/main/src/lifecycle.ts)
- [src/cli/adhoc-server.ts](https://github.com/steipete/mcporter/blob/main/src/cli/adhoc-server.ts)
# 传输层
## 概述
传输层是 mcporter 架构中连接 MCP 服务器与客户端的核心组件，负责处理不同通信协议之间的数据传输与协议协商。mcporter 支持多种传输方式，包括 HTTP、SSE（Server-Sent Events）和 stdio（标准输入输出），每种传输方式都有其特定的适用场景和配置要求。
传输层的主要职责包括：
- 建立与 MCP 服务器的连接
- 处理请求与响应的序列化/反序列化
- 管理传输生命周期（持久连接 vs 临时连接）
- 处理认证和授权流程
- 提供传输层面的错误处理与重试机制
资料来源：[src/runtime/transport.ts:1-50]()
## 支持的传输类型
mcporter 支持三种主要的传输协议，开发者可通过 `--transport` 参数显式指定，或由系统自动检测：
| 传输类型 | 标识符 | 说明 | 适用场景 |
|---------|--------|------|---------|
| HTTP | `http` | 基于 RESTful 风格的请求/响应模式 | 远程服务器、无状态服务 |
| SSE | `sse` | Server-Sent Events，支持服务端推送 | 需要实时更新的场景 |
| stdio | `stdio` | 标准输入输出流 | 本地进程、子进程通信 |
资料来源：[src/cli/config/help.ts:3]()
## HTTP 传输
### 基本原理
HTTP 传输是 mcporter 用于连接远程 MCP 服务器的主要方式。客户端通过 HTTP POST 请求发送工具调用请求，服务器返回 JSON 格式的响应。
```mermaid
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 传输支持多种请求头配置，用于认证和自定义元数据传递：
```typescript
interface HttpTransportConfig {
url: string;
headers?: Record;
timeout?: number;
}
```
资料来源：[src/runtime/node-http-fetch.ts:1-40]()
## SSE 传输
### 基本原理
SSE（Server-Sent Events）传输允许服务器主动向客户端推送消息，这在需要实时通知或长连接操作的场景中特别有用。
```mermaid
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 传输支持复杂的命令行解析，包括引号处理和参数转义：
```mermaid
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 传输包含对特定命令的自动识别机制：
| 命令类型 | 标识 | 行为 |
|---------|------|------|
| Chrome DevTools | `chrome-devtools` 相关占位符 | 自动分配动态端口 |
| 持久化命令 | 配置中的 keep-alive 列表 | 保持连接复用 |
资料来源：[src/lifecycle.ts:30-80]()
## 传输生命周期管理
### 生命周期模式
mcporter 支持两种服务器生命周期模式：
| 模式 | 标识 | 说明 |
|------|------|------|
| 持久化 | `keep-alive` | 服务器进程持续运行，支持连接复用 |
| 临时 | `ephemeral` | 每次请求后终止服务器进程 |
### 持久化配置
```typescript
interface LifecycleConfig {
mode: 'keep-alive' | 'ephemeral';
idleTimeoutMs?: number; // 可选的空闲超时配置
}
```
资料来源：[src/lifecycle.ts:100-150]()
### 生命周期序列化
```mermaid
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` 函数用于生成人类可读的传输信息摘要：
```typescript
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]()
### 传输类型检测
传输层提供自动检测机制，根据服务器配置推断最合适的传输类型：
```typescript
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` 模块提供额外配置能力：
```typescript
// 超时配置示例
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 传输层的错误分类：
| 错误类型 | 状态码范围 | 处理策略 |
|---------|-----------|---------|
| 认证错误 | 401, 403 | 提示用户执行 `mcporter auth login` |
| 网络错误 | - | 自动重试或返回离线状态 |
| 服务器错误 | 5xx | 记录日志，返回错误状态 |
| 超时 | - | 根据配置的超时时间终止请求 |
资料来源：[src/cli/http-utils.ts:50-100]()
## 进程清理与资源管理
### 标准清理流程
对于 stdio 传输，mcporter 在连接关闭时执行以下清理：
```mermaid
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]()
### 锁文件恢复
传输层包含锁文件管理机制，用于处理异常进程退出：
```typescript
async function removeRecoverableLock(lockPath: string): Promise
```
恢复条件：
- 锁文件持有进程已不存在
- 锁文件创建时间超过阈值
- breaker 文件存在且满足恢复条件
资料来源：[src/fs-json.ts:60-100]()
## 配置参考
### 传输相关配置项
| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| `transport` | `http` \| `sse` \| `stdio` | 自动检测 | 强制使用指定传输类型 |
| `baseUrl` | string | - | HTTP 服务器基础 URL |
| `command` | string | - | stdio 模式下的可执行命令 |
| `args` | string[] | `[]` | 命令行参数 |
| `env` | Record | `{}` | 环境变量 |
### 命令行参数
| 参数 | 说明 |
|------|------|
| `--transport ` | 指定传输类型 |
| `--arg ` | 传递 stdio 额外参数（可重复） |
| `--header KEY=value` | 添加 HTTP 请求头（可重复） |
| `--env KEY=value` | 设置环境变量（可重复） |
资料来源：[src/cli/config/help.ts:1-30]()
## 最佳实践
### 选择传输类型
1. **远程 API 访问**：优先使用 HTTP 传输
2. **需要实时推送**：选择 SSE 传输
3. **本地工具集成**：使用 stdio 传输
4. **混合场景**：在配置文件中为每个服务器单独指定
### 性能优化
- 对于频繁调用的服务器，启用 `keep-alive` 模式减少连接建立开销
- HTTP 传输建议设置合理的超时时间（默认 60 秒）
- stdio 传输注意进程清理，避免僵尸进程
### 安全建议
- 使用 HTTPS 替代 HTTP 传输敏感数据
- 通过环境变量存储认证凭据，避免硬编码
- 定期轮换 OAuth 客户端密钥
## 相关文档
- [配置管理](./config.md) - 传输层配置详解
- [认证流程](./auth.md) - OAuth 和 API Key 认证
- [工具调用](./tools.md) - 通过传输层执行工具调用
- [CLI 生成](./cli-generation.md) - 生成独立 CLI 工具
---
## CLI 命令参考
### 相关页面
相关主题：[工具调用语法](#page-call-syntax), [调用启发式与自动更正](#page-call-heuristic)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/cli-reference.md](https://github.com/steipete/mcporter/blob/main/docs/cli-reference.md)
- [README.md](https://github.com/steipete/mcporter/blob/main/README.md)
- [src/cli/cli-factory.ts](https://github.com/steipete/mcporter/blob/main/src/cli/cli-factory.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/cli/serve-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/serve-command.ts)
- [src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/cli/list-output.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-output.ts)
# CLI 命令参考
## 概述
mcporter 提供了一套完整的命令行工具，用于管理、调用和调试 MCP（Model Context Protocol）服务器。该 CLI 是与 MCP 服务器交互的主要入口点，支持服务器发现、工具调用、配置管理以及代码生成等功能。
CLI 工具的核心设计理念是统一处理不同类型的 MCP 服务器（HTTP、SSE、stdio），并提供一致的接口和输出格式。通过运行时抽象层，`mcporter` 能够自动发现已配置的服务器、处理 OAuth 认证、管理连接生命周期。资料来源：[README.md:1-50]()
## 核心命令架构
mcporter CLI 采用子命令架构，主要包含以下命令模块：
```mermaid
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 命令支持以下全局选项：
| 选项 | 说明 | 环境变量 |
|------|------|----------|
| `--config ` | 指定配置文件路径 | `MCPORTER_CONFIG` |
| `--root ` | 设置工作目录 | - |
| `--log-level ` | 设置日志级别（debug/info/warn/error） | `MCPORTER_LOG_LEVEL` |
| `--oauth-timeout ` | OAuth 超时时间 | `MCPORTER_OAUTH_TIMEOUT_MS` |
| `--output ` | 控制输出格式 | - |
资料来源：[src/cli/config/help.ts:1-30]()
## mcporter list
`list` 命令用于列出已配置的 MCP 服务器及其可用工具。
### 基本用法
```bash
mcporter list [server]
mcporter list --json
mcporter list --signatures
```
### 选项说明
| 选项 | 说明 |
|------|------|
| `--json` | 以 JSON 格式输出结果 |
| `--signatures` | 仅显示函数签名 |
| `--brief` | 简化输出格式 |
| `--all-parameters` | 显示所有参数（包括可选） |
| `--required-only` | 仅显示必需参数 |
| `--schema` | 显示 JSON Schema |
资料来源：[src/cli/list-command.ts:1-50]()
### 输出状态分类
服务器状态分为以下几类：
| 状态 | 含义 | 颜色标识 |
|------|------|----------|
| `ok` | 服务器正常，可调用工具 | 绿色 |
| `auth` | 需要认证 | 黄色 |
| `offline` | 服务器离线 | 灰色 |
| `http` | HTTP 错误 | 红色 |
| `error` | 未知错误 | 红色 |
资料来源：[src/cli/list-format.ts:40-80]()
### 服务器信息格式化
输出格式包括工具数量、响应耗时和来源信息：
```typescript
// 输出格式示例
- 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 服务器上的特定工具。
### 基本用法
```bash
mcporter call . [args...]
mcporter call context7.resolve-library-id --query "React hooks"
```
### 选项说明
| 选项 | 说明 |
|------|------|
| `--raw` | 保持原始输出格式 |
| `--raw-strings` | 保持数字形式的字符串参数 |
| `--no-coerce` | 禁用类型转换 |
| `--save-images ` | 保存图片内容到指定目录 |
| `--tail-log` | 显示相关日志的最后 20 行 |
### 参数传递规则
`call` 命令支持多种参数格式：
```bash
# 关键字参数
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 配置文件。
### 子命令
| 子命令 | 说明 |
|--------|------|
| `config list` | 列出本地配置 |
| `config get ` | 获取指定配置项 |
| `config add ` | 添加新配置 |
| `config remove ` | 删除配置项 |
| `config import ` | 导入外部配置 |
资料来源：[README.md:120-150]()
### 配置示例
```jsonc
{
"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 服务器转换为独立的命令行工具。
### 基本用法
```bash
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
```
### 生成选项
| 选项 | 说明 |
|------|------|
| `--name ` | 覆盖推断的 CLI 名称 |
| `--description ` | 设置帮助文本摘要 |
| `--command ` | MCP 服务器命令或 URL |
| `--server ` | 从配置中选择服务器 |
| `--bundle ` | 输出捆绑包路径 |
| `--dry-run` | 预览生成结果 |
| `--from ` | 从现有 CLI 重新生成 |
资料来源：[README.md:30-60]()
### 工件元数据
生成的 CLI 嵌入以下元数据：
```bash
npx mcporter inspect-cli dist/context7.js # 查看元数据摘要
npx mcporter generate-cli --from dist/context7.js # 使用元数据重新生成
```
## mcporter emit-ts
生成强类型的 TypeScript 客户端代码，无需完整的 CLI 即可使用 MCP 工具。
### 基本用法
```bash
# 仅生成类型定义
mcporter emit-ts linear --out types/linear-tools.d.ts
# 生成客户端包装器
mcporter emit-ts linear --mode client --out clients/linear.ts
```
### 输出模式
| 模式 | 说明 | 输出文件 |
|------|------|----------|
| `types` | 仅接口定义 | `.d.ts` |
| `client` | 接口 + 代理工厂 | `.d.ts` + `.ts` |
### 附加选项
| 选项 | 说明 |
|------|------|
| `--include-optional` | 展开所有可选字段 |
| `--json` | 输出结构化摘要 |
| `--server ` | 选择服务器（支持 URL） |
生成的客户端模式与 `createRuntime()` API 保持同步。资料来源：[README.md:70-100]()
## mcporter inspect-cli
检查已生成 CLI 工件的元数据和签名信息。
### 基本用法
```bash
mcporter inspect-cli dist/context7.js
```
## 服务器生命周期管理
mcporter 支持两种服务器生命周期模式：
| 模式 | 说明 | 配置值 |
|------|------|--------|
| `keep-alive` | 持续运行，复用连接 | `"keep-alive"` |
| `ephemeral` | 每次调用后关闭 | `"ephemeral"` |
### 生命周期配置
```json
{
"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` 选项获取机器可读输出：
```json
{
"servers": [
{
"name": "context7",
"status": "ok",
"durationMs": 1200,
"tools": [...]
}
]
}
```
资料来源：[src/cli/list-output.ts:1-80]()
## OAuth 认证
mcporter 自动处理 MCP 服务器的 OAuth 认证流程。
### OAuth 配置选项
| 选项 | 说明 |
|------|------|
| `--oauth-client-id ` | 使用预注册的客户端 ID |
| `--oauth-client-secret-env ` | 从环境变量读取密钥 |
| `--oauth-token-endpoint-auth-method ` | 设置令牌认证方式 |
| `--oauth-redirect-url ` | 自定义重定向 URL |
| `--token-cache-dir ` | OAuth 令牌缓存目录 |
### 认证流程
```mermaid
sequenceDiagram
participant User
participant CLI as mcporter
participant Server as MCP Server
participant Browser
User->>CLI: call .
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]()
## 错误处理与调试
### 常见错误状态
| 状态码 | 含义 | 解决方案 |
|--------|------|----------|
| `auth` | 认证失败 | 运行 `mcporter config login ` |
| `offline` | 服务器不可达 | 检查网络连接和服务器地址 |
| `http` | HTTP 请求错误 | 检查服务器日志 |
| `error` | 未知错误 | 使用 `--log-level debug` 调试 |
### 调试模式
```bash
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` 直接运行未配置的服务器：
```bash
mcporter list --command "npx -y some-mcp-server"
```
支持完整的命令参数传递和生命周期管理。资料来源：[src/cli/adhoc-server.ts:1-50]()
### 工具选择器
使用点号分隔符精确指定服务器和工具：
```bash
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` 生命周期模式
---
*本文档最后更新于 2024 年 11 月，基于 mcporter 最新版本。*
---
## 工具调用语法
### 相关页面
相关主题：[调用启发式与自动更正](#page-call-heuristic), [CLI 命令参考](#page-cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/call-syntax.md](https://github.com/steipete/mcporter/blob/main/docs/call-syntax.md)
- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)
- [src/cli/call-argument-expression.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-argument-expression.ts)
- [src/cli/call-expression-parser.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-expression-parser.ts)
- [src/cli/command-inference.ts](https://github.com/steipete/mcporter/blob/main/src/cli/command-inference.ts)
# 工具调用语法
## 概述
mcporter 的工具调用语法（Tool Calling Syntax）是连接用户命令行与 MCP（Model Context Protocol）服务器工具之间的核心桥接层。该系统负责解析用户输入的参数表达式，将其转换为符合工具 schema 的结构化参数，并最终传递给运行时执行调用。
工具调用语法的主要职责包括：
- **参数解析**：支持命名参数、位置参数、混合使用等多种调用方式
- **类型强制转换**：自动将字符串形式的参数值转换为 schema 定义的正确类型
- **工具发现**：根据服务器名称和工具名称定位目标工具
- **参数验证**：验证参数是否符合工具定义的输入 schema
资料来源：[src/cli/call-command.ts:1-50]()
## 核心组件架构
### 组件关系图
```mermaid
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
```
### 主要模块说明
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| call-command | `src/cli/call-command.ts` | 命令入口、参数解析协调、调用执行 |
| call-expression-parser | `src/cli/call-expression-parser.ts` | 解析位置参数表达式 |
| call-argument-expression | `src/cli/call-argument-expression.ts` | 处理参数表达式求值 |
| command-inference | `src/cli/command-inference.ts` | 服务器和工具名称推断 |
| list-command | `src/cli/list-command.ts` | 工具元数据查询 |
资料来源：[src/cli/call-command.ts:50-100]()
## 调用方式
mcporter 支持多种工具调用方式，以适应不同用户习惯和场景需求。
### 1. 命名参数方式
最直接的调用方式，用户显式指定每个参数的名称和值：
```bash
mcporter call . --key1=value1 --key2=value2
```
示例：
```bash
mcporter call linear.create-issue --title="Bug Report" --team_id=team123
```
### 2. 位置参数方式
用户按照工具 schema 定义的参数顺序提供值，系统自动将位置参数映射到对应的字段：
```bash
mcporter call .
```
位置参数映射遵循以下规则：
- 仅填充**未通过命名参数设置的字段**
- 严格校验位置参数数量不超过剩余可填充字段数
- 必须按照 schema 中 required 参数在前、optional 参数在后的顺序提供
资料来源：[src/cli/call-command.ts:150-200]()
```typescript
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. 混合使用方式
命名参数和位置参数可以混合使用，命名参数具有更高的优先级：
```bash
mcporter call . --key2=value2
```
### 4. 选择器语法（Selector Syntax）
使用点号分隔符直接指定服务器和工具：
```bash
mcporter call .
```
系统会从 `.` 中提取服务器名称和工具名称，支持自动补全和建议功能。
资料来源：[src/cli.ts:80-120]()
## 参数类型强制转换
mcporter 内置了智能的类型强制转换系统，能够自动将命令行输入的字符串值转换为工具 schema 定义的正确类型。
### 支持的转换类型
| 目标类型 | 转换规则 | 示例 |
|----------|----------|------|
| string | 保持原值 | `--name=value` → `"value"` |
| number | 解析数值字符串 | `--count=42` → `42` |
| boolean | 识别真值/假值 | `--verbose=true` → `true` |
| null | 识别 null 字符串 | `--value=null` → `null` |
| array | 逗号分隔或 JSON 数组 | `--ids=a,b,c` → `["a","b","c"]` |
| object | JSON 对象字符串 | `--config='{"a":1}'` → `{a:1}` |
### 强制转换流程
```mermaid
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]()
```typescript
async function enforceSchemaAwareArgumentTypes(
runtime,
server,
tool,
args,
stringCandidates,
arrayCandidates,
timeoutMs
): Promise> {
// 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 } | 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. **按顺序映射**：将位置参数依次赋给剩余字段
```typescript
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));
```
## 工具选择器解析
### 服务器和工具名称推断
系统支持通过多种方式指定目标服务器和工具：
```mermaid
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. **点号分隔符**：`.` 格式直接解析
2. **服务器标志**：`--server ` 或 `--server=`
3. **工具标志**：`--tool ` 或 `--tool=`
4. **URL 识别**：包含 `://` 的输入视为 HTTP 服务器定义
```typescript
const separator = token.indexOf('.');
if (separator > 0) {
return token.slice(0, separator); // 返回服务器名
}
```
### 自动补全建议
当用户输入的服务器或工具名称不存在时，系统会使用 `chooseClosestIdentifier` 函数提供最接近的候选建议：
```typescript
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]; // 最长匹配优先
}
```
## 错误处理与诊断
### 常见错误类型
| 错误场景 | 错误信息 | 解决方案 |
|----------|----------|----------|
| 工具不存在 | `Tool 'xxx' not found on 'yyy'` | 检查工具名称是否正确 |
| 参数过多 | `Too many positional arguments` | 减少位置参数或使用命名参数 |
| 参数缺失 | `Missing required parameter` | 检查 required 字段 |
| 类型不匹配 | `Cannot convert 'xxx' to number` | 检查参数格式 |
| Schema 不可用 | `Unable to load tool metadata` | 检查服务器连接 |
### 参数类型错误处理
当类型强制转换失败时，系统会保留原始字符串值并输出警告，而非直接报错。这允许某些工具接受灵活格式的输入。
资料来源：[src/cli/call-command.ts:250-300]()
### 超时处理
所有涉及网络请求的操作都支持超时控制：
```typescript
const tools = await withTimeout(
loadToolMetadata(runtime, server, { includeSchema: true }),
timeoutMs
).catch(() => undefined);
```
## 调用流程完整图
```mermaid
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` 标志可以禁用所有自动类型转换，保持参数值为原始字符串形式：
```bash
mcporter call server.tool --raw-strings --count=42 --enabled=true
```
此模式下，所有值都将作为字符串传递，不会进行数值或布尔值转换。
### 禁用 Coerce 模式
`--no-coerce` 标志完全禁用类型强制，包括 `key=value`、`key:value` 和尾部位置参数的所有转换：
```bash
mcporter call server.tool --no-coerce --id=12345 --data='{"json":"value"}'
```
### 双破折号分隔符
使用 `--` 可以停止标志解析，使后续参数保持字面形式：
```bash
mcporter call server.tool -- --some-value --another-value
```
## 命令行参数速查表
| 参数 | 说明 | 示例 |
|------|------|------|
| `--server ` | 指定服务器名称 | `--server linear` |
| `--tool ` | 指定工具名称 | `--tool create-issue` |
| `--timeout ` | 设置调用超时 | `--timeout 60000` |
| `--raw-strings` | 禁用类型转换 | `--raw-strings` |
| `--no-coerce` | 禁用所有强制转换 | `--no-coerce` |
| `--output ` | 指定输出格式 | `--output json` |
## 相关文档
- [配置文件参考](docs/config.md) - mcporter.json 配置语法
- [emit-ts 命令](docs/emit-ts.md) - 生成 TypeScript 类型定义
- [generate-cli 命令](docs/generate-cli.md) - 生成独立 CLI 工具
---
## 调用启发式与自动更正
### 相关页面
相关主题：[工具调用语法](#page-call-syntax), [CLI 命令参考](#page-cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/call-heuristic.md](https://github.com/steipete/mcporter/blob/main/docs/call-heuristic.md)
- [src/cli/identifier-helpers.ts](https://github.com/steipete/mcporter/blob/main/src/cli/identifier-helpers.ts)
- [src/cli/server-lookup.ts](https://github.com/steipete/mcporter/blob/main/src/cli/server-lookup.ts)
- [src/cli/list-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
- [src/cli/list-format.ts](https://github.com/steipete/mcporter/blob/main/src/cli/list-format.ts)
- [src/cli/call-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/call-command.ts)
# 调用启发式与自动更正
mcporter 的调用启发式与自动更正系统为 MCP 服务器和工具的调用提供了智能容错机制。该系统通过模糊匹配、选择建议和上下文感知解析，显著提升了命令行交互的用户体验，减少了因拼写错误或格式偏差导致的命令失败。
## 核心概念
mcporter 在处理服务器名称、工具选择器和命令参数时，采用了多层次的启发式策略。这些策略协同工作，形成了从输入解析到错误恢复的完整链路。
### 模糊匹配算法
当用户输入的服务器名称与配置中的实际名称不完全匹配时，mcporter 使用基于字符串相似度的算法进行自动更正。该算法不仅考虑精确匹配，还评估字符串之间的距离和公共子序列。资料来源：[src/cli/identifier-helpers.ts]()
```typescript
// 伪代码示例：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]()
| 输入类型 | 处理策略 | 示例 |
|---------|---------|------|
| 精确名称 | 直接映射 | `mcporter list context7` |
| 带点分隔符 | 提取 server 和 tool | `mcporter call linear.listProjects` |
| 前缀模糊 | 扫描配置匹配 | `sshadcn` → `shadcn` |
| URL 格式 | 协议解析 | `https://mcp.context7.com/mcp` |
### 2. 工具元数据加载器
工具元数据加载器负责获取指定服务器的工具列表，并在存在请求的工具时进行过滤。该组件通过 MCP 协议的 `tools/list` 方法获取服务器提供的所有工具及其输入模式。资料来源：[src/cli/list-command.ts:54-71]()
```typescript
// 工具元数据过滤逻辑
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]()
```typescript
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 ` 形式的命令
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]()
```typescript
// 从工具模式推断位置参数映射
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]()
```typescript
function serializeLifecycle(lifecycle: ReturnType): 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 的模糊匹配功能能够智能处理常见的拼写错误：
| 用户输入 | 实际配置 | 校正行为 |
|---------|---------|---------|
| `sshadcn` | `shadcn` | 自动更正 + 提示消息 |
| `contextt7` | `context7` | 自动更正 |
| `linearr` | `linear` | 自动更正 |
校正发生时，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 list` | 匹配服务器名称 | `--exact` 禁用模糊匹配 |
| `mcporter call` | 匹配服务器和工具 | `--strict` 严格模式 |
| `mcporter config` | 匹配配置键名 | 无需配置 |
## 错误处理
### 缺失工具的诊断
当用户请求的工具在服务器上不存在时，mcporter 提供友好的错误消息，列出该服务器实际提供的工具列表。资料来源：[src/cli/list-command.ts:72-79]()
```typescript
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]()
```typescript
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 等）的专业故障排除指导。
## 相关文档
- [配置管理文档](docs/config.md) - 了解服务器配置的编写方式
- [emit-ts 文档](docs/emit-ts.md) - 生成类型化客户端工具
- [Agent Skills 文档](docs/agent-skills.md) - 为 AI 代理编写技能定义
---
## 配置管理
### 相关页面
相关主题：[核心架构](#page-core-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/config.md](https://github.com/steipete/mcporter/blob/main/docs/config.md)
- [src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)
- [src/config/path-discovery.ts](https://github.com/steipete/mcporter/blob/main/src/config/path-discovery.ts)
- [src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)
- [src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)
- [src/cli/config/index.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/index.ts)
# 配置管理
mcporter 的配置管理系统负责定义、加载和组织 MCP 服务器的连接信息。该系统支持多种配置源、灵活的命名匹配、跨编辑器的配置导入以及完整的 XDG 标准兼容。
## 配置架构概述
mcporter 采用分层配置架构，支持本地项目配置、全局用户配置和系统级配置的组合使用。
```mermaid
graph TD
A[CLI 参数] --> B[环境变量
MCPORTER_CONFIG]
B --> C[项目配置
config/mcporter.json]
C --> D[XDG 配置
$XDG_CONFIG_HOME/mcporter/mcporter.json]
D --> E[默认配置
~/.mcporter/mcporter.json]
F[MCP Servers 定义] --> C
G[导入配置
Cursor/Claude/Windsurf] --> C
H[OAuth Vault 存储] -.-> D
```
配置加载按优先级从高到低依次为：
1. **CLI 参数**：`--config ` 或 `--root `
2. **环境变量**：`MCPORTER_CONFIG`
3. **项目配置**：`/config/mcporter.json`
4. **XDG 配置**：`$XDG_CONFIG_HOME/mcporter/mcporter.json`
5. **默认配置**：`~/.mcporter/mcporter.json`
资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)
## 配置文件格式
mcporter 支持 JSONC 格式的配置文件，允许使用行内注释和尾随逗号。
```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](https://github.com/steipete/mcporter/blob/main/README.md)
### 服务器定义结构
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `command` | `string` | 条件 | stdio 传输时的启动命令 |
| `args` | `string[]` | 否 | 命令行参数数组 |
| `env` | `Record` | 否 | 环境变量 |
| `baseUrl` | `string` | 条件 | HTTP 传输时的服务器地址 |
| `headers` | `Record` | 否 | HTTP 请求头 |
| `transport` | `http \| sse \| stdio` | 否 | 强制指定传输类型 |
| `description` | `string` | 否 | 服务器描述文本 |
| `allowedTools` | `string[]` | 否 | 允许的工具列表（白名单） |
| `blockedTools` | `string[]` | 否 | 屏蔽的工具列表（黑名单） |
| `lifecycle` | `keep-alive \| ephemeral` | 否 | 服务器生命周期模式 |
资料来源：[src/config.ts](https://github.com/steipete/mcporter/blob/main/src/config.ts)
## 路径发现机制
配置路径发现遵循标准化的优先级规则，支持显式覆盖和 XDG 标准。
```mermaid
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`，支持以下环境变量：
| 环境变量 | 用途 | 默认值 |
|----------|------|--------|
| `MCPORTER_CONFIG` | 直接指定配置文件路径 | - |
| `XDG_CONFIG_HOME` | XDG 配置根目录 | `~/.config` |
| `XDG_DATA_HOME` | OAuth 令牌存储目录 | `~/.local/share` |
| `XDG_CACHE_HOME` | Schema 缓存目录 | `~/.cache` |
| `XDG_STATE_HOME` | 守护进程状态目录 | `~/.local/state` |
资料来源：[README.md](https://github.com/steipete/mcporter/blob/main/README.md)
## 工具过滤配置
服务器定义支持细粒度的工具访问控制，通过 `allowedTools` 和 `blockedTools` 实现白名单和黑名单机制。
```jsonc
{
"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](https://github.com/steipete/mcporter/blob/main/README.md)
## 配置管理命令
`mcporter config` 提供交互式配置管理功能，支持列表、查询、添加、删除和导入操作。
### 子命令概览
| 命令 | 功能 |
|------|------|
| `mcporter config list` | 列出当前配置的服务器 |
| `mcporter config get ` | 获取指定服务器配置详情 |
| `mcporter config add ` | 添加新服务器配置 |
| `mcporter config remove ` | 删除服务器配置 |
| `mcporter config import ` | 从编辑器导入配置 |
| `mcporter config logout ` | 清除 OAuth 认证信息 |
资料来源：[src/cli/config-command.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config-command.ts)
### 添加服务器配置
```bash
# 基本 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
```
支持的添加参数：
| 参数 | 说明 |
|------|------|
| `--command ` | stdio 传输的启动命令 |
| `--transport ` | 强制指定传输类型 |
| `--arg ` | 附加 stdio 参数（可重复） |
| `--env KEY=value` | 环境变量（可重复） |
| `--header KEY=value` | HTTP 请求头（可重复） |
| `--auth ` | 强制认证类型 |
| `--oauth-client-id ` | OAuth 客户端 ID |
| `--oauth-client-secret-env ` | OAuth 密钥环境变量名 |
| `--token-cache-dir ` | OAuth 令牌缓存目录 |
| `--persist ` | 写入指定配置文件路径 |
| `--scope ` | 配置文件作用域 |
| `--copy-from ` | 从导入配置复制 |
资料来源：[src/cli/config/help.ts](https://github.com/steipete/mcporter/blob/main/src/cli/config/help.ts)
## 配置导入系统
mcporter 支持从主流编辑器的配置中导入 MCP 服务器定义，实现配置迁移。
### 支持的导入源
| 编辑器 | 导入标识 | 配置格式 |
|--------|----------|----------|
| Cursor | `cursor` | `cursor/mcp.json` |
| Claude Code | `claude-code` | `.claude/mcp.json` |
| Windsurf | `windsurf` | `windsurf/mcp.json` |
| VS Code | `vscode` | `mcp.json` |
```bash
# 列出可导入的服务器
mcporter config import cursor --list
# 交互式导入
mcporter config import cursor
# 直接复制到本地配置
mcporter config import cursor --copy
```
导入过程会处理多种配置格式，包括 `mcpServers`、`servers` 和 `mcp` 容器结构。
资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)
### 导入安全规则
不同来源的导入有不同的安全限制：
```typescript
{
allowMcpServers: true, // 标准 mcpServers 容器
allowServers: true, // servers 容器
allowMcp: true, // mcp 容器
allowRootFallback: boolean // 是否允许根目录回退
}
```
Claude Code 配置有特殊处理，仅在 `.claude.json` 或 `.claude/mcp.json` 路径下允许根目录回退。
资料来源：[src/config/imports/external.ts](https://github.com/steipete/mcporter/blob/main/src/config/imports/external.ts)
## 模糊匹配与自动纠正
mcporter 在配置管理中内置了智能模糊匹配机制，支持输入纠错和歧义提示。
```bash
# 拼写错误自动纠正
mcporter config get sshadcn
# 输出: sshadcn → shadcn (已纠正)
# 歧义时提示选择
mcporter config get linear
# 输出: "Did you mean linear-api or linear-tools?"
```
匹配逻辑实现于 `src/cli/list-command.ts`，使用最长前缀匹配策略：
```typescript
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](https://github.com/steipete/mcporter/blob/main/src/cli/list-command.ts)
## 配置输出格式化
`mcporter list` 命令以表格形式展示配置，支持文本和 JSON 两种输出格式。
### 状态分类
| 状态 | 说明 | 颜色编码 |
|------|------|----------|
| `ok` | 服务器在线，工具可用 | 绿色 |
| `auth` | 需要认证 | 黄色 |
| `offline` | 服务器离线 | 灰色 |
| `http` | HTTP 错误 |
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.
---
---
## Doramagic 踩坑日志
项目：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 ` to seed credentials non-interactively
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add `mcporter vault set ` 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