MCP 模板：模型上下文协议服务器

此服务器实现了用于全局使用的模型上下文协议（MCP）模板。它提供了一种标准化的方法，通过模型上下文协议将AI模型连接到不同的数据源和工具。

特性

实现了MCP服务器发送事件（SSE）传输
为构建自定义MCP服务器提供了强大的结构
包含带有适当类型定义的示例工具
使用API密钥进行安全认证
支持不同严重级别的日志记录功能
多客户端连接的会话管理
对SIGINT和SIGTERM信号的优雅关闭处理

工具

该服务器目前包含以下示例工具：

calculator：执行基本算术运算（加、减、乘、除）

有关如何添加自己的自定义工具的信息，请参阅扩展模板部分。

配置

服务器配置集中于src/config.ts文件中。这使得无需修改多个文件即可轻松调整设置。

typescript // 必要的配置选项 export const config = { server: { name: "mcp-boilerplate", version: "1.0.0", port: parseInt(process.env.PORT || "4005"), host: process.env.HOST || "localhost", apiKey: process.env.API_KEY || "dev_key", }, sse: { // 发送保活消息的频率（以毫秒为单位） keepaliveInterval: 30000, // 是否除了注释外还发送ping事件 usePingEvents: true, // 初始连接消息 sendConnectedEvent: true, }, tools: { // 工具执行失败时的最大重试次数 maxRetries: 3, // 重试之间的延迟（以毫秒为单位） retryDelay: 1000, // 是否发送关于工具执行状态的通知 sendNotifications: true, }, logging: { // 默认日志级别 defaultLevel: "debug", // 发送日志消息的频率（以毫秒为单位） logMessageInterval: 10000, }, };

解决SSE超时问题

如果您在MCP连接中遇到“Body timeout error”错误：

减少keepaliveInterval以更频繁地发送保活消息（例如15000ms）
确保启用了usePingEvents以增加连接稳定性
如果您使用代理服务器，请检查是否有任何代理超时

设置

安装依赖项：

bash npm install

创建一个.env文件，并包含以下变量：

PORT=4005 API_KEY=your_api_key

构建项目：

bash npm run build

启动服务器：

bash npm run start:sse

开发

bash

以开发模式启动并启用热重载

npm run start

使用PM2在生产环境中启动

npm run start:pm2

使用nodemon在开发模式下启动

npm run dev

API端点

/health：健康检查端点，返回服务器状态和版本
/sse：用于建立MCP连接的SSE端点（需要API密钥）
/messages：客户端-服务器通信的消息处理端点

MCP配置

要从不同的客户端连接到此MCP服务器，请使用以下适当的配置：

Cursor, Windsurf和其他支持SSE的客户端

json { "mcpServers": { "mcp-server": { "url": "http://localhost:4005/sse?API_KEY={{your_api_key_here}}" } } }

Claude Desktop

json { "mcpServers": { "mcp-server": { "command": "npx", "args": [ "mcp-remote", "http://localhost:4005/sse?API_KEY={{your_api_key_here}}" ] } } }

扩展模板

添加自定义工具

按照以下步骤向MCP服务器添加新工具：

创建您的工具处理器：
- 在src/tools.ts文件中或在src/tools目录中创建一个新文件来添加新的工具处理器
- 工具应遵循ToolHandler接口
配置您的工具：- 将您的工具配置添加到 src/tools.ts 文件中的 toolConfigs 数组里

定义您的工具的名称、描述、输入模式和处理器

导出并注册您的工具：
- 如果您创建了一个单独的文件，请导出您的处理器并在 src/tools.ts 中导入它
- 确保您的工具在 toolConfigs 数组中正确注册

示例：

typescript // 在 src/tools.ts (直接添加到 toolConfigs 数组) { name: "myTool", description: "我的工具描述", inputSchema: { type: "object" as const, properties: {}, required: [], }, handler: async () => { return createSuccessResult({ result: "工具结果" }); }, }

错误处理

服务器实现了全面的错误处理机制：

所有操作都包裹在 try/catch 块中
对参数和输入进行适当的验证
提供适当的错误消息以利于调试
提供辅助函数来创建标准化的错误和成功响应

安全考虑

所有连接均使用 API 密钥认证
对所有参数进行类型验证
不包含硬编码的敏感信息
适当的错误处理，防止信息泄露
基于会话的传输管理

MCP 协议特性

此模板支持核心的 MCP 特性：

工具：列出和调用带有适当参数验证的工具
日志记录：多种严重级别（调试、信息、通知、警告、错误、严重、警报、紧急）
服务器配置：名称、版本和功能

会话管理

服务器通过以下方式管理客户端会话：

每个客户端连接都有唯一的会话 ID
通过会话 ID 跟踪活跃的传输
自动清理断开连接的会话
连接状态跟踪

额外资源

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

来源

来源：github
链接：https://github.com/iamsrikanthnani/mcp-boilerplate

iamsrikanthnani