MCP Servers - MCP Server

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/

职责：
- 实现核心业务逻辑
- 处理数据转换
- 调用外部 API
主要文件：
- XXXService.ts: 具体业务服务
特点：
- 业务逻辑封装
- 数据处理和转换
- 外部服务集成

服务入口（index.ts）

位置：服务目录/index.ts

职责：
- 初始化服务实例
- 注册 MCP 工具
- 处理标准输入输出
特点：
- 统一的入口点
- MCP 工具注册
- 错误处理

开发流程

新建服务

mkdir -p src/new-service/{config,controllers,service}

实现各层功能
- 配置层：定义常量和类型
- 控制器层：处理请求和响应
- 服务层：实现业务逻辑
创建配置文件
- package.json: 服务依赖和脚本
- tsconfig.json: TypeScript 配置
编写入口文件
- 创建 index.ts
- 注册 MCP 工具
- 实现请求处理

快速开始

1. 克隆项目

git clone <repository-url>
cd mcp-servers

2. 安装依赖

npm install

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