MCP 样板：模型上下文协议服务器
该服务器实现了模型上下文协议 (MCP)，可供全球使用，并作为样板。它提供了一种标准化的方法，可以使用模型上下文协议将 AI 模型连接到不同的数据源和工具。
特征
- 实现 MCP 服务器发送事件 (SSE) 传输
- 为构建自定义 MCP 服务器提供强大的结构
- 包括具有适当类型定义的示例工具
- 使用 API 密钥进行安全身份验证
- 具有不同严重程度的日志记录功能
- 多客户端连接的会话管理
- SIGINT 和 SIGTERM 信号的正常关闭处理
工具
该服务器当前包含以下示例工具：
calculator ：执行基本算术运算（加、减、乘、除）
有关如何添加您自己的自定义工具的信息，请查看扩展样板部分。
配置
服务器配置集中在src/config.ts中。这使得调整设置变得容易，而无需修改多个文件。
// Essential configuration options
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: {
// How often to send keepalive messages (in milliseconds)
keepaliveInterval: 30000,
// Whether to send ping events in addition to comments
usePingEvents: true,
// Initial connection message
sendConnectedEvent: true,
},
tools: {
// Number of retries for failed tool executions
maxRetries: 3,
// Delay between retries (in milliseconds)
retryDelay: 1000,
// Whether to send notifications about tool execution status
sendNotifications: true,
},
logging: {
// Default log level
defaultLevel: "debug",
// How often to send log messages (in milliseconds)
logMessageInterval: 10000,
},
};
排除 SSE 超时故障
如果您的 MCP 连接出现“主体超时错误”：
- 减少
keepaliveInterval以更频繁地发送 keepalive 消息（例如 15000ms） - 确保启用
usePingEvents以获得额外的连接稳定性 - 如果您使用代理服务器，请检查是否存在代理超时
设置
- 安装依赖项：
- 使用以下变量创建
.env文件：
PORT=4005
API_KEY=your_api_key
- 构建项目：
- 启动服务器：
发展
# Start in development mode with hot reloading
npm run start
# Start with PM2 for production
npm run start:pm2
# Development mode with nodemon
npm run dev
API 端点
/health ：返回服务器状态和版本的健康检查端点/sse ：用于建立 MCP 连接的 SSE 端点（需要 API 密钥）/messages ：客户端-服务器通信的消息处理端点
MCP 配置
要将 MCP 连接到此服务器，请添加以下配置：
{
"mcpServers": {
"mcp-server": {
"url": "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数组中正确注册
例子：
// In src/tools.ts (adding directly to the toolConfigs array)
{
name: "myTool",
description: "My tool description",
inputSchema: {
type: "object" as const,
properties: {},
required: [],
},
handler: async () => {
return createSuccessResult({ result: "Tool result" });
},
}
错误处理
服务器实现了全面的错误处理：
- 所有操作都包裹在try/catch块中
- 对参数和输入进行适当的验证
- 适当的错误消息以便更好地调试
- 用于创建标准化错误和成功响应的辅助函数
安全注意事项
- 所有连接的 API 密钥认证
- 所有参数的类型验证
- 没有硬编码的敏感信息
- 适当的错误处理以防止信息泄露
- 基于会话的传输管理
MCP 协议功能
该样板支持核心 MCP 功能：
- 工具：列出并调用具有适当参数验证的工具
- 日志记录：各种严重级别（调试、信息、通知、警告、错误、严重、警报、紧急）
- 服务器配置：名称、版本和功能
会话管理
服务器通过以下方式管理客户端会话：
- 每个客户端连接的唯一会话 ID
- 通过会话 ID 跟踪活动传输
- 自动清理断开的会话
- 连接状态跟踪
其他资源
执照
该项目根据MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。