MCP Servers 参考仓库贡献指南：接收边界、Vitest 测试规范与协议特性展示实战

本文围绕 MCP Servers（modelcontextprotocol/servers）仓库的 CONTRIBUTING.md 展开，梳理该参考服务器仓库如何接收社区贡献：哪些改动会被欢迎、哪些需要谨慎评审、哪些一律不接受，以及 TypeScript 服务器强制使用 Vitest 的测试规范。结合仓库中的 vitest 配置、文件服务器 Roots 实现与 Everything 服务器的注册测试等源码证据，读完你可以明确一条贡献 PR 的可行性边界，并知道如何为参考服务器提交一个符合仓库惯例、可直接跑通测试的改动。

一、先弄清这个仓库的定位：参考实现，而非生产服务

在讨论贡献之前，必须明确 README.md 中对仓库性质的两条定性，这直接决定了贡献的评审尺度：

• 本仓库是 Model Context Protocol（MCP）的参考实现集合（reference implementations），只保留由 MCP 指导小组维护的少数几个参考服务器，其定位是"为开发者构建自己的 MCP 服务器提供教学示例"，而不是生产就绪方案；
• 仓库曾维护的第三方服务器列表已被退役，浏览与发布服务器统一迁移到了 MCP Server Registry（registry.modelcontextprotocol.io）。

从仓库结构看，根目录 package.json 使用 npm workspaces（"workspaces": ["src/*"]）聚合各语言服务器，并提供 build、publish-all、link-all 等聚合脚本；src/ 下当前活跃的参考服务器包括 Everything、Fetch、Filesystem、Git、Memory、Sequential Thinking、Time 七个，Python 服务器（fetch、git、time）各自独立维护 pyproject.toml，TypeScript 服务器（everything、filesystem、memory、sequentialthinking）则统一采用 TypeScript + Vitest 的技术栈。

CONTRIBUTING.md 说明仓库采用标准的 GitHub Flow 模型接收变更——即从主分支拉取 feature 分支、提交 PR、评审合并的标准流程。理解了"参考实现"这一定位后，下文三级贡献标准的取向就容易理解了：仓库更希望代码库持续演示协议能力，而不是变成一个功能杂物间。

二、服务器列表退役：新服务器不再进 README，而是发布到 MCP Server Registry

CONTRIBUTING.md 的 "Server Listings" 一节明确：README 不再包含第三方 MCP 服务器列表，该列表已被退役，改为指向 MCP Server Registry。如果你想让自己的服务器被发现，正确路径是按 Registry 的 quickstart 指南把你的服务器发布上去，而不是往本仓库的 README 里加一行链接。

这一点在 README.md 中以醒目的 IMPORTANT 提示相互印证："如果你在找 MCP 服务器列表，去 MCP Registry 浏览已发布的服务器；本仓库只容纳指导小组维护的少量参考服务器。" 对贡献者的实际含义是："帮我把服务器加进列表"这类 PR 已经不符合仓库目标，Registry 才是发现机制。已归档的服务器（GitHub、GitLab、Google Drive、PostgreSQL、SQLite 等）则移入了独立的 servers-archived 仓库，README 中仅保留索引链接。

三、三级贡献标准：欢迎、谨慎评审与不接受

CONTRIBUTING.md 的 "Server Implementations" 一节给出了清晰的三层标准，这是本文的核心。

3.1 欢迎的贡献（We welcome）

1. Bug fixes — 修复现有参考服务器的缺陷；
2. Usability improvements — 让人类和 Agent 都更容易使用这些服务器；
3. 展示 MCP 协议特性的增强 — 这是仓库最鼓励的一类。参考服务器应当更好地演示除 Tools 之外被低估的协议能力，例如 Resources、Prompts、Roots。文档给出了一个具体示例：给 filesystem-server 增加 Roots 支持，正是为了展示这个重要但不为人知的特性。

这个示例在仓库源码中可以得到完整印证。src/filesystem/roots-utils.ts 中的 getValidRootDirectories（L52-L77）负责将客户端通过 Roots 能力提供的 root 规格（file:// URI 或纯路径）转换为规范化目录路径，并对每个路径做存在性与目录校验；其内部 parseRootUri（L13-L25）还做了 ~ 展开与 fs.realpath 符号链接解析，以基础安全方式防止路径逃逸。src/filesystem/README.md 则说明客户端提供的 Roots 会完全替换服务命令行参数指定的 Allowed directories，即 Roots 是动态访问控制的主通道——"把 Roots 支持加进 filesystem"这个被点名的贡献方向，实际上已经是仓库内的落地实现。

另一处佐证在 Everything 服务器：src/everything/tests/registrations.test.ts 验证了 registerConditionalTools 会依据客户端能力注册条件工具，当客户端声明 roots、elicitation、sampling 能力时才注册 get-roots-list、trigger-elicitation-request、trigger-url-elicitation 等工具——参考服务器确实在系统性地展示 Tools 之外的协议特性。

3.2 谨慎评审的贡献（We're more selective about）

• 其他新功能 — 尤其当它不属于服务器核心用途、或带有强烈主观取舍（highly opinionated）时。文档给出的替代路径是：如果你有特定功能需求，鼓励你构建增强版本并发布到 MCP Server Registry。仓库的观点是：参考服务器应当"激励社区"，而一个多样化的服务器生态对所有人都有利。

3.3 不接受的贡献（We don't accept）

• 新的服务器实现 — 一律不接受，同样引导发布到 MCP Server Registry。

可以把这三条总结成一个判断口诀：改得更好（bug/易用性）→ 欢迎；教得更多（协议特性演示）→ 欢迎；做得更多（新功能/新服务器）→ 去 Registry 自建。 提交 PR 前对照 README.md 顶部的 WARNING（参考实现 ≠ 生产方案）也能校准预期：向参考服务器堆叠生产级特性，本身就不符合仓库定位。

四、测试规范：TypeScript 服务器统一使用 Vitest

CONTRIBUTING.md 的 "Testing" 一节的原文要求很直接：

When adding or configuring tests for servers implemented in TypeScript, use vitest as the test framework. Vitest provides better ESM support, faster test execution, and a more modern testing experience.

即：为 TypeScript 实现的服务器新增或配置测试时，必须使用 vitest，理由是更好的 ESM 支持、更快的执行速度和更现代的测试体验。这不是空泛的口号，仓库中四个 TypeScript 服务器（everything、filesystem、memory、sequentialthinking）已全部按此规范落地，贡献者提交测试时需要对齐以下事实：

1. 测试入口统一为带覆盖率的 vitest run。 以 src/everything/package.json 为例：

"scripts": {
  "test": "vitest run --coverage"
},
"devDependencies": {
  "@vitest/coverage-v8": "^4.1.8",
  "vitest": "^4.1.8",
  "typescript": "^5.6.2"
}

filesystem、memory、sequentialthinking 三个服务器的 package.json 采用完全一致的写法（vitest run --coverage + vitest@^4.1.8 + @vitest/coverage-v8）。

2. 统一的 vitest 配置。 src/everything/vitest.config.ts 展示了仓库标准配置，贡献新测试时应沿用同一形态：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['**/__tests__/**/*.test.ts'],
    coverage: {
      provider: 'v8',
      include: ['**/*.ts'],
      exclude: ['**/__tests__/**', '**/dist/**'],
    },
  },
});

关键点：测试文件必须放在 __tests__/ 目录且命名为 *.test.ts（由 include 模式强制），覆盖率采用 v8 provider 并排除测试与构建产物目录。

3. 测试写法示范。 以 src/everything/tests/registrations.test.ts 为例，仓库的测试风格是用 mock server 对象验证注册行为：导入 registerTools 后断言 registerTool 恰好被调用 12 次（12 个标准无条件工具），并逐一检查 echo、get-sum、get-env、get-tiny-image、get-structured-content、gzip-file-as-resource 等工具名是否在册。这类"注册清单"测试正是参考服务器维护协议特性演示的护栏——你提交的新工具如果没被测试锁定，注册逻辑回归时不会被发现。Python 服务器（如 src/git/tests/test_server.py）不在 vitest 规范约束范围内，该规范仅针对 TypeScript 实现。

五、文档贡献规范：优先"改善可用性"，避免厂商绑定

CONTRIBUTING.md 的 "Documentation" 一节给出两条原则：

1. 欢迎改进现有文档，但"如果可能，我们更希望看到可用性（ergonomic）改进，而不是把痛点写进文档"——即能通过改善实现/交互解决的问题，不要把问题文档化；
2. 对全新增文档更谨慎，尤其是非厂商中立（not vendor neutral）的写法，例如"如何在某个特定客户端中运行某个特定服务器"这类绑定具体厂商生态的教程。

结合 README.md 的结构可以理解这一条的动机：README 面向所有 MCP 客户端使用者，而仓库本身由指导小组中立维护，因此文档必须保持在协议层而非某家客户端产品层。撰写文档 PR 时，可以参照 src/everything/docs/ 这类按协议概念（extension、features、structure、startup 等）组织的既有文档风格。

六、动手前的工程惯例：构建、命名与扩展点

虽然不属于 CONTRIBUTING.md 正文，但要让你的 PR 通过评审，仓库内自带的开发指南 src/everything/AGENTS.md 值得通读，它规定了 Everything 服务器（也是协议特性演示最全的服务器）的工程惯例：

• 常用命令：npm run build（tsc 编译）、npm run watch、npm run start:stdio / start:sse / start:streamableHttp（三种传输）、npm run prepare（发布前构建）；
• 代码风格：ES module 且 import 路径带 .js 扩展名、严格 TypeScript 类型、工具入参一律用 zod schema 校验、2 空格缩进；命名上变量/函数 camelCase、类型 PascalCase、常量 UPPER_CASE、文件名与注册的工具/提示/资源名一律 kebab-case 且工具名用动词开头（如 get-annotated-message 而非 annotated-message）；
• 扩展模式：功能按目录分层（tools / resources / prompts / transports / server），每个模块导出 registerX(server) 注册函数并在对应目录的 index.ts 中接线，中心工厂为 server/index.ts——新增工具即遵循"照抄同目录既有文件的命名、导出与注册方式"这一模式。

对照 src/everything/tools/ 目录可以看到该模式的规模：echo.ts、get-sum.ts、get-structured-content.ts、trigger-elicitation-request.ts 等每个工具一个 kebab-case 文件，由 src/everything/tools/index.ts 统一注册，与 registrations.test.ts 中的 12 个标准工具断言一一对应。Python 服务器侧则各自维护 pyproject.toml 与 tests/ 目录（如 src/git/pyproject.toml）。

七、社区渠道与协作方式

CONTRIBUTING.md 的 "Community" 一节指向 MCP 官方的社区沟通指南（modelcontextprotocol.io/community/communication），即协议层的讨论、议题与协作统一在官方社区渠道进行；README.md 的 Community 部分同样指向 GitHub Discussions。对于贡献者的实操路径是：先在社区渠道讨论方案（尤其是"展示某个协议特性"的增强类改动），确认方向符合参考服务器的定位后再开工，可以显著降低 PR 被以"过于 opinionated"或"应发布到 Registry"为由拒绝的概率。

最后对照 CONTRIBUTING.md 做一次提交前自检：改动是否为 bug 修复、易用性改进或协议特性演示（欢迎）；是否为非必要新功能（谨慎，建议去 Registry）；是否新增服务器（不接受）；TypeScript 测试是否用了 vitest 并放在 __tests__/*.test.ts；文档是否厂商中立、偏向可用性改进；是否遵循了 registerX(server) 扩展点与 kebab-case 命名惯例。满足以上各条，你的贡献就落在这条仓库标准明确界定的接收范围内。