MCP Boilerplate

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

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

特性

• 实现MCP服务器发送事件（SSE）传输
• 为构建自定义MCP服务器提供了一个强大的结构
• 包括具有正确类型定义的示例工具
• 使用API密钥进行安全身份验证
• 具有不同严重级别的日志记录功能
• 多客户端连接的会话管理
• 对信号情报和信号终端信号进行优雅的关机处理

工具

服务器当前包括以下示例工具：

• 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连接出现“Body timeout error”：

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

设置

1. 安装依赖项：

npm install

1. 创建一个 .env 包含以下变量的文件：

PORT=4005
API_KEY=your_api_key

1. 构建项目：

npm run build

1. 启动服务器：

npm run start:sse

发展

# 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服务器，请使用以下适当的配置：

Cursor、Windsurf和其他SSE支持客户

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

克劳德桌面

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

扩展样板

添加自定义工具

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

1. 创建工具处理程序:

- 在中添加新的工具处理程序 src/tools.ts 文件或在中创建新文件 src/tools 目录 - 工具应遵循 ToolHandler 接口

1. 配置您的工具:

- 将您的工具配置添加到 toolConfigs 数组in src/tools.ts - 定义工具的名称、描述、输入模式和处理程序

1. 导出并注册您的工具:

- 如果创建了单独的文件，请导出处理程序并将其导入 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跟踪活动传输
• 自动清理断开连接的会话
• 连接状态跟踪

额外资源

• MCP文件
• MCP TypeScript SDK

许可证

该项目根据 MIT许可证 -看看 许可证 文件以获取详细信息。