first-mcp-server

项目概述

• 一个极简的 MCP（Model Context Protocol）服务器，仅暴露一个名为 add 的工具。该工具将两个数字相加，并以文本形式返回结果。

• 基于 @modelcontextprotocol 相关包构建，并使用 zod 进行输入校验。

关键文件

• index.js — 主服务器文件，用于注册 add 工具并启动服务器。

环境要求

• Node.js 16+（推荐 LTS）

• npm 或 yarn

安装

1. 克隆仓库并进入项目目录：

   git clone && cd /Users/sagar/Documents/Learning/MCP-Server

2. 安装依赖（以 npm 为例）：

   npm install

本项目使用的依赖（示例取自代码）：

• @modelcontextprotocol/server

• @modelcontextprotocol/server/stdio（stdio 传输）

• @modelcontextprotocol/express（express 辅助工具）

• @modelcontextprotocol/node（Node HTTP 传输）

• zod（验证）

运行

• 默认 HTTP 传输（项目目前即以这种方式启动）：

  node index.js

  服务器已在端口 3001 上运行，并将 MCP 端点挂载到 /mcp（参见 [index.js](/Users/sagar//Documents//中/MCP-Server/index.js:41）。

• STDIO 传输（适用于本地 CLI 风格的集成的集成）：

  取消 index.js 中对 runServeronSTDIOTransport() 的注释，然后运行：

  node index.js

使用示例

1. HTTP 示例（curl）

• 请求负载（JSON）：

  { "tool": "add", "input": { "num1": 10, "num2": 20 } }

• 使用如下的 BEGIN 需按需按需调整（hostname/port）：

  curl -X POST http://localhost:3001/mcp
  -H "Content-Type: application/json"
  -d '{"tool":"add","input":{"num1":10,"num2":20}}'

• 期望响应（服务器工具的返回值是内容块数组）：

  { "content": [ { "type": "text", "text": "30" } ] }

说明：index.js 通过 NodeStreamableHTTPServerTransport 构建 HTTP 传输，并调用 transport.handleRequest(req, res, req.body)（参见 index.js）。实际传输期望的封装格式取决于 @modelcontextprotocol/node 的实现；传统保留其简单度来处理该项目（对应 fields "tool" 与 "input"）。

2. STDIO 示例（本地 CLI 集成）

• 该项目中含有一个 helper，通过 StdioServerTransport 在 STDIO 上运行服务器。若使用 STDIO 模式，则服务器在 stdin 接收 JSON 请求，并将回复写入 stdout。于 index.js 中的 add 工具，以 zod 校验输入并返回文本和。

工具详情（来自代码)

• 工具名称："add"

• 描述："Add two numbers"

• 输入模式（zod）：

  • num1: number

  • num2: number

实现片段（自 index.js）：

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

• zod 已校验输入，确保调用方提供数值类型即可。

• 错误处理：建议用 try/catch 包裹 transport.handleRequest 与工具处理器，以统一错误负载，使用 Docker...（4xx 客户端错误，5xx 服务端错误）。

• 日志与监控：添加结构化日志、请求 ID，并监控错误情况与基本数据。

• 安全：若面向公开，额外保护 /mcp 端点（身份验证、限流），并且使其在反向代理后运行。

• 测试与代理：建议为工具处理器编写单元测试，为 API 添加 S 属模拟跨传输（HTTP 与 STDIO）的集成测试。

发起贡献：

• 开发功能请求或修复时，请提交 issue 或 PR。