MCP Servers 项目
基于 Model Context Protocol (MCP) 开发的服务集合，用于支持 Cursor IDE 的智能功能。目前包含示例服务和天气服务。
开发环境要求
- Node.js >= 16.0.0
- npm >= 8.0.0
- TypeScript >= 4.5.0
- Cursor IDE（最新版本）
项目结构
mcp-servers/
├── src/ # 源代码目录
│ ├── demo/ # 示例服务
│ │ ├── config/ # 配置层：常量、类型定义
│ │ │ ├── constants.ts # 常量定义
│ │ │ └── types.ts # 类型定义
│ │ ├── controllers/ # 控制器层：请求处理
│ │ │ └── GreetingController.ts # 问候控制器
│ │ ├── service/ # 服务层：业务逻辑
│ │ │ └── GreetingService.ts # 问候服务
│ │ ├── package.json # 服务配置文件
│ │ ├── tsconfig.json # TypeScript 配置
│ │ └── index.ts # 服务入口文件
│ │
│ └── weather/ # 天气服务
│ ├── config/ # 配置层：常量、类型定义
│ │ ├── constants.ts # 常量定义
│ │ └── types.ts # 类型定义
│ ├── controllers/ # 控制器层：请求处理
│ │ └── WeatherController.ts # 天气控制器
│ ├── service/ # 服务层：业务逻辑
│ │ └── WeatherService.ts # 天气服务
│ ├── package.json # 服务配置文件
│ ├── tsconfig.json # TypeScript 配置
│ └── index.ts # 服务入口文件
│
├── build/ # 编译输出目录
├── node_modules/ # 依赖包
├── package.json # 项目配置
├── tsconfig.json # TypeScript 配置
└── README.md # 项目文档
代码分层架构
项目采用三层架构设计，每个服务都遵循相同的结构模式：
1. 配置层（Config）
位置：服务目录/config/
- 职责：
- 主要文件：
constants.ts: 常量定义types.ts: 类型定义
- 特点：
2. 控制器层（Controllers）
位置：服务目录/controllers/
- 职责：
- 处理 MCP 请求和响应
- 参数验证和错误处理
- 调用服务层方法
- 主要文件：
XXXController.ts: 具体业务控制器
- 特点：
3. 服务层（Service）
位置：服务目录/service/
服务入口（index.ts）
位置：服务目录/index.ts
- 职责：
- 初始化服务实例
- 注册 MCP 工具
- 处理标准输入输出
- 特点：
开发流程
-
新建服务
mkdir -p src/new-service/{config,controllers,service}
-
实现各层功能
- 配置层：定义常量和类型
- 控制器层：处理请求和响应
- 服务层：实现业务逻辑
-
创建配置文件
package.json: 服务依赖和脚本tsconfig.json: TypeScript 配置
-
编写入口文件
- 创建
index.ts
- 注册 MCP 工具
- 实现请求处理
快速开始
1. 克隆项目
2. 安装依赖
3. 构建项目
# 构建所有服务
npm run build
# 构建单个服务
npm run build:weather # 构建天气服务
npm run build:demo # 构建示例服务
4. 配置 MCP
编辑 ~/.cursor/mcp.json 文件：
{
"mcpServers": {
"weather": {
"command": "node",
"args": [
"/your/path/to/mcp-servers/build/weather/index.js"
],
"env": {
"OPENWEATHER_API_KEY": "your_api_key_here"
}
}
}
}
5. 启动服务
# 启动天气服务
npm run start:weather
# 启动示例服务
npm run start:demo
可用服务说明
1. 示例服务（Demo）
- 位置：
src/demo/
- 功能：展示 MCP 服务的基本结构和开发方法
- 特点：
- 简单的请求响应示例
- 基础错误处理
- 代码注释完善，适合学习
2. 天气服务（Weather）
- 位置：
src/weather/
- 功能：提供全球天气查询服务
- 特点：
- 实时天气查询
- 5天天气预报
- 支持多城市查询
- 详细的天气信息
查看各服务详细文档：
开发指南
创建新服务
- 在
src 目录下创建新服务目录
- 参考现有服务的目录结构
- 实现必要的控制器和服务
- 在
package.json 添加相应的构建和启动脚本
调试方法
- 使用
console.error() 输出调试信息
- 检查 Cursor IDE 的 MCP 日志
- 使用 TypeScript 的源码映射功能
测试
# 运行所有测试
npm test
# 运行特定服务的测试
npm run test:weather
常见问题
-
服务无法启动
-
API 调用失败
- 检查 API Key 配置
- 确认网络连接
- 查看错误日志
-
Cursor IDE 无法识别服务
- 检查 MCP 配置
- 重启 Cursor IDE
- 确认服务状态
贡献指南
- Fork 项目
- 创建特性分支
- 提交变更
- 推送到分支
- 创建 Pull Request
许可证
MIT License
