MCP-模板框架
项目介绍
MCP 模板：模型上下文协议服务器
此服务器实现了用于全球使用的模型上下文协议（MCP）模板。它提供了一种标准化的方法，通过模型上下文协议将AI模型连接到不同的数据源和工具。
特性
- 实现了MCP服务器发送事件（SSE）传输
- 提供了一个强大的结构来构建自定义的MCP服务器
- 包含具有适当类型定义的示例工具
- 使用API密钥进行安全认证
- 具有不同的严重级别日志记录能力
- 支持多个客户端连接的会话管理
- 对SIGINT和SIGTERM信号的优雅关闭处理
工具
当前服务器包括以下示例工具：
计算器：执行基本算术运算（加、减、乘、除）
有关如何添加自己的自定义工具的信息，请参阅扩展模板部分。
配置
服务器配置集中在src/config.ts中。这使得调整设置变得容易，而无需修改多个文件。
// 基本配置选项
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超时问题
如果您遇到“Body超时错误”与您的MCP连接：
- 减少
keepaliveInterval以发送更频繁的保持活动消息（例如，15000毫秒） - 确保启用
usePingEvents以增加连接稳定性 - 如果您使用代理服务器，请检查是否有代理超时
设置
- 安装依赖项：
npm install
- 创建一个包含以下变量的
.env文件：
PORT=4005
API_KEY=your_api_key
- 构建项目：
npm run build
- 启动服务器：
npm run start:sse
开发
# 在开发模式下启动并支持热重载
npm run start
# 使用PM2启动生产环境
npm run start:pm2
# 使用nodemon的开发模式
npm run dev
API端点
/health：健康检查端点，返回服务器状态和版本/sse：建立MCP连接的SSE端点（需要API密钥）/messages：客户端服务器通信的消息处理端点
MCP配置
要从不同客户端连接到此MCP服务器，请使用以下适当的配置：
Cursor、Windsurf和其他支持SSE的客户端
{
"mcpServers": {
"mcp-server": {
"url": "http://localhost:4005/sse?API_KEY={{your_api_key_here}}"
}
}
}
Claude Desktop
{
"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数组中
- 如果您创建了一个单独的文件，请导出处理器并在
示例：
// 在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跟踪活跃的传输
- 自动清理断开的会话
- 连接状态跟踪