MCP Servers

Una colección de servidores MCP para Cursor IDE, que incluye servicios de demostración y clima.

GitHubPrueba este MCPPatrocinado

Documentación

Proyecto MCP Servers

Colección de servicios desarrollados basados en el Protocolo de Contexto de Modelo (MCP), para soportar las funciones inteligentes de Cursor IDE. Actualmente incluye un servicio de ejemplo y un servicio meteorológico.

Requisitos del entorno de desarrollo

  • Node.js >= 16.0.0
  • npm >= 8.0.0
  • TypeScript >= 4.5.0
  • Cursor IDE (última versión)

Estructura del proyecto

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             # 项目文档

Arquitectura de capas de código

El proyecto adopta un diseño de arquitectura de tres capas, y cada servicio sigue el mismo patrón estructural:

1. Capa de configuración (Config)

Ubicación: 服务目录/config/

  • Responsabilidades:
    • Definir constantes y elementos de configuración
    • Declarar tipos e interfaces
    • Gestionar variables de entorno
  • Archivos principales:
    • constants.ts: Definición de constantes
    • types.ts: Definición de tipos
  • Características:
    • Gestión centralizada de configuración
    • Seguridad de tipos
    • Fácil de mantener y modificar

2. Capa de controladores (Controllers)

Ubicación: 服务目录/controllers/

  • Responsabilidades:
    • Procesar solicitudes y respuestas de MCP
    • Validación de parámetros y manejo de errores
    • Invocar métodos de la capa de servicios
  • Archivos principales:
    • XXXController.ts: Controlador de negocio específico
  • Características:
    • Validación de parámetros de solicitud
    • Manejo de errores y registros
    • Formateo de respuestas

3. Capa de servicios (Service)

Ubicación: 服务目录/service/

  • Responsabilidades:
    • Implementar la lógica de negocio principal
    • Procesar transformación de datos
    • Invocar API externas
  • Archivos principales:
    • XXXService.ts: Servicio de negocio específico
  • Características:
    • Encapsulación de lógica de negocio
    • Procesamiento y transformación de datos
    • Integración de servicios externos

Punto de entrada del servicio (index.ts)

Ubicación: 服务目录/index.ts

  • Responsabilidades:
    • Inicializar instancias de servicio
    • Registrar herramientas MCP
    • Procesar entrada y salida estándar
  • Características:
    • Punto de entrada unificado
    • Registro de herramientas MCP
    • Manejo de errores

Flujo de desarrollo

  1. Crear un nuevo servicio

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

  2. Implementar las funciones de cada capa

    • Capa de configuración: definir constantes y tipos
    • Capa de controladores: procesar solicitudes y respuestas
    • Capa de servicios: implementar lógica de negocio

  3. Crear archivos de configuración

    • package.json: Dependencias y scripts del servicio
    • tsconfig.json: Configuración de TypeScript

  4. Escribir el archivo de entrada

    • Crear index.ts
    • Registrar herramientas MCP
    • Implementar el manejo de solicitudes

Inicio rápido

1. Clonar el proyecto

git clone <repository-url>
cd mcp-servers

2. Instalar dependencias

npm install

3. Compilar el proyecto

# 构建所有服务
npm run build

# 构建单个服务
npm run build:weather  # 构建天气服务
npm run build:demo    # 构建示例服务

4. Configurar MCP

Editar el archivo ~/.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. Iniciar el servicio

# 启动天气服务
npm run start:weather

# 启动示例服务
npm run start:demo

Descripción de los servicios disponibles

1. Servicio de ejemplo (Demo)

  • Ubicación: src/demo/
  • Función: mostrar la estructura básica y el método de desarrollo de los servicios MCP
  • Características:
    • Ejemplo simple de solicitud y respuesta
    • Manejo básico de errores
    • Comentarios de código completos, adecuado para aprender

2. Servicio meteorológico (Weather)

  • Ubicación: src/weather/
  • Función: proporcionar un servicio de consulta meteorológica global
  • Características:
    • Consulta meteorológica en tiempo real
    • Pronóstico meteorológico de 5 días
    • Soporte para consulta de múltiples ciudades
    • Información meteorológica detallada

Consulte la documentación detallada de cada servicio:

Guía de desarrollo

Crear un nuevo servicio

  1. Crear un nuevo directorio de servicio en el directorio src
  2. Consultar la estructura de directorios de los servicios existentes
  3. Implementar los controladores y servicios necesarios
  4. Agregar los scripts de compilación e inicio correspondientes en package.json

Métodos de depuración

  1. Usar console.error() para generar información de depuración
  2. Revisar los registros MCP de Cursor IDE
  3. Usar la función de mapas de código fuente de TypeScript

Pruebas

# 运行所有测试
npm test

# 运行特定服务的测试
npm run test:weather

Preguntas frecuentes

  1. El servicio no puede iniciarse

    • Verificar la ocupación del puerto
    • Confirmar la configuración de variables de entorno
    • Verificar la salida de compilación

  2. La llamada a la API falla

    • Verificar la configuración de la clave de API
    • Confirmar la conexión de red
    • Revisar los registros de errores

  3. Cursor IDE no puede reconocer el servicio

    • Verificar la configuración de MCP
    • Reiniciar Cursor IDE
    • Confirmar el estado del servicio

Guía de contribución

  1. Hacer fork del proyecto
  2. Crear una rama de características
  3. Confirmar los cambios
  4. Enviar a la rama
  5. Crear un Pull Request

Licencia

MIT License