MCP-SERVER-TEMPLATE

MCP 服务器模板

欢迎使用MCP-SERVER-TEMPLATE ，这是一个使用官方 TypeScript SDK 实现模型上下文协议 (MCP) 服务器的模板项目。该项目为构建无状态和有状态的 MCP 服务器奠定了基础，并支持 HTTP 和标准 I/O (stdio) 等不同的传输机制。

目录

• 概述
• 先决条件
• 安装
• 配置
• 运行服务器
• 测试
• 代码格式化
• 项目结构
• 故障排除
• 贡献
• 执照
• 致谢

概述

MCP-SERVER-TEMPLATE项目是一个基于 TypeScript 的入门模板，用于使用官方 SDK 构建模型上下文协议 (MCP) 服务器。该服务器充当用户查询和工具执行之间的接口，使 AI 助手和外部系统能够以模块化和可扩展的方式动态调用工具、解释提示和管理资源。

关键功能

• 模块化架构：该项目分为清晰的模块，用于配置、传输管理、工具注册、服务器编排和实用程序助手，促进关注点分离和易于维护。
• 传输抽象：内置对多种传输类型的支持，包括：
  • HTTP（无状态） ：每个请求都会启动一个新的 MCP 服务器实例，以实现完全隔离并符合 RESTful 实践。
  • STDIO（有状态） ：用于需要持续通信的桌面或基于 CLI 的集成。
  • 通过统一的接口和工厂模式，可轻松扩展到未来的传输，例如 SSE 或 WebSocket。
• 依赖注入：自定义 DI 系统将配置和日志等服务注入工具和传输层，确保可测试性和解耦。
• 工具系统：工具是独立的类，定义：
  • 唯一的名称和描述
  • 用于输入验证的 Zod 模式
  • 处理业务逻辑的execute函数
  • 自动生成用于外部自省的 JSON 模式
• 提示和资源可扩展性：包括脚手架以支持提示模板和动态资源获取，允许将来与 LLM 集成以进行提示编排或检索增强生成 (RAG) 用例。
• 内置测试和调试：
  • MCP Inspector ：用于可视化工具调用、输入/输出流和实时调试的 GUI。
  • HTTP 测试脚本：发送 JSON-RPC 请求以测试端点响应。
  • 单元测试：基于 Jest 的工具和实用程序逻辑测试框架。
• 可配置且安全：可通过.env和运行时配置文件轻松调整：
  • 身份验证凭证和 API 密钥
  • 服务器端口和传输选项
  • 日志记录级别和会话行为

用例

此模板非常适合：

• 构建对话式 MCP 服务器
• 创建后端来管理基于 LLM 的工作流的可调用工具

无论您是在制作 LLM 工具链原型、与专有系统集成，还是准备可扩展的生产 MCP 助手后端，该项目都提供了一个可扩展且结构完善的解决方案。

先决条件

• Node.js（建议使用 18.x 或更高版本）
• npm（Node 包管理器）
• Git（用于克隆存储库）

安装

1. 克隆存储库：
   git clone xxxx cd mcp-server-template
2. 安装依赖项：
   npm install
   这将安装生产依赖项（例如， @modelcontextprotocol/sdk 、 express 、 axios ）和开发依赖项（例如， typescript 、 ts-node 、 jest ），如package.json中所定义。
3. 确保已安装@modelcontextprotocol/sdk包（版本^1.10.1 ），因为它是 MCP 功能的核心依赖项。

配置

该项目使用通过环境变量和src/core/config/中的两个关键文件进行管理的配置系统。设置在ConfigService和runtimeConfig中定义，允许自定义传输类型、日志记录和外部 API 集成。

配置选项

• 环境变量（通过runtimeConfig.ts中的dotenv加载）：
  • TRANSPORT_TYPE ：设置传输机制（ 'http'或'stdio' ，默认值： 'stdio' ）。
  • HTTP_PORT ：HTTP 服务器的端口（默认值： 3000 ）。
  • HTTP_HOST ：HTTP 服务器的主机（默认值： localhost ）。
  • SESSION_SUPPORT ：启用/禁用会话支持（默认值： 'true' ）。
  • LOG_LEVEL ：日志记录级别（例如， 'info' ， 'debug' ，默认值： 'info' ）。
  • MCP_INSPECTOR_PORT ：MCP 检查器的端口（默认值： 6274 ）。

示例配置

在.env文件中设置环境变量：

运行服务器

服务器通过入口点src/index.ts启动，它使用依赖注入和配置设置来协调初始化和启动过程。

启动过程

1. 环境设置： index.ts使用dotenv加载环境变量，以确保配置设置（例如TRANSPORT_TYPE 、 HTTP_PORT ）可用。
2. 依赖项初始化：使用createDependencies设置共享依赖项，如 logger 和ConfigService 。
3. 传输配置：根据TRANSPORT_TYPE设置通过runtimeConfig配置传输（ HttpTransport或StdioTransport ）。
4. 服务器初始化：使用配置的传输和依赖项创建MCPServer实例。
5. 服务器启动：异步启动服务器，通过记录并退出失败代码来处理任何致命错误。

启动服务器

1. 生产模式：
   • 构建项目以将 TypeScript 编译为 JavaScript：
     npm run build
     这将运行tsc来生成包含已编译 JavaScript 文件的dist/文件夹。
   • 启动服务器：
     npm start
     这将执行node dist/index.js来运行编译后的服务器。
   • 对于http ，服务器监听http://localhost:3000/mcp （端口和主机可通过HTTP_PORT和HTTP_HOST配置）。
   • 对于stdio ，服务器从控制台读取并写入。
2. 开发模式：
   • 使用ts-node直接通过 TypeScript 运行服务器：
     npm run dev
     这将执行ts-node src/index.ts ，从而允许更快的迭代而无需构建步骤。

笔记

• 确保在启动服务器之前正确设置环境变量或runtimeConfig配置设置。
• 检查控制台输出的日志（由LOG_LEVEL控制）以验证服务器是否成功启动。

测试

该项目包括几个脚本，用于测试服务器、调试其行为以及使用自动化测试和 MCP Inspector 验证功能。

单元测试

使用 Jest 运行单元测试来验证各个组件的功能：

这将执行jest ，运行项目中定义的所有测试（例如，测试工具、实用程序或服务器逻辑）。请确保已使用 Jest 和ts-jest设置测试文件，以支持 TypeScript。

HTTP 传输测试

为 HTTP 传输提供了测试脚本，以验证 MCP 服务器的基本功能。

脚本详细信息（ src/scripts/testHttpTransport.js ）

• 目的：通过向服务器发送 JSON-RPC tools/list请求并验证响应来测试 HTTP 传输。
• 依赖项：
  • 使用axios向服务器发送 HTTP POST 请求。
• 功能：
  • 使用method: 'tools/list' 、 id: 1和适当的标头向http://localhost:3000/mcp发送 JSON-RPC 2.0 请求。
  • 验证响应以确保：
    • 响应遵循 JSON-RPC 2.0 ( jsonrpc: '2.0' )。
    • 响应id与请求匹配（ id: 1 ）。
    • 响应包含一个带有预期tools键的result字段。
  • 如果有效，则记录带有响应数据的成功消息；如果格式不符合预期，则记录带有接收数据的错误。
• 错误处理：
  • 捕获并记录任何请求失败（例如，网络错误、服务器未运行）以及错误消息。

运行测试

1. 确保服务器正在运行并且TRANSPORT_TYPE设置为'http' ：
   npm start
2. 运行测试脚本：
   npm run test:http
   这将执行ts-node src/scripts/testHttpTransport.ts 。

联合起跑和测试

要通过一个命令启动服务器并运行 HTTP 测试：

这将运行npm run start & npm run test:http ，在后台启动服务器并立即运行 HTTP 测试脚本。

预期输出

• 成功案例：如果服务器正确响应，脚本将记录：
  ✅ HTTP transport responded correctly to tools/list Response: { "tools": [ { "name": "calculator_tool", "description": "Performs basic arithmetic operations: add, subtract, multiply, divide.", "inputSchema": {...} } ] }
• 失败案例（无效的响应格式） ：如果响应格式不符合预期，则脚本会记录以下内容：
  ❌ Response received, but unexpected format Received: {...}
• 失败情况（请求失败） ：如果请求失败（例如，服务器未运行），则脚本记录：
  ❌ HTTP request failed: <error message>

笔记

• 该脚本假定服务器在http://localhost:3000/mcp上运行。如果HTTP_PORT或HTTP_HOST不同，请调整脚本中的endpoint 。
• 确保诸如CalculatorTool之类的工具已注册，以便在tools/list响应中看到它们。

MCP 检查器调试

MCP Inspector 是一个用于调试和监控 MCP 服务器的强大工具，它提供了一个 Web UI 来检查服务器状态和交互。

脚本详情（ src/scripts/mcpInspectorScript.ts ）

• 目的：启动 MCP Inspector，等待其 Web UI 准备就绪，然后在浏览器中打开它，以使用 stdio 传输在本地调试 MCP 服务器。
• 依赖项：
  • 使用child_process生成mcp-inspector进程并执行浏览器打开命令。
  • 使用axios检查 MCP Inspector Web UI 是否可访问。
  • 利用通过createDependencies()进行的依赖注入来访问ConfigService进行端口配置。
• 功能：
  • 使用npx mcp-inspector node dist/index.js生成mcp-inspector进程，继承 stdio 用于控制台输出。
  • 实现waitUntilInspectorIsReady来轮询 Web UI（默认端口： 6274 ，可通过MCP_INSPECTOR_PORT配置），并进行重试（20 次尝试，500 毫秒延迟）。
  • 在特定平台的浏览器中打开 Web UI：
    • macOS： open
    • Windows： start
    • Linux： xdg-open
  • 记录带有 URL 的启动摘要表：
    • MCP 检查器 UI： http://localhost:6274 （或配置的端口）
    • MCP 代理服务器： http://localhost:6277
• 错误处理：
  • 如果 Web UI 不能立即可用，则重试。
  • 如果检查器在重试后仍无法启动，则会引发错误并退出。
  • 失败时终止检查器进程并记录一条消息以手动检查或重新启动。

运行 MCP 检查器

1. 确保服务器已编译（例如， npm run build生成dist/index.js ）。
2. 运行 MCP 检查器脚本：
   npm run mcp:inspector
   这将执行ts-node src/scripts/start-mcp-inspector.ts 。

联合建造和检查

要使用一个命令构建项目并启动 MCP Inspector：

这将运行npm run build && npm run mcp:inspector ，确保在启动检查器之前编译项目。

调试技巧

• 使用 MCP Inspector UI 监控服务器请求、工具调用和响应。
• 如果检查器启动失败，请检查控制台输出中的启动日志或错误。
• 验证MCP_INSPECTOR_PORT未被其他服务使用。

代码格式化

该项目使用 Prettier 来维护所有文件的一致代码格式。

格式代码

要格式化项目中的所有文件：

这将执行prettier --write . ，自动格式化所有支持的文件（例如.ts 、 .js 、 .json ）。

检查格式

检查所有文件是否符合 Prettier 格式规则：

这将执行prettier --check . ，报告任何不符合格式规则的文件而不对其进行修改。

项目结构

• src/core/config/
  • configService.ts ：实现ConfigService ，这是一个用于管理服务器配置的类。它从环境变量中加载设置，包括传输类型、HTTP 服务器设置、日志记录级别、API URL（例如 MealDB）、身份验证凭据和 MCP 检查器端口的默认设置。
  • runtimeConfig.ts ：定义运行时配置，使用dotenv加载环境变量。它设置传输配置（ transportType 、 port ）和身份验证策略（ authStrategy 、 tokenSecret 、 username 、 password ）。
• src/core/dependencies/
  • dependencies.ts ：使用Dependencies接口实现依赖注入，提供一个logger （使用 Winston）和一个ConfigService实例。createDependencies createDependencies会根据transportType动态配置日志传输（stdio 为stdio ，其他为 stdout，以及一个文件 log combined.log ），并导出一个单例logger以供全局使用。
• src/core/server/
  • transports/
    • http/
    • server.ts ：实现HttpTransport ，一个使用 Express 的无状态 HTTP 传输协议。它处理POST /mcp请求，处理带有可选 Bearer token 身份验证的 JSON-RPC 消息，将响应存储在ResponseMap中，并支持异步发送响应。它依赖于依赖注入的Dependencies进行日志记录和配置。
      • stdio/
    • server.ts ：实现StdioTransport ，这是一个使用 SDK 的StdioServerTransport的传输接口。它管理 stdin/stdout 通信，启动和关闭传输，并通过依赖注入的Dependencies处理消息发送和错误日志记录。
      • baseTransport.ts ：定义BaseTransport接口和抽象AbstractTransport类，扩展了 SDK 的Transport接口。它为传输实现指定了方法（ start 、 send 、 close 、 isRunning ）和事件处理程序（ onmessage 、 onerror 、 onclose ），为HttpTransport和StdioTransport提供了通用的契约。
      • transportFactory.ts ：实现TransportFactory ，这是一个静态类，它根据TransportConfig类型（例如'http'或'stdio' ）创建HttpTransport或StdioTransport的实例。它使用依赖注入和Dependencies来提供日志记录和配置，并针对不支持的传输类型抛出错误。
  • mcpServer.ts ：实现MCPServer ，它是核心服务器类，用于将 MCP SDK 的Server与传输协议（ HttpTransport或StdioTransport ）集成。它初始化服务器，使用ToolRegistry设置RequestHandler ，连接传输协议，并使用依赖注入的Dependencies来处理消息传递、错误和响应，并进行日志记录。
  • requestHandler.ts ：实现RequestHandler ，它使用 MCP SDK 注册tools/list和tools/call请求的处理程序。它列出可用的工具，并使用已验证的参数（通过 Zod）执行工具调用，支持身份验证令牌，并针对无效的工具（ ToolNotFoundError ）或参数（ ValidationError ）抛出错误。它使用依赖注入的Dependencies进行日志记录。
• src/core/toolManagement/
  • toolFactory.ts ：实现ToolFactory ，它是一个使用Dependencies依赖注入创建工具实例（例如， calculatorTool ）的类。它定义了一个泛型ToolConstructor类型，并通过日志记录处理实例化错误。
  • toolRegistry.ts ：实现ToolRegistry ，这是一个管理工具注册和检索的类。它使用ToolFactory从toolClasses实例化工具，将它们存储在Map中，并提供注册、获取和列出工具及其元数据（名称、描述、输入模式）的方法。它通过依赖注入的Dependencies记录加载状态和错误。
  • errors.ts ：定义用于工具管理的自定义错误类，包括ToolNotFoundError （当请求的工具未注册时抛出）和ValidationError （当工具参数验证失败时抛出，例如通过 Zod）。
  • types.ts ：定义用于传输和身份验证配置的 TypeScript 类型。包括TransportType （ 'stdio' 、 'sse' 、 'http' ）、 TransportConfig （包含 SSE 或 HTTP 选项以及身份验证）、 SSETransportConfig （端口、CORS、身份验证）、 HttpStreamTransportConfig （端口、响应模式、CORS、会话、可恢复性、身份验证）以及AuthConfig （策略、凭据）。
• src/prompts/ ：提示模板目录（当前为空，保留用于将来实现）。
• src/resources/ ：资源管理目录（当前为空，为将来的实现保留）。
• src/scripts/
  • testHttpTransport.js ：HTTP 传输的测试脚本，通过发送tools/list请求并验证响应来验证基本功能。
  • mcpInspectorScript.ts ：用于启动 MCP Inspector 的脚本，等待其 Web UI 准备就绪，并在浏览器中打开它以调试 MCP 服务器。它使用依赖注入来访问ConfigService进行端口配置，并处理特定平台的浏览器打开。
• src/tools/
  • types/
    • ITool.ts ：定义工具的ITool接口，指定name 、 description 、 schema （ Zod 类型）、 jsonSchema ，以及用于处理 JSON-RPC CallToolRequest``execute方法。导出工具实现的Dependencies 。
    • baseTool.ts ：实现一个抽象的BaseTool类，该类减少样板，使用Dependencies处理依赖注入，并使用zod-to-json-schema以进行自省、文档和 UI 生成。
    • index.ts ：将toolClasses导出为工具构造函数数组（例如CalculatorTool ），以便由ToolRegistry动态加载，从而可以轻松扩展新工具。
    • calculatorTool.ts ：实现CalculatorTool ，这是一个具体的工具，它执行基本的算术运算（ add 、 subtract 、 multiply 、 divide ），并通过 Zod 进行输入验证、进行错误处理（例如，使用HttpError进行除以零），并通过依赖注入的Dependencies进行日志记录。
  • utils/
    • httpUtils.ts ：提供用于 HTTP 操作的实用函数，包括： serviceRequest （用于发起经过身份验证的 HTTP 请求，支持重试和超时处理）、 getAuthToken用于获取和缓存 OAuth2 令牌）、 buildQueryString用于创建查询字符串）以及validateResponse用于响应验证）。它与ConfigService集成，用于配置。
    • index.ts ：导出实用函数以供工具和其他组件使用。
• src/index.ts ：启动 MCP 服务器的入口点。使用dotenv加载环境变量，使用createDependencies初始化依赖项，使用来自runtimeConfig的传输协议创建MCPServer实例，并异步启动服务器，通过记录日志和退出来处理致命错误。

故障排除

• “服务器未初始化”错误：
  • 确保处理程序已注册，并且已在MCPServer设置中设置了功能（通过RequestHandler ）。
  • 在处理每个请求（对于 HTTP）之前立即验证传输是否已连接。
  • 如果重复使用的服务器仍然存在错误，请使用无状态方法（每个请求一个新服务器）。
• 性能问题：
  • 每次请求都创建新的服务器可能会在高负载下影响性能。如有需要，可以考虑复用一个带有会话管理功能的MCPServer ，但务必进行充分测试。
• 配置问题：
  • 确保环境变量在.env文件中正确设置或直接传递给进程。
  • 如果外部 API 集成（例如 MealDB、OMDB）失败，请检查ConfigService日志以验证已加载的设置。
• 日志问题：
  • 验证LOG_LEVEL环境变量是否与预期级别匹配（例如'info' 、 'debug' ）。
  • 对于stdio传输，确保日志按预期定向到 stderr；检查combined.log以获取基于文件的日志。
• 运输问题：
  • 对于HttpTransport ，请确保端口可用并且没有运行冲突的服务。
  • 对于StdioTransport ，如果没有处理消息，请检查 stdin/stdout 可用性。
  • 如果TransportFactory失败，请验证TRANSPORT_TYPE是否与配置中支持的类型（ 'http'或'stdio' ）匹配。
• 请求处理问题：
  • 如果tools/list或tools/call请求失败，请检查ToolRegistry是否有已注册的工具。
  • 根据CallToolRequestSchema中的模式验证工具参数以避免ValidationError 。
  • 如果工具需要，请确保提供身份验证令牌。
• 刀具管理问题：
  • 如果工具加载失败，请验证src/tools/index.ts中的toolClasses是否包含有效的工具实现。
  • 检查ToolFactory日志中是否存在实例化错误并确保Dependencies已正确注入。
• MCP 检查器问题：
  • 如果 MCP Inspector 启动失败，请验证MCP_INSPECTOR_PORT （默认值： 6274 ）未被使用。
  • 在启动脚本之前，通过运行npm run build确保dist/index.js存在。
  • 检查控制台输出是否存在启动期间的错误，例如网络问题或缺少依赖项。
• HTTP 请求问题：
  • 如果serviceRequest失败，请验证ConfigService中的authType 、 authEndpoint 、 clientId 、 clientSecret或apiKey设置。
  • 检查可能触发重试的网络问题或服务器错误（5xx）。
  • 确保请求 URL 和方法正确，并使用validateResponse验证响应模式。
• HTTP 传输测试问题：
  • 如果testHttpTransport.js脚本失败，请确保服务器正在使用TRANSPORT_TYPE='http'运行并监听http://localhost:3000/mcp 。
  • 验证端口和主机是否与脚本的endpoint匹配（如果HTTP_PORT或HTTP_HOST不同则进行调整）。
  • 检查ToolRegistry中已注册的工具；空的tools数组可能表示存在工具加载问题。
• 测试问题：
  • 如果npm test失败，请确保 Jest 使用ts-jest正确配置以支持 TypeScript，并验证测试文件是否存在。
  • 如果npm run mcp:inspector或npm run mcp:dev失败，请检查@modelcontextprotocol/inspector是否已安装以及服务器是否已编译（ dist/index.js是否存在）。
• 格式问题：
  • 如果npm run format:check报告问题，请运行npm run format以自动修复格式，或手动调整文件以符合 Prettier 的规则。

贡献

欢迎在 GitHub 代码库中提交问题或拉取请求。欢迎为改进服务器实现、添加新功能或优化性能做出贡献！

执照

本项目遵循 ISC 许可证。详情请参阅LICENSE文件。

致谢

• 使用@modelcontextprotocol/sdk构建
• 受到typescript-sdk 存储库中的示例的启发。