用途:帮助开发者在 modelcontextprotocol/servers 仓库中定位代码,并决定新增文件应放在哪里。顶层目录树、各服务器的包名与注册表在 AGENTS.md 的 Project structure 一节;本技能说明其下一层:每个服务器内部有什么,以及新文件放在哪里。测试放置与测试框架见 /testing,构建与运行服务器见 /local-dev。
总体约束:服务器之间没有共享库。src/ 下每个目录都是独立版本化、独立发布的完整包,因此两个服务器都需要的辅助函数要在两边各写一份(例如 expandHome 在 filesystem 和 memory 中都存在,memory 中的副本已注明这一点)。不要添加跨服务器导入。任何服务器都不在导入时启动:每个服务器通过 createServer(...) 工厂构建,入口文件仅在被作为进程入口点时连接传输层(isEntryPoint() 或 isMainModule() 比较真实路径,以便 npm bin 符号链接仍能启动)。导入时就绑定端口、连接 stdio 或安装信号处理器的模块无法被测试在进程内驱动。
TypeScript 服务器(everything、filesystem、memory、sequentialthinking):四个都是根 package.json 的 npm workspace,共享同一形态:入口为 index.ts,源码位于工作区根目录(服务器内部没有 src/),测试在 tests/,tsc 输出 dist/。每个都有四个相同的配置文件:package.json、tsconfig.json(构建)、tsconfig.test.json(不产物的类型检查程序,也包含测试)和 vitest.config.ts。
各服务器内部结构与功能注册位置:everything 的 index.ts 从 argv 选择传输层;server/ 存放工厂;tools/、resources/、prompts/ 每个功能一个文件加一个 index.ts;transports/ 每种传输层一个文件;version.ts 读取包版本;docs/ 随包发布。每个功能文件导出 register… 函数,接入所属区域的 index.ts(registerTools、registerResources、registerPrompts),再由 server/index.ts 的 createServer() 调用。filesystem 的 index.ts 是 stdio 入口(argv → 允许目录,main());server.ts 导出 createServer(allowedDirectories);lib.ts 存放文件操作与路径校验,允许列表以参数传入而非全局持有;path-utils.ts、path-validation.ts、roots-utils.ts 是聚焦的辅助模块;version.ts 读取包版本;功能在 server.ts 的 createServer() 中以内联 server.registerTool(...) 注册。memory 的 index.ts 包含 KnowledgeGraphManager、createServer(memoryFilePath) 和 stdio main();version.ts 读取包版本;功能在 createServer() 中内联注册,资源及其订阅处理器是同一文件中导出的 register… 函数。sequentialthinking 的 index.ts 包含 createServer() 和 stdio main();lib.ts 包含 SequentialThinkingServer 与逻辑;version.ts 读取包版本;功能在 createServer() 中内联注册。
关于 everything 的三点补充:server/index.ts 导出 createServer(),返回 { server, cleanup };每个传输层文件调用它,每个 stdio 进程一次或每个 HTTP 会话一次。依赖客户端能力(roots、sampling、elicitation)的工具通过 registerConditionalTools 注册,它在 initialize 之后运行,而不是通过 registerTools。docs/ 是服务器的一部分而非仅文档:构建会把它复制到 dist/docs,其中每个文件都作为静态资源提供,docs/instructions.md 作为服务器说明返回;在那里新增文件即成为客户端可列出的资源。其自身映射文件是 src/everything/docs/structure.md 和 src/everything/docs/extension.md;服务器文件变更需更新 structure.md,src/everything/AGENTS.md 存放仅适用于该目录的规则。
Python 服务器(fetch、git、time):是独立的 uv 项目,布局相同。src/<server>/ 下有 pyproject.toml(依赖、控制台脚本、pytest 与覆盖率配置)、uv.lock、.python-version、src/mcp_server_<name>/(init.py 的 main(): 命令行标志,然后 asyncio.run(serve(...));main.py 支持 python -m mcp_server_<name>;server.py 存放其余全部内容)以及 tests/(pytest 套件,进程内驱动 serve())。server.py 持有 Pydantic 输入模型、执行工作的函数和 serve();serve() 构造 Server,在函数体内用 @server.list_tools() / @server.call_tool() 装饰器声明工具(fetch 还包括提示词),再通过 stdio 运行。因此新增工具是对 server.py 的一组修改:输入模型、list_tools 条目、call_tool 分支;git 和 time 还有第四处:工具名是枚举成员(GitTools、TimeTools),list_tools 与 call_tool 都据此分发,需先在那里加入新名称;fetch 只有一个工具且无枚举。Server 对象是 serve() 的局部变量,不可导入。
新文件放置规则:everything 的工具、资源或提示词——各自在 tools/、resources/、prompts/ 下的 kebab-case 文件,导出 register… 函数并接入该目录的 index.ts;everything 的传输层——src/everything/transports/,并在 src/everything/index.ts 加一个 case 和 start:… 脚本;filesystem、memory 或 sequentialthinking 的工具——在该服务器 createServer() 中的 server.registerTool(...) 调用(filesystem 在 server.ts,另两个在 index.ts),其调用的逻辑放入 lib.ts(或其扩展的类);everything 的辅助模块——放在它所支持的功能区域旁的 kebab-case .ts 文件(server/logging.ts、server/roots.ts、resources/session.ts),以 .js 扩展名导入;filesystem、memory 或 sequentialthinking 的辅助模块——工作区根目录的 kebab-case .ts 文件,以 .js 扩展名导入;Python 服务器的工具——server.py 中的工具名枚举成员(git、time)、模型、list_tools 条目、call_tool 分支;Python 服务器的命令行标志——init.py,传入 serve();测试——/testing;根工具脚本(守卫、发布辅助)——scripts/<name>.mjs,有值得测试的逻辑时配 <name>.test.mjs,共享辅助放在 scripts/lib/;设计文档——docs/;面向智能体的流程——.claude/skills/<name>/SKILL.md,并在 Skills 索引中加一行。新增服务器目录不在此列表中:仓库不接受新服务器(见 CONTRIBUTING.md)。
新增文件的校验:新位置的 TypeScript 文件仍在检查范围内,因为两个守卫枚举已跟踪文件而非信任 glob:verify:typecheck-coverage 在某个已跟踪 .ts 文件不属于 typecheck 运行的任何项目时失败;verify:format-coverage 在某个已跟踪源文件不匹配任何 prettier --check glob 时失败。两者都在 npm run validate:guards 中运行。若你的新增文件触发守卫,修复方式是把文件纳入现有配置,而非排除它。当文件或目录新增、删除、重命名或用途变更时,所有描述它的条目需在同一 PR 中更新(AGENTS.md,Maintenance rules):根 README.md、服务器自己的 README.md、AGENTS.md 中的目录树,以及 everything 的 docs/structure.md。