ECC MCP Server Patterns：基于 Node/TypeScript SDK 构建 MCP 服务器的工具、资源、提示与传输层实践

本文以 ECC 仓库中的 mcp-server-patterns 技能文档 为核心，系统讲解如何用 Node/TypeScript SDK（@modelcontextprotocol/sdk）构建 Model Context Protocol（MCP）服务器：涵盖 Tools、Resources、Prompts 三大核心构件的注册方式、Zod 输入校验、stdio 与 Streamable HTTP 传输层选型，并结合仓库中的 MCP 连接器配置目录 与 能力面选型文档 说明该模式在 ECC 项目中的实际应用。读完本文，你将掌握一个可复制的 MCP 服务器搭建流程，以及判断"什么时候该用 MCP、什么时候不该用"的决策依据。

技能定位：什么时候用 MCP Server Patterns

技能文档（frontmatter 中 name: mcp-server-patterns）明确给出的适用场景是：实现一个新的 MCP 服务器、为其添加工具或资源、在 stdio 与 HTTP 之间做传输层选型、升级 SDK 版本，或调试 MCP 注册与传输问题。该技能同时被声明在仓库根 agent.yaml 的技能清单中，说明它是 ECC 工具链面向 Agent 的一等能力，而非一次性教程。

一个值得注意的背景：技能文档强调 MCP 的 SDK API 会随版本演进，方法名和签名可能变化（例如 registerTool() 与 tool() 的并存），因此建议始终对照官方 MCP 文档或 Context7 查询库（在 mcp-configs/mcp-servers.json 中，Context7 正是被配置为"实时文档查询"连接器）来核对当前 @modelcontextprotocol/sdk 的签名，避免复制粘贴过时 API。

核心概念：Tools、Resources、Prompts 与 Transport

文档把 MCP 服务器抽象为四个核心构件：

• Tools（工具）：模型可以主动调用的动作，例如搜索、执行命令。注册方式因 SDK 版本而异，可能是 registerTool()，也可能是 tool()。
• Resources（资源）：模型可以拉取的只读数据，例如文件内容、API 响应。注册方式为 registerResource() 或 resource()，处理器通常接收一个 uri 参数。
• Prompts（提示模板）：可复用、参数化的提示模板，客户端可以将其展示出来（例如在 Claude Desktop 中）。注册方式为 registerPrompt() 或等效 API。
• Transport（传输层）：本地客户端（如 Claude Desktop）用 stdio；远程场景（Cursor、云端）优先使用 Streamable HTTP（当前规范下每个 MCP 服务器只暴露单一 HTTP 端点）；遗留的 HTTP/SSE 仅在有向后兼容需求时保留。

这里的关键设计原则是：服务器逻辑（tools + resources）必须与传输层解耦，在入口点（entrypoint）中再把逻辑接到 stdio 或 HTTP 上。这样同一套业务逻辑既能本地跑，也能部署到云端。

安装与服务器骨架

文档给出的最小可运行起点如下：

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

随后根据你所在 SDK 版本提供的 API 注册工具与资源。文档特别警告了签名差异：

• 一些版本使用位置参数形式：server.tool(name, description, schema, handler)；
• 另一些版本使用对象参数形式：server.tool({ name, description, inputSchema }, handler)，或干脆叫 registerTool()；
• 资源注册同理——当 API 提供 uri 时，应在处理器中包含它。

输入校验使用 Zod（或 SDK 偏好的 schema 格式）定义每个工具的 inputSchema。

与仓库内真实配置对照

上述 stdio 模式并非纸上谈兵。仓库的 mcp-configs/mcp-servers.json 中大量本地服务器正是 stdio 形态：例如 memory（npx -y @modelcontextprotocol/server-memory）、sequential-thinking（npx -y @modelcontextprotocol/server-sequential-thinking）、github（npx -y @modelcontextprotocol/server-github）。而远程 Streamable HTTP 形态在同样这份配置中也有真实样本：vercel（"type": "http", "url": "https://mcp.vercel.com"）、clickhouse、parallel-search 等均以单一 HTTP 端点 + 可选 headers（如 memxus 的 Authorization: Bearer ...）声明。这两类条目恰好印证了文档"stdio 管本地、Streamable HTTP 管远程"的传输层划分，并且展示了通过环境变量（env 字段）注入 API Key 这一 MCP 服务器的通用鉴权手法。

传输层选型与能力面路由：ECC 的实战约束

ECC 仓库对该技能最重要的补充，是它在项目层面给"要不要用 MCP"加了一层严格的路由判断。docs/capability-surface-selection.md 定义了五种能力承载面及其决策顺序：

1. 每次路径/事件匹配都要发生、不需要模型判断？→ 用 rule；
2. 主要是按需加载的 playbook/工作流？→ 用 skill；
3. 需要跨多个 harness/客户端反复调用的结构化 tool/resource 接口？→ 用 MCP；
4. 简单的本地一次性动作？→ 用本地 CLI/仓库脚本；
5. 只是大工作流中一个窄远程集成步骤？→ 在 skill 内直接调 API。

其中对 MCP 的正面判据是：结构化输入/输出、可复用的资源或提示、跨客户端重复使用、跨 Claude Code/Codex/Cursor/OpenCode 等 harness 的稳定接口，以及"常驻服务器进程值得这份运维开销"。负面判据同样明确：一次性本地命令、服务器唯一职责是 shell out 一次、安装/运行时负担大于产品价值——这三种情况都不该上 MCP。

docs/MCP-CONNECTOR-POLICY.md 进一步给出了 ECC 的落地版本：ECC 只内置一个默认连接器（chrome-devtools），且 2026 年 6 月的审计把原有六个默认连接器（github、context7、exa、memory、playwright、sequential-thinking）全部降级为 opt-in 条目——理由包括无状态请求/响应本应是 skill、工具 schema 会占用每个会话的上下文窗口等。该文档也解释了为什么 mcp-configs/mcp-servers.json 被定位为模板目录而非默认加载项：README 建议将所需条目复制到项目级 .mcp.json 或 Claude Code 的 ~/.claude.json，并可用 ECC_DISABLED_MCPS 环境变量在安装/同步阶段过滤。这条治理线索对技能使用者是直接的实践提醒：MCP 服务器的工具 schema 会进入每个会话的上下文，构建时应控制工具数量与描述的 token 成本——这正是下面最佳实践中"Rate and cost"一条的深层原因。

最佳实践：Schema First、错误、幂等与版本

文档总结的五条最佳实践，可直接作为 MCP 服务器的代码评审清单：

• Schema first（schema 优先）：为每个工具定义输入 schema，并文档化参数与返回结构。这让客户端（以及模型）在调用前就知道契约，也是 Zod 校验的基础。
• 错误处理：返回结构化的错误信息或模型可解读的消息，避免把裸栈追踪抛给模型。
• 幂等性：尽可能让工具幂等，使模型的重试行为是安全的。
• 速率与成本：调用外部 API 的工具要评估限流与费用，并写进工具描述中，让模型自行权衡调用。
• 版本管理：在 package.json 中锁定 SDK 版本，升级时核对 release notes。这一点与文档开头"SDK API 会演进"的警告呼应，也是仓库中 Context7 条目存在的意义。

从仓库结构看，这套实践在 ECC 生态内是自洽的：技能文档（skills 面）负责"怎么建服务器"，配置目录（mcp-configs/）负责"接入哪些现成服务器"，策略文档（MCP Connector Policy、Capability Surface Selection）负责"该不该建"，而 agent.yaml 把技能声明为 Agent 可隐式调用的能力（配套的 agents/openai.yaml 中还声明了 allow_implicit_invocation: true 策略），形成从决策到实现的完整闭环。

官方 SDK 与文档来源

文档结尾列出的官方 SDK 与文档来源，构建时应按此选型：

• JavaScript/TypeScript：@modelcontextprotocol/sdk（npm）。用 Context7（库名 "MCP"）查询当前注册与传输模式。
• Go：官方 Go SDK（modelcontextprotocol/go-sdk）。
• C#：.NET 官方 C# SDK。

小结

mcp-server-patterns 技能（其正式版本位于 skills/mcp-server-patterns/SKILL.md）的价值不在某一段代码，而是一套完整的判断链：核心概念（Tools/Resources/Prompts/Transport 与版本敏感的注册 API）→ 可运行骨架（McpServer + Zod + stdio/Streamable HTTP 双传输）→ 工程纪律（schema first、结构化错误、幂等、成本意识、锁版本）→ 组织级约束（能力面路由与连接器策略决定 MCP 的启用边界）。在 ECC 项目中，这条链路由技能文档、mcp-configs/mcp-servers.json 配置模板与 MCP 连接器策略 共同落地，读者可据此在当前 harness 中判断：你的下一个集成应该是一个 MCP 服务器，还是一个更轻的 skill 加 CLI。