用Express写MCPServer，Claude直接调用本地API实战解析
开发者实测：基于 Express 框架快速搭建 MCP Server，实现 Claude 等 AI 助手直接调用业务接口。核心在于复用已有 service 层逻辑，通过 stdio 或 HTTP 协议...
近期，Model Context Protocol（MCP）在开发者社区引发关注。不同于传统 Function Calling 各框架自定义 Schema 的碎片化现状，MCP 由 Anthropic 提出并开源，旨在为 AI 助手与后端服务之间建立统一的通信标准——类似“USB 接口”，一次实现即可被所有兼容客户端调用。
一位拥有多年 Express 开发经验的工程师在实践中验证：构建一个可被 Claude Desktop 直接调用的 MCP Server，并不需要学习全新框架。其技术栈仅包含 Express 4、官方 @modelcontextprotocol/sdk、Zod 与 TypeScript，无额外黑魔法。关键在于架构分层：将业务逻辑集中于 service.ts，再通过三个入口复用——REST API（/api/trending）、MCP stdio（本地调试）、MCP HTTP（/mcp 部署为远程服务）。
以“查询 GitHub 热门仓库”为例，service.ts 中封装了完整业务逻辑，包括对 GitHub Search API 的调用及限频兜底机制。当 API 请求失败时，自动返回预置的 FALLBACK 数据集，避免工具因外部依赖中断而失效。该函数被同时用于 REST 路由与 MCP 工具定义，真正实现“一套逻辑三吃”。
MCP Server 的实现本质是 JSON-RPC over stdio 或 HTTP。以 stdio 方式为例，使用官方 SDK 初始化 McpServer 后，只需声明工具函数及其参数类型与文档字符串，SDK 自动完成协议转换与错误处理。例如：
值得注意的是，stdio 模式下严禁向 stdout 输出任何调试信息，否则会污染 JSON-RPC 流，导致客户端无法识别工具列表。日志应统一输出至 stderr 或文件系统。
在部署层面，MCP 支持两种传输模式：
- stdio：适用于本地开发与桌面客户端（如 Claude Desktop），启动简单、调试直观；
- HTTP/SSE：适合云环境部署，通过 POST /mcp 接收请求，可配合 Nginx 反向代理与 TLS 加密。
实际项目中，开发者已将该模式应用于内部系统集成。例如，一个“接口文档检索”Server 可响应模型提问：“下单接口的参数是什么？”，并返回结构化文档片段；另一个“配置读取”工具则支持按 key 查询 config.ini，参数名明确标注单位（如 minutes: int = 10），显著提升模型调用准确率。
工具层设计有三大易错点需特别注意：
x、y 会导致模型猜测失败，而 service_name、minutes 并注明单位则大幅提高命中率；minutes="十分钟" 这类非数值参数，应在 Server 侧用 Zod 或 Pydantic 做强校验，避免运行时异常；MCP 的价值不仅在于简化接入流程，更在于推动可观测性标准化。所有工具调用经由统一 Client 出口，可在该层集中埋点：记录入参、耗时、异常堆栈，形成完整的 trace 链路，远优于在各业务函数中零散打日志。
与此同时，本地大模型生态也在加速适配。Ollama 自 v0.40.12 起提供 Anthropic Messages API 子集兼容，使 Claude Code 等工具可直连本地模型。配置仅需两行环境变量：
结合 MCP Server，开发者可构建完整闭环：本地模型（Ollama）→ AI 助手（Claude Code）→ 业务工具（Express MCP Server）→ 内部系统（GitHub API / 数据库 / 配置中心）。整个链路无需公网暴露，数据不出内网，兼顾安全与效率。
目前，MCP 已被多个开源项目采纳，包括 n8n、Cursor、Codeium 等。随着更多客户端支持，其作为“AI Agent 工具层事实标准”的地位正逐步确立。对于已有 Node.js 后端团队而言，迁移成本极低——只需在现有 Express 应用上叠加一层协议适配，即可让 AI 助手真正“动手干活”。
未来，MCP 或将进一步扩展对 Resources（只读数据源）与 Prompts（预置提示模板）的支持，但就当前实践而言，90% 的场景仍聚焦于 Tools 的可靠暴露。对开发者而言，掌握这一轻量级协议，意味着能以最小代价将既有系统接入 AI 时代的工作流。
