AI导哈

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

一个生产就绪的模型上下文协议（MCP）服务器模板，支持TypeScript，具有认证、速率限制、可观察性和双传输支持（stdio + HTTP+SSE）功能。

  • by muhammadkh4n
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 muhammadkh4n/mcp-server-template

使用说明

MCP服务器模板

一个带有TypeScript的生产就绪模型上下文协议（MCP）服务器模板，具有身份验证、速率限制、可观察性和双传输支持（stdio+HTTP+SSE）。

特性

✨ 生产就绪架构

  • 具有严格模式的TypeScript
  • ESM模块
  • 全面的错误处理
  • 优雅的关机，连接排水

🔐 身份验证和安全

  • API密钥验证
  • OAuth2支持（可扩展）
  • 使用令牌桶算法限制每个客户端的速率

📊 可观测性

  • 使用Pino进行结构化日志记录
  • OpenTetry集成
  • 健康检查端点
  • 请求跟踪

🚀 双重运输支持

  • 标准：用于本地CLI使用
  • HTTP+SSE：适用于基于网络的客户端

🛠️ 示例实现

  • 带有Zod验证的工具示例
  • 具有缓存的资源示例
  • 中间件模式

快速开始

安装

cd ~/Projects/mcp-server-template
npm install

配置

复制 .env.example 到 .env 并配置：

cp .env.example .env

关键环境变量：

  • TRANSPORT: stdio 或 http
  • PORT：HTTP服务器端口（默认值：3000）
  • API_KEYS：用于身份验证的逗号分隔的API密钥
  • RATE_LIMIT_TOKENS：每个存储桶的最大令牌数（默认值：100）
  • LOG_LEVEL：日志记录级别（调试、信息、警告、错误）
  • OTEL_ENABLED：启用OpenTetry（真/假）

构建

npm run build

跑

标准模式 （供当地使用）：

npm run start:stdio

HTTP+SSE模式 （适用于web客户端）：

npm run start:http

或者直接使用编译后的二进制文件：

node dist/index.js --transport=http --port=3000

项目结构

src/
├── index.ts              # Entry point with transport setup
├── server.ts             # MCP server configuration
├── middleware/
│   ├── auth.ts          # API key + OAuth2 middleware
│   ├── rateLimit.ts     # Token bucket rate limiter
│   └── logging.ts       # Pino structured logging
├── tools/
│   └── example.ts       # Example tools (echo, calculator)
├── resources/
│   └── example.ts       # Example resources with caching
└── utils/
    ├── errors.ts        # MCP error helpers
    ├── health.ts        # Health check system
    └── telemetry.ts     # OpenTelemetry setup

API 参考

工具

echo

使用可选的转换回显消息。

输入：

  • message （string）：要回显的消息
  • uppercase （布尔值，可选）：转换为大写
  • repeat （数字，可选）：重复计数（1-10）

例子：

{
  "message": "Hello, MCP!",
  "uppercase": true,
  "repeat": 2
}

calculate

执行基本的数学运算。

输入：

  • operation （枚举）： add, subtract, multiply, divide
  • a （number）：第一个操作数
  • b （number）：第二个操作数

例子：

{
  "operation": "add",
  "a": 5,
  "b": 3
}

资源

config://server/info

服务器配置和运行时信息（缓存30秒）。

time://current

ISO 8601格式的当前服务器时间。

健康终点

仅HTTP模式：

  • GET /health -详细的健康状况
  • GET /healthz -与/健康相同
  • GET /ready -准备就绪探针
  • GET /sse -SSE连接端点

发展

观看模式

npm run dev

类型检查

npm run typecheck

清理构建工件

npm run clean

认证

API密钥

集 API_KEYS 在 .env:

API_KEYS=key1,key2,key3

客户必须包括：

Authorization: Bearer <api-key>

OAuth2

配置OAuth2设置：

OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_ISSUER_URL=https://your-issuer.com

注： OAuth2令牌验证是一个占位符。实施JWT验证以供生产使用。

速率限制

带可配置参数的令牌桶算法：

  • RATE_LIMIT_TOKENS：最大令牌数（默认值：100）
  • RATE_LIMIT_REFILL_RATE：每个间隔添加的令牌（默认值：10）
  • RATE_LIMIT_REFILL_INTERVAL：重新填充间隔（毫秒）（默认值：1000）

每个请求消耗1个令牌。速率限制是每个客户端的（由API密钥或IP标识）。

可观测性

日志记录

使用Pino的结构化JSON日志。集 LOG_PRETTY=true 为了发展。

开放遥测

启用 OTEL_ENABLED=true 并配置导出器：

OTEL_SERVICE_NAME=mcp-server-template
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

支持通过OTLP导出跟踪、指标和日志。

优雅关闭

服务器处理 SIGINT 和 SIGTERM 优雅：

  1. 停止接受新连接
  2. 等待2秒等待飞行中的请求
  3. 关闭MCP服务器
  4. 清理资源（速率限制器、缓存、遥测）
  5. 退出

错误处理

标准化MCP错误代码：

  • -32700：分析错误
  • -32600：无效请求
  • -32601：未找到方法
  • -32602：无效参数
  • -32603：内部错误
  • -32001：未找到资源
  • -32002：资源不可用
  • -32003：未找到工具
  • -32004：工具执行错误
  • -32005：身份验证错误
  • -32006：超出费率限制

扩展服务器

添加工具

  1. 在中创建新文件 src/tools/
  2. 定义Zod模式以进行输入验证
  3. 使用工具 execute 方法
  4. 导出并添加到 tools 数组输入 src/tools/example.ts

添加资源

  1. 在中创建新文件 src/resources/
  2. 定义资源 uri, name, description, mimeType
  3. 实施 read 方法
  4. 导出并添加到 resources 数组输入 src/resources/example.ts

添加中间件

  1. 在中创建新文件 src/middleware/
  2. 实现中间件逻辑
  3. 连接到请求处理程序 src/server.ts

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

  • TypeScript严格模式合规性
  • 正确的错误处理
  • 新功能测试
  • 文档更新

内置：

相关 MCP