My First MCP Server

我的第一个 SSE MCP 服务

基于 Model Context Protocol (MCP) 的示例服务，通过 HTTP + Server-Sent Events (SSE) 暴露工具， 用于与本地用户和状态 API 交互。

此仓库旨在作为模板/样板代码，用于基于 Express + SSE 创建更多 Node MCP 服务。思路是克隆此项目，更改名称，并将示例工具改为适用于你自己的领域和 API 的工具。

索引 / 目录

• 🇪🇸 西班牙语文档
• 🇬🇧 英语文档

---

🇪🇸 西班牙语文档

描述

myfirstmcpserver 是一个 MCP 服务，它：

• 使用 Express 暴露一个 SSE 端点（GET /sse）和一个 HTTP 端点（POST /messages）。
• 使用官方 SDK @modelcontextprotocol/sdk 注册 MCP 工具。
• 连接到外部 HTTP API（默认地址为 http://localhost:3001），以执行网络和用户相关操作。

如需了解更多技术细节，请参阅 docs/spec.md 中的内部规范。

主要特性

• SSE 传输：基于 MCP SDK 的 SSEServerTransport 实现集成。
• 按领域分组：
  • networkTools：与 API 连通性和状态相关的工具。
  • userTools：用于通过外部 API 列出和创建用户的工具。
• 可扩展设计：可轻松添加新的工具组或操作。

注意：虽然仓库名称中提到了 STDIO，但此模板基于 Express + SSE，而非纯 STDIO。

如何使用此模板

1. 克隆此仓库，或在 GitHub 上将其用作 模板。
2. 如果需要，请在 package.json 中更改软件包名称和描述。
3. 可选：在 src/config/server.js 中更改 McpServer 的 name。
4. 修改或删除以下位置中的示例工具：
   • src/tools/networkTools.js
   • src/tools/userTools.js 按照相同模式创建新的 initializeXTools 模块，以适配你的领域。
5. 配置环境变量 API_BASE_URL，使其指向你的实际 API。
6. 根据新项目调整 README.md 和 docs/spec.md 中的文档。

要求

• Node.js ≥ 18（使用 Node 原生 fetch）。
• npm（软件包管理器）。

安装

在项目根目录中：

npm install

运行

• 开发模式（使用 nodemon）：

npm run dev

• 普通模式：

npm start

服务默认在 http://localhost:3000 启动。SSE 端点为：

• GET http://localhost:3000/sse

MCP 消息端点为：

• POST http://localhost:3000/messages

与 MCP 客户端配合使用

此服务旨在由支持 SDK 所定义的 SSE 传输（SSEServerTransport）的 MCP 客户端使用。

一般来说，客户端需要：

• 通过 GET /sse 建立 SSE 连接。
• 以 JSON 格式向 POST /messages 发送 MCP 请求（工具）。

请参阅你所使用的 MCP 客户端文档，了解如何配置外部 SSE 端点。

可用的 MCP 工具

工具会注册到 McpServer 实例中，详细说明见 docs/spec.md。简要概览：

• 🔗 网络工具（src/tools/networkTools.js）：
  • ping({ url })：执行 fetch(url) 并返回状态码或错误。
  • apiStatus()：调用 http://localhost:3001/status 并返回状态 JSON。
• 👤 用户工具（src/tools/userTools.js）：
  • getUsers()：从 http://localhost:3001/users 获取用户列表。
  • createUser({ name, email })：拆分名字和姓氏，并向 http://localhost:3001/users 发送 POST 请求以创建新用户。

外部 API

本项目不包含http://localhost:3001 上外部 API 的实现，只负责调用该 API。项目要求至少提供以下接口：

• GET /status — 返回状态信息。
• GET /users — 返回用户数组。
• POST /users — 使用适当的 JSON 请求体创建新用户。

数据结构示例请参阅 docs/spec.md。

---

🇬🇧 英文文档

概览

myfirstmcpserver 是一个**模型上下文协议（MCP）**服务，它：

• 使用 Express 提供 SSE 端点（GET /sse）和 HTTP 端点（POST /messages）。
• 使用官方的 @modelcontextprotocol/sdk 注册 MCP 工具。
• 连接到外部 HTTP API（默认为 http://localhost:3001），以执行网络和用户相关操作。

如需了解更深入的技术说明，请参阅 docs/spec.md 中的内部规范。

功能

• 使用 SDK 的 SSEServerTransport 实现 SSE 传输。
• 按领域分组工具：
  • networkTools：连通性和 API 健康状态检查。
  • userTools：通过外部 API 列出和创建用户。
• 可扩展设计：便于添加新的工具组或操作。

注意：虽然仓库名称中提到了 STDIO，但此模板基于 Express + SSE 构建，并非纯 STDIO 传输。

如何使用此模板

1. 克隆此仓库，或在 GitHub 上将其用作模板。
2. 如有需要，更新 package.json 中的包 name 和 description。
3. 可选：更改 src/config/server.js 中 McpServer 的 name。
4. 修改或移除以下文件中的示例工具：
   • src/tools/networkTools.js
   • src/tools/userTools.js 并按照相同模式创建新的 initializeXTools 模块。
5. 配置 API_BASE_URL 环境变量，使其指向你的实际 API。
6. 修改此 README.md 和 docs/spec.md，以介绍你的具体项目。

要求

• Node.js ≥ 18（使用 Node.js 内置的 fetch）。
• 使用 npm 作为包管理器。

设置

在项目根目录中：

npm install

运行

• 开发模式（使用 nodemon）：

npm run dev

• 普通模式：

npm start

默认情况下，服务监听 http://localhost:3000。主要端点：

• GET http://localhost:3000/sse — MCP 的 SSE 端点。
• POST http://localhost:3000/messages — MCP 消息端点。

从 MCP 客户端使用

此服务面向支持 SDK 所实现的 SSE 传输的 MCP 客户端。

通常，客户端应：

• 打开到 GET /sse 的 SSE 连接。
• 以 JSON 格式向 POST /messages 发送 MCP 工具请求。

有关如何配置 MCP 客户端以连接到外部 SSE MCP 服务的具体格式，请参阅相应的客户端文档。

可用的 MCP 工具

工具在 McpServer 实例上注册。完整详情请参阅 docs/spec.md。 简要说明：

• 🔗 网络工具（src/tools/networkTools.js）：
  • ping({ url })：执行 fetch(url)，并返回 HTTP 状态码或错误。
  • apiStatus()：调用 http://localhost:3001/status，并返回状态 JSON。
• 👤 用户工具（src/tools/userTools.js）：
  • getUsers()：从 http://localhost:3001/users 获取用户列表。
  • createUser({ name, email })：将全名拆分为名和姓，并向 http://localhost:3001/users 发送 POST 请求，以创建新用户。

外部 API

本项目不包含http://localhost:3001 上外部 API 的实现，只负责调用该 API。项目要求至少提供以下接口：

• GET /status — 返回一般状态信息。
• GET /users — 返回用户数组。
• POST /users — 使用适当的 JSON 请求体创建新用户。

示例请求体请参阅 docs/spec.md。

---

由 Enrique Rodriguez Vela 制作