Ts Template MCP

TypeScript MCP服务器模板

全面 TypeScript MCP服务器模板 跟随 官方MCP TypeScript SDK 最佳实践，基于 禁食 以及提供工具、资源和提示。

📖 西班牙语自述 -对于喜欢西班牙语文档的用户

📌 如何使用或贡献

此存储库可作为 合作项目 以及a 模板:

• 用作模板 → 通过单击立即创建自己的MCP服务器项目 使用此模板.
• 促进改进 → 分叉此仓库，进行更改，并发送Pull Request，以便我们审查和整合它们。

我们欢迎：

• 新的MCP工具、资源和提示
• 性能优化
• 文档改进
• Bug修复和代码质量增强

如果您基于此模板创建内容，请在README中提及此存储库。

🛠️ 技术栈和工具详解

核心技术

• TypeScript -具有编译时错误检查的类型安全开发
• 禁食 -用于构建API的快速高效的web框架
• @模型上下文协议/sdk -用于AI模型集成的官方MCP服务器SDK

开发工具

• 萨德 -API输入的运行时类型验证和架构定义
• @fastify/cors -CORS支持web客户端访问API
• 多伦多证券交易所 -无需编译步骤的现代TypeScript执行
• 皮诺漂亮 -具有结构化输出的漂亮开发日志

代码质量工具

• 埃斯林特 -静态代码分析，以捕捉错误并执行编码标准
• 更漂亮 -自动代码格式化，风格一致
• 哈士奇 -Git钩子在提交前运行质量检查
• 皮棉上演 -仅对暂存文件运行linters，以获得更快的反馈

部署工具

• 码头工人 -容器化，实现跨环境的一致部署
• Docker Compose -用于开发和生产的多容器编排

📦 项目结构

ts-template-mcp-server/
├── src/
│   ├── server.ts              # Main MCP server with HTTP/STDIO transport
│   ├── config/
│   │   └── constants.ts       # Centralized configuration constants
│   ├── utils/
│   │   ├── errorHandler.ts    # Centralized error handling utilities
│   │   └── logger.ts          # Structured logging with Pino
│   ├── schemas/
│   │   ├── toolSchemas.ts     # Zod schemas for MCP tool validation
│   │   └── commonSchemas.ts   # Reusable validation schemas
│   └── plugins/
│       ├── helloPlugin.ts     # Fastify plugin with REST endpoint
│       └── weatherPlugin.ts   # Weather tools with Zod validation
├── .github/workflows/
│   └── ci.yml                 # GitHub Actions CI/CD pipeline
├── client-example.js          # Example client for testing MCP features
├── Dockerfile                 # Multi-stage Docker build configuration
├── docker-compose.yml         # Docker Compose for local development
├── .dockerignore              # Docker build context exclusions
├── DOCKER_TROUBLESHOOTING.md  # Docker issues and solutions documentation
├── DOCKER_BEST_PRACTICES.md   # Docker best practices guide
├── CHANGELOG.md               # Version history and release notes
├── AI_GUIDELINES.md           # AI development guidelines and conventions
├── AI_PROMPT_EXAMPLES.md      # Specific prompt examples for AI assistance
├── AI_QUICK_START.md          # Quick start guide for AI assistants
├── README_ES.md              # Spanish documentation for non-English speakers
├── .eslintrc.json            # ESLint configuration with TypeScript rules
├── .prettierrc               # Prettier formatting rules
├── .husky/pre-commit         # Git hook to run lint-staged
├── env.example               # Environment variables template
├── tsconfig.json             # TypeScript compiler configuration
├── package.json              # Dependencies and npm scripts
└── README.md                 # This comprehensive documentation

🚀 入门指南

1.安装依赖项

npm install

这有什么作用： 安装所有必需的依赖项，包括TypeScript、Fastify、MCP SDK和开发工具。

2.环境设置

复制环境示例文件并配置变量：

cp env.example .env

这有什么作用： 创建具有以下配置的本地环境文件：

• 服务器设置（端口、主机）
• MCP配置（STDIO模式，会话超时）
• 日志记录级别和格式
• CORS设置
• 外部API密钥（气象服务）

3.启动开发服务器

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

npm run dev

STDIO模式（适用于Claude Desktop等CLI客户端）：

npm run dev:stdio

调试模式（带详细日志记录）：

npm run dev:debug

每种模式的作用：

• HTTP模式：为基于web的MCP客户端在端口3000上启动服务器
• STDIO模式：作为桌面AI应用程序的CLI进程运行
• 调试模式：启用详细日志记录以进行故障排除

4.为生产而建造

# Clean previous build (optional)
npm run clean

# Compile TypeScript to JavaScript
npm run build

# Run the compiled server
npm start

这有什么作用：

• clean：删除旧的构建工件
• build：将TypeScript编译为优化的JavaScript
• start：运行生产服务器

生产STDIO模式：

npm run start:stdio

🌐 可用端点

HTTP模式：服务器启动于 http://localhost:3000 使用这些端点：

MCP协议端点

• POST /mcp -模型上下文协议接口（处理所有MCP操作）

- 目的：AI模型与工具和资源交互的主界面 - 用法：使用MCP方法发送JSON-RPC 2.0请求

REST API端点

• GET /hello/:name -传统的REST API端点

- 目的：混合REST+MCP服务器示例 - 用法: curl http://localhost:3000/hello/YourName

天气插件端点

• GET /weather/forecast?lat=40.7128&lng=-74.0060 -天气预报

- 目的：获取特定坐标的天气数据 - 用法: curl "http://localhost:3000/weather/forecast?lat=40.7128&lng=-74.0060"

• GET /weather/alerts/:state -美国各州天气警报

- 目的：获取美国特定州的天气警报 - 用法: curl http://localhost:3000/weather/alerts/CA

监控端点

• GET /health -通过会话信息增强服务器状态

- 目的：具有详细指标的健康检查 - 用法: curl http://localhost:3000/health

• GET /info -服务器功能和端点

- 目的：发现可用功能 - 用法: curl http://localhost:3000/info

STDIO模式：服务器作为CLI进程运行，用于与Claude Desktop等MCP客户端直接集成。

🧪 测试服务器

快速健康检查

curl http://localhost:3000/health

预期响应：

{
  "status": "ok",
  "timestamp": "2025-07-25T12:00:00.000Z",
  "server": "ts-template-mcp-server",
  "version": "1.0.0",
  "uptime": 123.456,
  "sessions": 0,
  "capabilities": ["tools", "resources"]
}

这个告诉你：

• 服务器正在运行且状态良好
• 当前时间戳和正常运行时间
• 活动MCP会话数
• 可用MCP功能

使用客户端示例

附带的客户端示例演示了所有MCP功能：

node client-example.js

这表明：

• ✅ 连接：建立与MCP服务器的连接
• 🔧 工具：列出并调用MCP工具
• 📚 资源：列出并阅读MCP资源
• 💭 提示：列出并获取MCP提示
• 🚨 错误处理：正确的错误处理示例

🔧 MCP功能说明

🛠️ 工具-它们是什么以及如何使用

工具 是AI模型可以调用以执行动作的函数。每个工具：

• 具有名称、描述和输入模式
• 使用Zod模式验证输入
• 返回结构化结果

可用工具：

1. sayHello 工具

目的：用于测试MCP通信的简单问候工具 输入：人员姓名 使用示例：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: test-session" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "sayHello",
      "arguments": {
        "name": "Developer"
      }
    }
  }'

2. calculate 工具

目的：执行算术运算 输入：操作类型和两个数字 使用示例：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: test-session" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "operation": "multiply",
        "a": 15,
        "b": 7
      }
    }
  }'

3. getWeatherForecast 工具

目的：获取特定坐标的天气预报 输入：纬度和经度 用法：由AI模型调用以获取天气数据

4. getWeatherAlerts 工具

目的：获取美国各州的天气警报 输入：美国州名 用法：由AI模型调用以获取天气警报

📋 Zod验证-为什么它很重要

萨德 提供与TypeScript类型匹配的运行时类型验证：

// Example: Weather forecast tool validation
const WeatherForecastSchema = z.object({
  latitude: z.number().min(-90).max(90),
  longitude: z.number().min(-180).max(180)
});

// Usage in tool
const { latitude, longitude } = validateToolArgs(WeatherForecastSchema, args);

优点：

• ✅ 类型安全：运行时验证与TypeScript类型匹配
• ✅ 更好的错误：描述性验证错误消息
• ✅ 可重复使用性：通用模式可以在工具之间共享
• ✅ 可维护性：集中验证逻辑

📚 资源-它们是什么以及如何使用

资源 是AI模型可以读取的数据源。每个资源：

• 具有URI方案(mcp://, file://等等）
• 包含结构化数据
• 可以多次阅读

可用资源：

1.服务器信息(mcp://server-info)

目的：提供服务器元数据和功能 用途：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: test-session" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "resources/read",
    "params": {
      "uri": "mcp://server-info"
    }
  }'

2.你好留言(mcp://hello-message)

目的：包含问候内容的示例资源 用途：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: test-session" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "resources/read",
    "params": {
      "uri": "mcp://hello-message"
    }
  }'

💭 提示-它们是什么以及如何使用

提示 是AI模型可以使用的模板消息。每个提示：

• 有名称和描述
• 接受自定义参数
• 返回格式化邮件

可用提示：

问候提示(greeting-prompt)

目的：生成个性化问候 用途：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: test-session" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "prompts/get",
    "params": {
      "name": "greeting-prompt",
      "arguments": {
        "name": "Alice",
        "style": "enthusiastic"
      }
    }
  }'

🏗️ 架构和最佳实践

使用的官方SDK模式

此模板遵循 MCP TypeScript SDK官方文档:

• ✅ 正确的请求处理程序：使用 setRequestHandler() 适用于所有MCP操作
• ✅ 会话管理：基于地图的传输实例会话存储
• ✅ 可流式HTTP传输：最新传输方法（未弃用SSE）
• ✅ 标准JSON模式：没有Zod依赖的正确工具输入模式
• ✅ 错误处理：通过适当的MCP错误响应进行全面的错误处理
• ✅ 资源URI方案：使用 mcp:// 遵循最佳实践的方案

基本实施的关键改进

1. 会话管理：正确的会话跟踪和清理
2. 增强的错误处理：详细的错误响应和日志记录
3. 多种功能：工具、资源、AND提示（许多示例仅显示一个）
4. 生产就绪：优雅的关机、健康检查、正确的日志记录
5. 类型安全：完全支持TypeScript，无需运行时模式验证开销
6. 代码质量：ESLint、Prettier和Husky用于代码一致性
7. 容器化：Docker支持，易于部署
8. CI/CD：用于自动化测试的GitHub Actions管道

集成功能

• 跨域资源共享：增强了web客户端的CORS配置
• 日志记录：使用pino进行结构化日志记录，非常适合开发
• 健康监测：具有会话度量的详细健康端点
• 休息+MCP：支持传统REST和MCP协议的混合服务器
• 错误处理：使用自定义错误类型进行集中错误处理
• 配置：集中配置管理

🔄 Git流工作流

该项目如下 Git流 有组织发展的方法论：

分支结构

• main -生产就绪代码
• develop -功能集成分支
• **feature/*** -新功能和改进
• **release/*** -发布准备
• **hotfix/*** -关键生产修复

开发工作流程

# Start a new feature
git flow feature start feature-name

# Work on your feature...
git add .
git commit -m "feat: add new feature"

# Finish the feature (merges to develop)
git flow feature finish feature-name

# Create a release
git flow release start v1.1.0

# Finish release (merges to main and develop)
git flow release finish v1.1.0

# Create hotfix for critical issues
git flow hotfix start critical-fix
git flow hotfix finish critical-fix

提交消息约定

我们跟随 常规承诺:

• feat: -新功能
• fix: -Bug修复
• docs: -文档更改
• style: -代码样式更改（格式等）
• refactor: -代码重构
• test: -添加或更新测试
• chore: -维护任务

🔧 开发工具详解

可用脚本

开发脚本

• npm run dev -使用热重新加载和漂亮的日志记录启动开发服务器

- 目的：带有实时重新加载的主开发命令 - 使用时间：开发新功能

• npm run dev:debug -从启用调试日志记录开始

- 目的：用于故障排除的详细日志记录 - 使用时间：调试问题或了解服务器行为

• npm run dev:stdio -CLI客户端以STDIO模式启动

- 目的：为桌面AI应用程序运行服务器 - 使用时间：使用Claude Desktop或类似工具进行测试

生成脚本

• npm run build -将TypeScript编译为JavaScript dist/ 文件夹

- 目的：创建生产就绪的JavaScript文件 - 使用时间：部署到生产环境

• npm run build:watch -使用手表模式构建

- 目的：文件更改时自动重建 - 使用时间：使用构建步骤进行开发

• npm start -运行已编译的服务器（生产模式）

- 目的：启动生产服务器 - 使用时间：在生产环境中运行

代码质量脚本

• npm run clean -删除已编译的文件

- 目的：清理构建工件 - 使用时间：解决构建问题

• npm run lint -运行ESLint

- 目的：检查代码质量和样式 - 使用时间：提交代码之前

• npm run lint:fix -运行ESLint并自动修复

- 目的：自动修复掉毛问题 - 使用时间：ESLint报告可修复的错误

• npm run format -使用Prettier格式化代码

- 目的：确保代码格式一致 - 使用时间：代码格式不一致

• npm run type-check -运行TypeScript类型检查

- 目的：在不构建的情况下验证TypeScript类型 - 使用时间：检查类型错误

• npm run validate -运行类型检查和除尘

- 目的：全面的代码质量检查 - 使用时间：在推送代码或创建PR之前

测试脚本

• npm test -运行测试（占位符）

- 目的：执行测试套件 - 使用时间：验证功能

环境要求

• Node.js：>=18.0.0（用于现代JavaScript功能）
• TypeScript：^5.7.2（用于类型安全）
• MCP-SDK：^1.0.4（用于MCP协议支持）

添加新的MCP工具

遵循官方SDK模式：

1. 添加工具定义 向 tools/list 处理程序：

{
  name: "myTool",
  description: "My custom tool",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}

1. 处理工具执行 在……里面 tools/call 处理程序：

case "myTool":
  const { param } = args as { param: string };
  return {
    content: [{ type: "text", text: `Result: ${param}` }]
  };

添加新资源

1. 增添 resources/list 处理器 -定义可用资源
2. 处理读入 resources/read 处理器 -实现资源读取逻辑
3. 使用正确的URI方案 (mcp://, file://等）-遵循MCP惯例

添加提示

1. 增添 prompts/list 处理器 -定义可用提示
2. 句柄生成 prompts/get 处理器 -实现提示生成逻辑
3. 返回正确的消息格式 带角色-遵循MCP提示格式

🐳 Docker支持

塑造形象

docker build -t ts-template-mcp-server .

这有什么作用：

• 创建多阶段Docker镜像
• 以最小的尺寸优化生产
• 包括所有必要的依赖关系

使用Docker运行

# Production mode
docker run -p 3000:3000 ts-template-mcp-server

# Development mode
docker-compose up mcp-server-dev

每个人做什么：

• 生产模式：运行优化的容器进行生产
• 开发模式：使用音量挂载进行实时开发

Docker Compose

# Start all services
docker-compose up

# Start only production server
docker-compose up mcp-server

# Start development server
docker-compose --profile dev up mcp-server-dev

这提供了什么：

• 多服务编排：轻松管理多个容器
• 发展概况：dev/prod的单独配置
• 卷装载：开发中的实时代码重新加载

Docker文档

有关Docker设置、故障排除和最佳实践的详细信息：

• **** -常见问题和解决方案
• **** -Node.js容器化的最佳实践

主要改进：

• ✅ 多阶段构建，优化生产图像
• ✅ 非root用户执行以确保安全
• ✅ 使用curl进行正确的健康检查配置
• ✅ 分离npm脚本以避免预启动钩子问题
• ✅ 全面的.doccerignore可实现更快的构建

🌐 CORS和安全

增强CORS配置以实现MCP兼容性：

• 起源：灵活的原产地处理(true 而不是 *)
• 标头：所有必需的MCP标头和标准web标头
• 方法：所有HTTP方法实现最大兼容性
• 会话安全：基于会话的传输隔离

🚨 故障排除

常见问题

1.端口已在使用中

# Check what's using port 3000
netstat -ano | findstr :3000

# Kill the process or change port in server.ts

这修复了什么： 解决启动服务器时的端口冲突

2.TypeScript编译错误

# Clean and rebuild
npm run clean
npm run build

这修复了什么： 解决了由过时文件引起的构建问题

3.MCP连接问题

• 确保正确 Mcp-Session-Id 头球
• 检查web客户端的CORS配置
• 验证请求中的JSON-RPC 2.0格式

这修复了什么： 解决MCP协议通信问题

4.STDIO模式不工作

# Ensure proper environment variable
export MCP_STDIO=true
npm run dev:stdio

这修复了什么： 确保服务器在CLI客户端的正确模式下运行

5.过梁错误

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

这修复了什么： 解决代码风格和质量问题

调试模式

通过设置环境变量启用调试日志记录：

DEBUG=mcp:* npm run dev

这提供了什么： 用于排除MCP问题的详细日志记录

性能监控

健康端点提供实时指标：

curl http://localhost:3000/health | jq

这表明： 服务器状态、正常运行时间、活动会话和功能

📚 了解更多

• 模型上下文协议规范
• TypeScript官方SDK
• MCP服务器示例
• Fastify文档
• Git流文档

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

我们鼓励两者 直接捐款 和 独立项目 基于此模板。

1. 合作:

- 分叉存储库。 - 使用Git Flow创建功能分支： git flow feature start feature-name. - 遵循MCP SDK官方文档中的模式。 - 如果适用，添加测试。 - 提交拉取请求。

1. 创建自己的项目而不链接回:

- 点击 使用此模板 并开始建设。

______________________________________________________________________

构建如下 MCP TypeScript官方SDK 最佳实践