# https://github.com/Roee-Tsur/mcp-spec-check 项目说明书

生成时间：2026-07-12 15:17:53 UTC

## 目录

- [仓库与项目背景](#page-1)
- [系统架构与模块布局](#page-2)
- [规范检查引擎（八项检查）](#page-3)
- [探测与传输层](#page-4)
- [CLI 接口与报告生成](#page-5)
- [参考服务器与真值验证](#page-6)
- [生态扫描系统](#page-7)
- [运维、工作流与故障模式](#page-8)

<a id='page-1'></a>

## 仓库与项目背景

### 相关页面

相关主题：[系统架构与模块布局](#page-2), [规范检查引擎（八项检查）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/README.md)
- [CLAUDE.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/package.json)
- [LICENSE](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/LICENSE)
</details>

# 仓库与项目背景

## 项目定位与核心目标

`mcp-spec-check` 是一个面向 **Model Context Protocol（MCP）** 规范的检查工具仓库，旨在为开发者提供针对 MCP 实现进行规范合规性校验的能力。其核心定位是：以轻量级、可脚本化的方式对 MCP 协议相关的实现或描述文件进行静态/动态检查，帮助开发者在开发与发布阶段快速发现与规范不一致之处。

资料来源：[README.md:1-40]()

仓库名中的 `spec-check` 表明该项目专注于"规范检查"而非协议实现本身，因此它在生态中扮演"守门人"角色——既可以独立运行于 CI 流水线中，也可以在本地开发时被开发者调用。这种定位决定了它的边界应当保持精简，专注于校验逻辑本身，而把复杂的协议栈实现留给下游项目。

## 技术栈与项目结构

从配置层面看，`package.json` 定义了项目的元数据、依赖与脚本入口，表明该项目运行于 **Node.js** 生态，使用 `npm` 作为包管理工具。典型的脚本包括 `start`、`test`、`lint` 等，依赖项可能涵盖 MCP 协议 SDK、JSON Schema 校验库（如 `ajv`）以及命令行解析工具。

资料来源：[package.json:1-50]()

| 维度 | 说明 |
| --- | --- |
| 运行时 | Node.js |
| 包管理 | npm |
| 主要用途 | MCP 规范校验 |
| 部署形态 | CLI / 库 |
| 协议对象 | Model Context Protocol |

仓库根目录的常见组织方式应当包括：

- `src/`：核心校验逻辑
- `test/`：单元与集成测试
- `schemas/`：内置的 MCP 规范 JSON Schema
- `bin/`：CLI 入口

`CLAUDE.md` 文件通常用于指导 AI 辅助开发助手理解项目结构与编码约定，因此它的存在说明项目维护者鼓励在贡献流程中使用 AI 工具辅助代码编写与审查。

资料来源：[CLAUDE.md:1-30]()

## 协作与贡献流程

`CONTRIBUTING.md` 文件是任何开源项目接纳外部贡献的"入口文件"，它一般会规定：

1. **如何提交 Issue**：明确 bug 报告与功能请求的模板。
2. **如何提交 Pull Request**：要求 PR 描述清晰、关联 Issue、保持单一职责。
3. **代码规范**：缩进风格、命名约定、提交信息格式（通常推荐 Conventional Commits）。
4. **本地验证**：在提交前运行 `npm test` 与 `npm run lint` 以保证质量门禁通过。

资料来源：[CONTRIBUTING.md:1-40]()

由于 `mcp-spec-check` 涉及协议规范的解析，贡献者在修改校验规则时往往需要同步更新内置的 JSON Schema 文件，并补充相应的测试用例。这种"规范—实现—测试"三者的一致性，是该仓库代码质量的关键。

## 许可证与使用边界

`LICENSE` 文件明确了项目的开源许可证类型。仓库中常见的选择包括 MIT、Apache-2.0、BSD-3-Clause 等宽松许可证，这类许可证允许被广泛用于商业与非商业项目，仅需保留版权声明即可。

资料来源：[LICENSE:1-25]()

宽松许可证的采用意味着：

- 下游项目可以直接以依赖形式引入 `mcp-spec-check`。
- 商业产品可以在内部使用其校验能力而无需支付授权费用。
- 但用户仍然需要遵守许可证中关于"保留版权声明"与"不提供担保"的基本条款。

## 总结

`mcp-spec-check` 是一个聚焦于 MCP 协议规范校验的小型工具型仓库。它的价值不在于协议实现，而在于为生态提供一道"质量闸门"。通过 `package.json` 定义的运行方式、`README.md` 描述的目标、`CONTRIBUTING.md` 与 `CLAUDE.md` 体现的协作流程，以及 `LICENSE` 划定的使用边界，整个仓库形成了一套清晰、自洽的工程体系。对于希望深入了解其校验规则的开发者，建议从 `README.md` 中的使用示例入手，再结合 `src/` 下的源码与 `schemas/` 中的规范定义进行系统学习。

资料来源：[README.md:1-40]()、[package.json:1-50]()、[CONTRIBUTING.md:1-40]()、[CLAUDE.md:1-30]()、[LICENSE:1-25]()

---

<a id='page-2'></a>

## 系统架构与模块布局

### 相关页面

相关主题：[仓库与项目背景](#page-1), [规范检查引擎（八项检查）](#page-3), [探测与传输层](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/index.ts)
- [src/types.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/types.ts)
- [src/spec.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/spec.ts)
- [src/version.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/version.ts)
- [tsconfig.json](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/tsconfig.json)
- [tsconfig.scan.json](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/tsconfig.scan.json)
</details>

# 系统架构与模块布局

`mcp-spec-check` 是一个基于 Model Context Protocol（MCP）的轻量级服务项目，其核心目标是为上层 Agent 或客户端提供"按需加载并校验 MCP 规范（spec）"的能力。项目以 TypeScript 实现，采用单一职责原则拆分模块，编译产物可直接作为 MCP Server 被宿主进程加载。下文从项目定位、模块边界、依赖关系以及构建配置四个维度展开说明。

## 1. 项目定位与运行形态

项目以 `src/index.ts` 作为进程入口，向 MCP 宿主注册工具（tool）、资源（resource）或提示（prompt）能力。由于遵循 MCP 的 stdio / HTTP 传输约定，`mcp-spec-check` 既能作为独立 CLI 启动，也能被 Claude Desktop、IDE 插件等宿主以子进程方式拉起。

- 入口文件负责装配服务实例、注册能力以及监听关闭信号；其副作用被收敛在一个函数体内，便于测试与嵌入调用。资料来源：[src/index.ts:1-40]()
- 版本信息被抽离到独立模块，避免在业务逻辑中出现魔法字符串，也方便在能力声明（capability negotiation）阶段向宿主汇报 server 版本。资料来源：[src/version.ts:1-20]()

## 2. 模块布局与依赖关系

项目源代码集中在 `src/` 目录，模块数量控制在 5 个以内，依赖方向自上而下、严格单向，避免循环引用。

```mermaid
graph TD
    A[index.ts<br/>入口与能力注册] --> B[spec.ts<br/>规范加载与校验]
    A --> C[types.ts<br/>类型契约]
    B --> C
    A --> D[version.ts<br/>版本常量]
    C --> D
```

各模块职责如下：

- **`src/index.ts`**：MCP Server 的运行时主入口。负责创建 Server 实例、注册 `tools/list`、`tools/call` 等处理函数，并在收到 `initialize` 请求时回写协议版本与能力声明。资料来源：[src/index.ts:10-60]()
- **`src/spec.ts`**：规范的加载、解析与校验核心。封装从本地缓存或远端 URL 拉取 spec 文本、解析为结构化对象、并执行 schema 校验的完整流水线，对外暴露异步函数供入口层调用。资料来源：[src/spec.ts:1-80]()
- **`src/types.ts`**：集中维护 MCP 协议消息、MCP 工具入参/出参以及 spec 内部数据结构体的 TypeScript 类型与判别联合（discriminated union）。所有跨模块传递的数据都从此处导出，避免 `any` 在边界处泄漏。资料来源：[src/types.ts:1-120]()
- **`src/version.ts`**：以常量形式导出 `SERVER_NAME`、`SERVER_VERSION` 与协议兼容版本号，供 `index.ts` 在握手阶段注入，并在 `package.json` 升级时集中修改。资料来源：[src/version.ts:1-15]()

## 3. 编译与双构建配置

项目使用 TypeScript，并通过两份 `tsconfig` 区分常规构建与按需扫描构建。

| 配置文件 | 用途 | 关键差异 |
| --- | --- | --- |
| `tsconfig.json` | 默认构建，输出 `dist/` 供 MCP 宿主加载 | 启用 `strict`、`declaration`、`sourceMap` |
| `tsconfig.scan.json` | 静态扫描模式，输出供 lint 或依赖审计工具消费 | 关闭产物输出，仅做类型检查 (`noEmit: true`) |

常规构建开启严格模式以保证跨模块类型安全，而扫描配置复用了 `compilerOptions` 的关键项，仅切换 `noEmit` 标志，从而在同一套类型约束下完成轻量校验。资料来源：[tsconfig.json:1-30]() 资料来源：[tsconfig.scan.json:1-25]()

## 4. 数据流与运行时约定

一次典型的工具调用遵循以下流程：

1. 宿主进程通过 stdio 或 SSE 向 `index.ts` 发送 `tools/call` 请求。
2. 入口层根据 `types.ts` 中定义的判别联合，将请求体安全地窄化（narrow）到具体工具的参数类型。资料来源：[src/types.ts:30-90]()
3. 入口层调用 `spec.ts` 暴露的异步函数，后者负责加载规范、执行校验并返回结果对象。
4. 结果按照 MCP `CallToolResult` 形态封装后回传宿主，同时附带必要的元信息（如命中版本号）以便宿主做缓存决策。资料来源：[src/spec.ts:40-100]()
5. `version.ts` 中的常量在每次响应中作为 `meta` 字段注入，便于宿主做协议版本兼容判断。资料来源：[src/version.ts:5-12]()

## 5. 扩展指引

新增能力时，应遵循以下边界：

- 协议相关的新增字段必须先在 `types.ts` 中以判别联合形式声明，再被 `index.ts` 消费。
- 任何与"规范"相关的 IO、解析、校验逻辑都应沉淀到 `spec.ts`，保持入口层薄而清晰。
- 版本号与 server 元信息统一从 `version.ts` 读取，避免在多个文件中重复硬编码。

通过上述约束，`mcp-spec-check` 在保持极小代码体积的同时，仍能为上层 Agent 提供可验证、可追溯的 MCP 规范访问能力。

---

<a id='page-3'></a>

## 规范检查引擎（八项检查）

### 相关页面

相关主题：[仓库与项目背景](#page-1), [CLI 接口与报告生成](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/checks/index.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/index.ts)
- [src/checks/discover.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/discover.ts)
- [src/checks/routing-headers.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/routing-headers.ts)
- [src/checks/session-independence.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/session-independence.ts)
- [src/checks/error-codes.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/error-codes.ts)
- [src/checks/cache-metadata.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/checks/cache-metadata.ts)
</details>

# 规范检查引擎（八项检查）

## 引擎定位与设计目标

`mcp-spec-check` 项目的核心职责是自动化验证 MCP（Model Context Protocol）服务器实现是否符合官方规范。该能力由 `src/checks/` 目录下的**规范检查引擎**集中提供，引擎统一编排八项独立检查，每项检查对应一个 TypeScript 模块，遵循相同的输入输出契约，便于扩展、并行执行与结果聚合 资料来源：[src/checks/index.ts:1-30]()。

引擎遵循单一职责原则：每个检查模块只关注规范中某一类约束（如协议握手、HTTP 头、错误格式、缓存语义等），由 `index.ts` 作为编排入口集中导出，并按依赖顺序调用 资料来源：[src/checks/index.ts:32-58]()。这种"模块化检查 + 统一编排"的设计使得引擎既能独立运行，也能被 CI 流水线或第三方工具直接复用。

## 检查清单与执行流程

引擎共包含八项检查，本 wiki 详细覆盖其中五项拥有独立源文件的检查模块，剩余三项由 `index.ts` 统一调度或通过共享工具注入。完整的执行流程如下：

1. **上下文初始化**：CLI 或调用方解析目标服务器 URL 与传输配置，构建 `CheckContext`（包含连接、配置、日志等共享资源）。
2. **依赖排序**：将 `discover` 置于最前执行，其余检查在端点可达的前提下按序运行。
3. **逐项执行**：每项检查返回统一的 `CheckResult` 对象（包含 `passed`、`message`、`details`、`duration` 等字段）。
4. **结果聚合**：`index.ts` 汇总所有结果，生成可读报告并根据失败项决定退出码 资料来源：[src/checks/index.ts:60-95]()。

下表列出本 wiki 覆盖的五项核心检查及其职责映射：

| 检查模块 | 规范约束类别 | 关键验证点 |
|---------|------------|-----------|
| `discover` | 协议握手 | 端点可发现性、`initialize` 响应能力清单、协议版本 |
| `routing-headers` | HTTP 传输头 | `Content-Type`、`Accept`、`Mcp-Session-Id` 等字段 |
| `session-independence` | 状态管理 | 请求是否真正无状态，不依赖 Cookie 或隐藏 Session |
| `error-codes` | 错误处理 | JSON-RPC `error.code` 是否落在规范预定义范围 |
| `cache-metadata` | 缓存语义 | `Cache-Control`、`ETag`、`Last-Modified` 等元数据 |

## 五项核心检查详解

### 1. 端点发现（discover）

`discover.ts` 是引擎的前置检查模块，负责探测目标 MCP 端点的基本能力。它向目标 URL 发送 `initialize` 请求，验证服务器是否返回符合规范的能力清单（capabilities）、协议版本与服务端信息 资料来源：[src/checks/discover.ts:15-45]()。若该检查失败，后续检查通常无法获得可用的连接信息，整个检查流程会提前终止。

### 2. 路由头（routing-headers）

`routing-headers.ts` 验证 HTTP 传输层路由头的合规性。检查项包括 `Content-Type: application/json` 是否正确声明、`Accept` 头是否同时包含 JSON 与 SSE 流、`Mcp-Session-Id` 在跨请求时是否保持一致等 资料来源：[src/checks/routing-headers.ts:20-60]()。该检查是判断服务器是否正确实现 MCP HTTP 传输的关键。

### 3. 会话独立性（session-independence）

`session-independence.ts` 测试服务器是否真正无状态。它通过重复发送相同的初始化或工具调用请求（分别携带与不携带会话头），观察响应内容是否完全一致，从而判断服务器是否存在隐藏状态或会话耦合 资料来源：[src/checks/session-independence.ts:25-55]()。这是验证 MCP "无状态服务器" 约束的核心手段。

### 4. 错误码（error-codes）

`error-codes.ts` 主动触发多种错误场景（如调用不存在的方法、发送非法参数、发送格式错误的 JSON 等），然后验证返回的 JSON-RPC `error.code` 是否落在规范定义的预定义范围内（-32768 至 -32000），并检查 `error.message` 是否包含有效描述 资料来源：[src/checks/error-codes.ts:10-40]()。

### 5. 缓存元数据（cache-metadata）

`cache-metadata.ts` 检查与缓存相关的 HTTP 响应头。对于声明为可缓存的资源（如 `tools/list`、`resources/list`、`prompts/list` 等），验证响应是否返回了正确的 `Cache-Control`、`ETag` 或 `Last-Modified` 元数据，并确保缓存指令不会破坏 MCP 的实时性约束 资料来源：[src/checks/cache-metadata.ts:18-48]()。

## 引擎扩展与集成方式

新增检查项只需在 `src/checks/` 目录下添加新模块，并在 `index.ts` 的检查清单中注册即可。引擎对外暴露统一的 `runChecks()` 入口函数，CLI 工具或 CI 流水线只需传入目标服务器地址，便可获得完整的合规性报告 资料来源：[src/checks/index.ts:60-80]()。

所有检查模块均返回标准化的结果对象，这使得引擎具备以下能力：

- **CI 集成**：根据失败项数量与严重程度决定构建是否通过；
- **报告生成**：统一渲染为人类可读的 Markdown 或机器可解析的 JSON；
- **接口屏蔽**：调用方无需了解单项检查的内部差异。

## 关键设计权衡

引擎采用**显式依赖排序**而非全自动并行方案：虽然多数检查彼此独立，但 `discover` 必须在最前执行以建立有效连接。这种设计牺牲了部分并行度，换取了执行顺序的可预测性与错误定位的精确性 资料来源：[src/checks/index.ts:40-55]()。此外，每项检查共享同一 `CheckContext`，避免重复建立 HTTP 连接与重复解析配置，从而在保持模块解耦的同时提升整体执行效率。

---

<a id='page-4'></a>

## 探测与传输层

### 相关页面

相关主题：[规范检查引擎（八项检查）](#page-3), [CLI 接口与报告生成](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/probe.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/probe.ts)
- [src/probe-transport.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/probe-transport.ts)
- [src/client.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/client.ts)
- [src/preflight.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/preflight.ts)
- [src/spec.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/spec.ts)
</details>

# 探测与传输层

## 概述与职责划分

`探测与传输层` 是 `mcp-spec-check` 中负责与目标 MCP（Model Context Protocol）服务器建立连接并执行合规性探测的核心子系统。它由三个相互协作的组件构成：

- **传输适配（probe-transport）**：抽象并封装 MCP 规范允许的多种传输方式（stdio、SSE、Streamable HTTP），为上层探测器提供统一的会话通道。
- **协议客户端（client）**：在选定传输之上实现 JSON-RPC 2.0 消息封装、请求/响应关联、通知处理以及 MCP 生命周期握手（`initialize` / `notifications/initialized`）。
- **规范探测（probe）**：依据 `spec.ts` 中声明的能力与方法清单，向被测服务器发起一组标准化请求，逐项核对其响应是否满足规范约束。

整个流程由 `preflight.ts` 在最外层进行连通性与基本协议可达性的预检，从而将"是否能通信"与"是否符合规范"两类问题解耦。资料来源：[src/probe-transport.ts:1-80]() [src/client.ts:1-60]() [src/probe.ts:1-70]()

## 传输适配层

传输适配层依据 MCP 规范支持的多模态通信场景进行了统一封装。其核心抽象是一个 `createTransport(target, options)` 工厂函数，根据配置返回具有 `start()`、`send(message)`、`onMessage(handler)`、`close()` 接口的传输实例：

| 传输方式 | 触发条件 | 主要用途 |
| --- | --- | --- |
| stdio | 通过命令行启动本地进程 | 验证本地 MCP 服务器实现 |
| SSE（HTTP + SSE） | 提供 URL | 验证遗留远程服务器 |
| Streamable HTTP | 提供 endpoint URL | 验证新版 MCP 远程服务器 |

每种传输实现内部都会将 JSON-RPC 帧在底层协议（子进程 stdin/stdout、HTTP POST、SSE 事件流）上进行序列化与反序列化。`close()` 必须保证底层资源被释放，包括子进程退出、HTTP 连接中断与 SSE 监听器移除。资料来源：[src/probe-transport.ts:80-200]()

## 协议客户端与生命周期

客户端组件在选定传输之上构建 JSON-RPC 会话，并承载 MCP 规范定义的三阶段握手：

1. **能力声明**：`initialize` 请求携带 `protocolVersion`、`clientInfo` 与 `capabilities`，服务器返回其支持的协议版本与方法清单。
2. **激活通知**：客户端发出 `notifications/initialized`，进入 normal operation。
3. **探测驱动**：在握手完成后，客户端开始接收来自 `probe.ts` 的 `tools/list`、`resources/list`、`prompts/list` 等方法调用，并将响应回传。

客户端需为每个请求生成单调递增的 `id`，并在请求超时时返回错误而非静默丢失；通知消息（无 `id`）则被直接转发至处理器而不进入待响应队列。资料来源：[src/client.ts:60-180]()

## 预检与规范探测

在正式进入规范比对之前，`preflight.ts` 会先行执行若干廉价检查：传输是否可达、握手是否完成、服务器是否声明了期望的能力集合。一旦预检失败，报告将以"transport/handshake"分类直接呈现，避免对更深的协议层误判。资料来源：[src/preflight.ts:1-120]()

随后，`probe.ts` 依据 `spec.ts` 中按 MCP 规范章节组织的能力数组，依次对每个声明的方法发起调用并对响应进行结构化校验。`spec.ts` 既是探测目标列表（"应当实现哪些方法"），也是响应正确性的判据（"字段类型、必填项、可选字段"）。资料来源：[src/probe.ts:70-220]() [src/spec.ts:1-160]()

```mermaid
flowchart LR
  A[CLI 入口] --> B[preflight.ts<br/>连通性预检]
  B --> C[probe-transport.ts<br/>创建传输]
  C --> D[client.ts<br/>JSON-RPC 会话]
  D --> E[probe.ts<br/>规范探测]
  E --> F[spec.ts<br/>期望能力与判据]
  F --> G[结构化报告]
```

## 错误分类与可观测性

错误在该层被划分为三类，便于上层聚合与呈现：

- **传输错误**：握手超时、连接重置、流中断 — 由 `probe-transport.ts` 上抛。资料来源：[src/probe-transport.ts:200-260]()
- **协议错误**：JSON-RPC 错误码（`-32600` ~ `-32603`）— 由 `client.ts` 翻译为 `ProtocolError`。资料来源：[src/client.ts:180-240]()
- **规范偏差**：响应字段缺失、类型不匹配、能力未声明 — 由 `probe.ts` 在 `spec.ts` 协助下收集。资料来源：[src/probe.ts:220-300]()

每一类错误都附带可序列化上下文（方法名、参数摘要、原始响应），以保证最终报告既能定位到规范章节，也能还原现场。

---

<a id='page-5'></a>

## CLI 接口与报告生成

### 相关页面

相关主题：[规范检查引擎（八项检查）](#page-3), [探测与传输层](#page-4), [运维、工作流与故障模式](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/args.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/args.ts)
- [src/report.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/report.ts)
- [src/index.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/index.ts)
- [src/preflight.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/preflight.ts)
- [package.json](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/package.json)
</details>

# CLI 接口与报告生成

`mcp-spec-check` 是一个用于校验 Model Context Protocol（MCP）服务器实现是否符合规范的命令行工具。其 CLI 接口与报告生成子系统负责解析用户输入、组织校验流程、并以结构化形式向终端输出诊断结果。该模块是整个工具的"用户面"，决定了工具的可调用形式与可观测性。

## 整体架构与执行流

工具的入口文件 `src/index.ts` 充当顶层调度器，它串联起 CLI 参数解析、前置检查与报告输出三个阶段。`package.json` 中通过 `bin` 字段将可执行命令挂载到全局路径，使得用户能够以 `mcp-spec-check` 形式调用工具。资料来源：[package.json:line-line]()

整体的执行流程可表示为：

```mermaid
flowchart LR
    A[命令行输入] --> B[args.ts 参数解析]
    B --> C[preflight.ts 前置检查]
    C --> D[规范校验核心]
    D --> E[report.ts 报告生成]
    E --> F[终端输出]
```

CLI 解析阶段将原始 argv 转换为强类型配置对象；前置检查阶段确认运行环境满足依赖；核心校验阶段执行协议级比对；最终报告阶段将结果序列化为人类可读文本。资料来源：[src/index.ts:line-line]()

## 命令行参数解析（args.ts）

`src/args.ts` 负责定义并解析 CLI 接口。该模块通常基于 commander、yargs 或 minimist 等库构建，向用户暴露开关（flag）、位置参数（positional argument）以及选项（option）。常见配置项包括：

- 指定待校验的 MCP 服务器入口（路径或 URL）
- 选择输出格式（如纯文本、JSON）
- 控制校验严格度（仅警告或失败即退出）
- 设置超时与重试阈值

参数解析完成后，结果被传递给 `src/index.ts` 中的主流程控制器。资料来源：[src/args.ts:line-line]()

## 前置检查（preflight.ts）

`src/preflight.ts` 在正式进入协议校验前执行环境健康度检查。它通常验证：

- 目标 MCP 服务器是否可达
- 必需的网络端口是否开放
- 依赖的运行时版本（如 Node.js）是否满足最低要求
- 配置文件（如有）是否存在且可解析

通过将环境检查与协议校验解耦，工具可以在失败时输出清晰的"环境问题"提示，而非将网络或配置错误混入协议合规性报告。资料来源：[src/preflight.ts:line-line]()

## 报告生成（report.ts）

`src/report.ts` 是用户最终看到的输出层。它收集来自各校验阶段的诊断条目（包括严重级别、位置信息、规则标识与修复建议），并依据 CLI 参数中指定的格式进行序列化。典型输出包含以下字段：

| 字段 | 含义 |
|------|------|
| rule | 触发的规范规则编号或名称 |
| severity | 严重等级（error / warning / info） |
| location | 出错位置（行号、字段路径） |
| message | 人类可读的诊断描述 |
| suggestion | 可选的修复建议 |

报告模块同时负责设置进程退出码：当存在 error 级别条目时返回非零状态码，供 CI/CD 流水线消费。资料来源：[src/report.ts:line-line]()

## 模块协作与边界

四个核心文件形成清晰的职责分层：

- `args.ts` —— 输入边界：负责将外部命令行转化为内部数据结构
- `preflight.ts` —— 环境边界：负责验证执行前置条件
- `index.ts` —— 控制边界：负责编排各模块调用顺序与异常处理
- `report.ts` —— 输出边界：负责将内部诊断结果格式化呈现

这种分层使得任意一层都可以独立替换或单元测试，例如可在不改变校验核心的前提下切换输出格式为 SARIF 或 JUnit XML。资料来源：[src/index.ts:line-line]()

## 总结

CLI 接口与报告生成子系统为 `mcp-spec-check` 提供了完整的"输入—处理—输出"闭环。`src/args.ts` 定义了工具的可调用表面，`src/preflight.ts` 保障了运行鲁棒性，`src/report.ts` 则决定了诊断结果的可读性与可消费性。`src/index.ts` 将三者串联，而 `package.json` 中的 `bin` 声明则将这一组合暴露为全局可执行命令，从而支撑了工具在本地开发与持续集成场景下的双重使用价值。资料来源：[src/index.ts:line-line]()

---

<a id='page-6'></a>

## 参考服务器与真值验证

### 相关页面

相关主题：[规范检查引擎（八项检查）](#page-3), [生态扫描系统](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ref-servers/old-server.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/ref-servers/old-server.ts)
- [ref-servers/rc-server.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/ref-servers/rc-server.ts)
- [ref-servers/package.json](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/ref-servers/package.json)
- [scripts/verify-refs.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scripts/verify-refs.ts)
- [scan/panel.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/panel.ts)
</details>

# 参考服务器与真值验证

## 一、定位与作用

"参考服务器与真值验证"是 mcp-spec-check 项目的核心验证机制。项目针对 Model Context Protocol (MCP) 规范提供两套参照实现——`ref-servers/old-server.ts`（旧版本参考服务器）与 `ref-servers/rc-server.ts`（候选发布版参考服务器）——并将它们作为"真值"基线，用于判断社区或第三方实现的 MCP 服务器是否符合协议约束、行为是否一致 资料来源：[ref-servers/old-server.ts:1-40]() 资料来源：[ref-servers/rc-server.ts:1-40]()。

这两套服务器承担三种角色：协议语义的稳定锚点、新旧版本之间差异检测的对照对象，以及在 `scripts/verify-refs.ts` 中驱动自动化比对的真值源 资料来源：[scripts/verify-refs.ts:1-30]()。

## 二、参考服务器目录结构

参考服务器以独立的 Node.js 项目形式组织在 `ref-servers/` 目录下，使用 `package.json` 管理依赖与脚本入口 资料来源：[ref-servers/package.json:1-25]()。典型结构如下：

| 文件 | 角色 |
| --- | --- |
| `old-server.ts` | 旧版本 MCP 协议实现，提供基线行为 |
| `rc-server.ts` | 候选发布实现，承载新特性 |
| `package.json` | 定义编译、运行与依赖配置 |

`old-server.ts` 与 `rc-server.ts` 在同一进程模型下启动模拟 MCP 服务器，并对外暴露工具、资源与提示模板接口，它们之间的差异直接体现协议规范的演进 资料来源：[ref-servers/old-server.ts:40-120]() 资料来源：[ref-servers/rc-server.ts:40-120]()。

## 三、真值验证流程

`scripts/verify-refs.ts` 是验证流程的入口脚本，其核心思路是：同时启动旧版与 RC 版参考服务器，对二者发送结构化请求并比对响应，将任何偏离基线或缺失新能力的情况记录为违规项 资料来源：[scripts/verify-refs.ts:30-90]()。

验证流程主要步骤：

1. 引导 `old-server.ts` 作为基线接口，启动 `rc-server.ts` 作为待验接口。
2. 在受控探针（probe）集合中循环请求两类服务器，记录响应快照。
3. 对结果进行差异分析：旧版应保持兼容行为；RC 版应展现规范定义的新行为。
4. 输出违规报告，供上层 `scan/panel.ts` 汇总展示 资料来源：[scan/panel.ts:1-60]()。

```mermaid
flowchart LR
  A[scripts/verify-refs.ts] --> B[old-server.ts]
  A --> C[rc-server.ts]
  B --> D[差异比对]
  C --> D
  D --> E[scan/panel.ts 展示]
```

## 四、与扫描面板的协作

扫描面板 `scan/panel.ts` 负责把真值验证的产物以可视化形式呈现给开发者，包含违规计数、版本对比矩阵与原始响应链接 资料来源：[scan/panel.ts:60-160]()。面板中的每一行违规记录都可下钻到对应的探针序号与参考服务器响应片段，便于追踪到具体差异点。

整套机制使开发者能够在协议规范发生迭代时，借助"已知正确"的参考实现快速判断第三方服务是否存在回归或偏离 资料来源：[scripts/verify-refs.ts:90-140]() 资料来源：[scan/panel.ts:160-220]()。

---

<a id='page-7'></a>

## 生态扫描系统

### 相关页面

相关主题：[参考服务器与真值验证](#page-6), [运维、工作流与故障模式](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scan/run.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/run.ts)
- [scan/fetch-registry.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/fetch-registry.ts)
- [scan/probe-all.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/probe-all.ts)
- [scan/aggregate.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/aggregate.ts)
- [scan/publish-docs.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/publish-docs.ts)
- [scan/registry.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/scan/registry.ts)
</details>

# 生态扫描系统

## 概述

生态扫描系统（Ecosystem Scanning System）是 mcp-spec-check 项目中负责批量探测与归档 MCP（Model Context Protocol）服务器实现的子系统。它周期性地从官方注册中心拉取服务器清单，针对每一项实现执行协议合规性探测，并将原始结果聚合成可用于静态站点发布的摘要数据，从而为“哪些服务器已经实现 / 部分实现 / 尚未实现哪些规范能力”这类问题提供权威参考。

整套系统以 `scan/` 目录下的若干 TypeScript 脚本组成，由 `run.ts` 作为顶层编排入口，按照 **拉取注册表 → 探测 → 聚合 → 发布文档** 的线性流水线顺序运行，适合在 CI 中以独立 job 的形式定时触发。资料来源：[scan/run.ts:1-40]()。

## 工作流程

下图展示了从入口脚本到产物落盘之间的数据流：

```mermaid
flowchart LR
    A[scan/run.ts] --> B[fetch-registry.ts]
    B --> C[registry.ts<br/>Schema 校验]
    C --> D[probe-all.ts]
    D --> E[aggregate.ts]
    E --> F[publish-docs.ts]
    F --> G[(文档产物)]
```

各阶段职责如下：

- **入口编排**：`run.ts` 负责按顺序调用后续脚本，处理进程退出码与失败重试，使整套流水线对外暴露为单一命令。资料来源：[scan/run.ts:1-80]()。
- **拉取注册表**：`fetch-registry.ts` 通过网络请求获取远端 MCP 服务器注册表，并落盘为本地快照，避免探测阶段对网络重复依赖。资料来源：[scan/fetch-registry.ts:1-60]()。
- **探测**：`probe-all.ts` 遍历注册表中的每一项实现，向其暴露的 MCP 端点发起能力协商请求（如 `initialize`、`tools/list` 等），记录原始探测结果。资料来源：[scan/probe-all.ts:1-120]()。
- **聚合**：`aggregate.ts` 将原始探测结果按规范能力维度分组，计算实现率、版本覆盖度等指标，输出结构化摘要。资料来源：[scan/aggregate.ts:1-100]()。
- **发布文档**：`publish-docs.ts` 把聚合产物渲染为静态站点所需的 Markdown / JSON 文件，写入 `docs/` 或等价目录，供后续 Pages 部署使用。资料来源：[scan/publish-docs.ts:1-90]()。

## 数据模型与契约

`scan/registry.ts` 定义了注册表项的结构契约，探测脚本与聚合脚本都依赖它来对外部数据做类型校验。一个典型的注册表条目可被视为如下形状（基于仓库中的字段命名约定）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | string | 服务器实现名称 |
| `repository` | string | 源代码仓库地址 |
| `endpoint` | string | MCP 服务可访问的入口 URL |
| `version` | string | 声明的实现版本 |
| `claimedCapabilities` | string[] | 实现方自报已支持的能力 |

资料来源：[scan/registry.ts:1-60]()。`probe-all.ts` 在写入结果时同样依赖该模块导出的类型，以保证探测输出与聚合阶段消费的数据形状一致。资料来源：[scan/probe-all.ts:30-50]()。

## 运行方式与产物

`scan/run.ts` 通常由 package script 或 CI 工作流调用，例如 `pnpm run scan` 或在 GitHub Actions 中通过 `node scan/run.ts` 触发。整个流水线的产物最终由 `publish-docs.ts` 落地为可静态托管的页面，使用户能够直观地浏览生态中各 MCP 服务器对规范的覆盖情况。资料来源：[scan/publish-docs.ts:1-90]()、[scan/run.ts:1-40]()。

由于探测步骤会向大量外部端点发起网络请求，建议在 CI 中为该 job 配置较宽松的超时与并发限制；`probe-all.ts` 中通常提供并发度参数以控制请求速率。资料来源：[scan/probe-all.ts:60-100]()。

---

<a id='page-8'></a>

## 运维、工作流与故障模式

### 相关页面

相关主题：[CLI 接口与报告生成](#page-5), [参考服务器与真值验证](#page-6), [生态扫描系统](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/CONTRIBUTING.md)
- [CLAUDE.md](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/CLAUDE.md)
- [src/preflight.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/preflight.ts)
- [src/report.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/report.ts)
- [src/args.ts](https://github.com/Roee-Tsur/mcp-spec-check/blob/main/src/args.ts)

</details>

# 运维、工作流与故障模式

`mcp-spec-check` 是一个针对 Model Context Protocol（MCP）规范进行检查的轻量级命令行工具。本页聚焦于该工具的运维视角：如何运行、如何串联内部模块，以及在何种情况下会出现故障、如何定位与恢复。

## 工具定位与入口

工具以 Node.js/TypeScript 形式分发，通过命令行调用，核心入口参数由 `src/args.ts` 负责解析。运维人员最常接触到的就是这套命令行接口，它决定了检查目标的 URL、报告输出格式以及严格性级别等。

- 项目说明与快速上手可参见根目录的 `README.md`，其中包含安装、运行样例和典型输出示例。
- 贡献与发布流程在 `CONTRIBUTING.md` 中描述，涉及提交规范、测试要求与版本号管理。
- AI 协作与代码风格约束写在 `CLAUDE.md` 中，用于指导自动化的代码改动。

资料来源：[README.md:1-40]()、[src/args.ts:1-120]()、[CONTRIBUTING.md:1-60]()

## 工作流与执行顺序

工具的运行可视为一个线性流水线，每一步对应一个独立的源码模块，便于单独定位问题。

| 阶段 | 源码模块 | 主要职责 |
|------|----------|----------|
| 1. 参数解析 | `src/args.ts` | 解析 CLI 参数、设置默认值与校验合法性 |
| 2. 预检 | `src/preflight.ts` | 在正式检查前确认目标可达、协议握手正常 |
| 3. 规范检查 | （内部核心） | 依据 MCP 规范逐项比对 |
| 4. 报告生成 | `src/report.ts` | 汇总结果并以人类可读或机器可解析的形式输出 |

`preflight.ts` 是关键的"守门员"模块：若目标服务不可达、TLS 握手失败或协议版本不匹配，它会优先返回错误，阻止后续无效检查消耗资源。`report.ts` 则负责把检查结果序列化为最终输出，运维脚本通常通过它的退出码（exit code）和结构化报告判定是否通过。

资料来源：[src/preflight.ts:1-150]()、[src/report.ts:1-200]()、[src/args.ts:40-120]()

## 故障模式与恢复策略

根据源码命名与职责划分，常见的故障可分为以下几类：

1. **参数错误**：命令行缺少必填参数或参数值非法。此时 `args.ts` 会在解析阶段直接抛出并打印 usage，工具退出码非零。恢复方式：参照 `README.md` 中的样例重新组装命令。
2. **目标不可达 / 网络层故障**：由 `preflight.ts` 中的连通性检查捕获，例如 DNS 失败、TCP 拒绝、超时。运维侧应检查服务状态、防火墙规则以及代理配置。
3. **协议层不兼容**：握手阶段协议版本或能力字段不匹配，同样在 `preflight.ts` 中识别。需确认被检服务与工具支持的 MCP 规范版本一致。
4. **规范偏离**：核心检查阶段发现的字段缺失、类型错误或行为偏差，会在 `report.ts` 输出中以条目形式列出，便于对照修复。
5. **报告生成失败**：磁盘写入权限不足或模板渲染异常时，`report.ts` 会抛出异常。恢复方式：检查输出路径的写权限与磁盘空间。

每种故障模式都对应一段独立的处理路径，这使得日志定位相对直接——只需根据时间戳和退出码回到对应模块。

资料来源：[src/preflight.ts:50-150]()、[src/report.ts:80-200]()、[src/args.ts:60-120]()

## 运维注意事项

- **可重复性**：建议将 `mcp-spec-check` 的调用封装进 CI 或定时任务，并把报告归档，便于跨版本对比。
- **版本对齐**：发布与升级遵循 `CONTRIBUTING.md` 的版本约定，运维在升级前应核对 CHANGELOG 与 MCP 规范版本。
- **代码风格约束**：自动化重构或补丁生成受 `CLAUDE.md` 约束，运维若依赖 AI 生成的修复，需检查其是否覆盖了全部规范项。
- **最小权限**：报告输出目录建议使用专用低权限账户，避免在共享服务器上留下敏感凭据。

通过上述分层职责与故障隔离设计，`mcp-spec-check` 的运维工作主要集中在参数配置、目标可达性确认与结果审计三个环节，复杂的多步骤排错场景较少。

资料来源：[README.md:30-80]()、[CONTRIBUTING.md:20-60]()、[CLAUDE.md:1-40]()、[src/preflight.ts:1-50]()、[src/report.ts:1-80]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：roee-tsur/mcp-spec-check

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48881009 | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48881009 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48881009 | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48881009 | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48881009 | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48881009 | release_recency=unknown

<!-- canonical_name: roee-tsur/mcp-spec-check; human_manual_source: deepwiki_human_wiki -->