MCP Reporter

---

mcp-reporter 会连接本地 stdio 进程和远程 Streamable HTTP 端点，读取它们公布的功能，并生成报告，供你与项目文档一同保存或传递给其他工具。

它会枚举工具、资源、资源模板和提示词，但不会执行工具、读取资源内容或展开提示词。查看合成示例报告。

快速开始

需要 Node.js 22.12 或更高版本。开发使用 Bun 1.4 或更高版本。

创建 mcp-servers.json，添加一个你已在运行的服务：

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

生成报告：

npx mcp-reporter --config mcp-servers.json --output output/report.md

配置

配置是一个包含 mcpServers 的 JSON 对象。每个键用于在报告中标识一个服务。本地和远程条目可以共用一个文件：

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"],
      "env": { "EXAMPLE_API_KEY": "REPLACE_WITH_YOUR_KEY" }
    },
    "remote-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN" }
    },
    "disabled-server": {
      "command": "node",
      "args": ["/absolute/path/to/another/server.js"],
      "disabled": true
    }
  }
}

字段	适用对象	含义
command	stdio	要启动的可执行文件
args	stdio	可选参数数组
env	stdio	可选的字符串环境变量条目，会传递给 SDK 传输层
cwd	stdio	子进程的可选工作目录
url	HTTP	Streamable HTTP 端点，包含其 MCP 路径
headers	HTTP	可选的静态请求标头
type	任一	可选的 stdio 或 http；必须与条目类型一致
disabled	任一	为 true 时跳过该条目
alwaysAllow	任一	为兼容配置而接受；不会调用任何工具

必须且只能提供 command 或 url 其中之一。连接前，报告生成器会验证整个文件。路径相对于进程工作目录解析；在多个调用方之间共享配置时，请使用绝对路径。不支持交互式 OAuth 和旧版 SSE 端点。

配置值可能包含凭据。报告生成器会从诊断信息和启动元数据中省略 env/header 值、原始命令参数以及 URL 路径、查询参数和用户信息。子进程 stderr 会被抑制；错误会以安全的类别表示。服务提供的描述、架构、指令和扩展元数据会作为报告内容保留，因此分享报告前请先检查这些内容。

选择协议模式

默认使用旧版协商，以兼容需要 initialize 的服务。

--protocol-era	行为
legacy	使用旧版握手，不执行发现探测
auto	探测对现代协议的支持；根据旧版证据回退
2026-07-28	要求使用该现代修订版；不回退到旧版

npx mcp-reporter --config mcp-servers.json --protocol-era auto

自动模式可能会额外启动一个短暂运行的 stdio 进程，并在执行旧版握手前等待探测超时。HTTP 授权失败和超时会报告为失败，而不会视为支持旧版协议的证据。报告会记录实际选择的协议版本和时代。

报告内容

部分	包含的信息
执行摘要	连接数量和已收集的能力数量
连接失败	已配置的服务 ID 和安全的失败原因
服务信息	传输方式、实现身份、协商的协议、连接时间、声明的标志、说明
工具	名称、标题、描述、输入/输出架构、注释、图标和扩展元数据
资源和模板	URI/模板、名称、描述、MIME 类型和提供的元数据
提示词	名称、描述、参数、必填标志和提供的元数据

列表按页收集。每项能力均标记为未声明、完整（可能为空）或不完整。页数限制、游标重复和请求失败会保留已收集的条目，并将其数量标记为部分结果。某个服务或列表失败，不会丢弃其他成功的结果。

报告以表格和文本为主；较长的定义放在可折叠的详细信息中。图标作为元数据保留，不会远程加载图像。服务注释是服务提供的提示，并非经过独立验证的安全保证。枚举会保留服务的声明，即使客户端可能因工具的架构扩展无效而拒绝调用该工具。

CLI 选项

选项	默认值	用途
-c, --config <path>	mcp-servers.json	配置文件
-o, --output <path>	output/mcp_server_report.md	Markdown 输出路径
--no-schemas	包含架构	隐藏输入架构；输出架构仍会显示
--no-metadata	包含元数据	隐藏服务信息、声明的标志和说明
--no-examples	包含示例	隐藏调用方提供的示例
--protocol-era <era>	legacy	legacy、auto 或 2026-07-28
--max-pages <count>	64	每个能力列表的正数页数上限
--timeout <ms>	30000	正数连接/请求超时时间
-q, --quiet	关闭	禁止显示进度；致命错误仍会输出到 stderr
-V, --version	—	输出软件包版本
-h, --help	—	显示帮助

对于 HTTP 服务，超时会限制整个握手过程，包括 initialized 通知的响应。超时会关闭传输、记录连接失败，并继续报告其余服务。每个能力列表请求均有独立的超时时间。

仍接受现有的正向标志 -s/--schemas、-m/--metadata 和 -e/--examples。MCP 枚举没有示例来源；只有程序化调用方将示例提供给渲染器时，报告中才会出现示例。

进度信息输出到 stderr，报告则写入所选文件。退出代码 0 表示报告已写入，包括已记录的任何连接/列表失败。配置无效或报告写入失败时，退出代码为 1。

作为库使用

bun add mcp-reporter

import { McpReporter } from 'mcp-reporter';

const reporter = new McpReporter('./mcp-servers.json', {
  outputPath: './output/capabilities.md',
  protocolEra: 'auto',
  includeInputSchemas: true,
  includeServerMetadata: true,
  maxPages: 64,
  timeoutMs: 30_000,
  progressCallback(event) {
    console.error(event.message);
  },
});

await reporter.run();

该库采用 ESM；如果没有进度回调，则不会输出任何信息。run() 会在写入报告并关闭连接后完成；遇到配置/文件错误时会拒绝执行。再次运行会开始一次全新的收集。ReportOptions.transportFactory(config, serverId) 可为嵌入式使用或确定性测试提供传输方式。

类型从软件包根目录导出。若要渲染已收集的 ServerReport[]，请从 mcp-reporter 导入 MarkdownGenerator，并调用 generateReport(reports, options)。它会遵循相同的渲染标志，并保留调用方提供的可选 ToolInfo.examples。

运行时、模块和报告方面的变更，请参阅升级到 1.1.0。

开发

构建源码检出：

git clone https://github.com/cyanheads/mcp-reporter.git
cd mcp-reporter
bun install
bun run rebuild

使用 node dist/cli.js --config mcp-servers.json 运行构建后的 CLI。

命令	用途
bun run devcheck	运行 lint、源码/脚本/测试类型检查、变更日志检查和完整测试套件
bun run rebuild	清理并编译 Node 程序包
bun run test:all	运行确定性行为测试
bun run test:package	验证编译后的 Node CLI/库及程序包内容
bun run format	应用 Biome 格式化和安全修复
bun run example:report	重新生成合成示例报告
bun run tree	重新生成目录映射
bun run list-skills	列出项目工作流

测试使用内存中的 SDK 服务、回环 HTTP 和合成 stdio 进程。测试无需凭据或外部 MCP 服务。发布工作流使用本地门禁、按版本划分的变更日志、约定式提交和带注释的标签摘要；发布目标为 npm 和 GitHub。

贡献指南 · 安全 · 变更日志 · Apache-2.0 许可证