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

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

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文以 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 定义了五种能力承载面及其决策顺序：

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考