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

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

特征

实现 MCP 服务器发送事件 (SSE) 传输
为构建自定义 MCP 服务器提供强大的结构
包括具有适当类型定义的示例工具
使用 API 密钥进行安全身份验证
具有不同严重程度的日志记录功能
多客户端连接的会话管理
SIGINT 和 SIGTERM 信号的正常关闭处理

Related MCP server: SourceSync.ai MCP Server

工具

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

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以获得额外的连接稳定性
如果您使用代理服务器，请检查是否存在代理超时

设置

安装依赖项：

npm install

使用以下变量创建.env文件：

PORT=4005
API_KEY=your_api_key

构建项目：

npm run build

启动服务器：

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 连接到此服务器，请添加以下配置：

{
  "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文件。

MCP Boilerplate