MCP Servers

Uma coleção de servidores MCP para Cursor IDE, incluindo serviços de demonstração e clima.

GitHubExperimente este MCPPatrocinado

Documentação

Projeto MCP Servers

Conjunto de serviços desenvolvidos com base no Model Context Protocol (MCP), para suportar os recursos inteligentes do Cursor IDE. Atualmente inclui um serviço de exemplo e um serviço de clima.

Requisitos do ambiente de desenvolvimento

  • Node.js >= 16.0.0
  • npm >= 8.0.0
  • TypeScript >= 4.5.0
  • Cursor IDE (versão mais recente)

Estrutura do projeto

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

Arquitetura em camadas de código

O projeto adota um design de arquitetura em três camadas, e cada serviço segue o mesmo padrão estrutural:

1. Camada de configuração (Config)

Localização: 服务目录/config/

  • Responsabilidades:
    • Definir constantes e itens de configuração
    • Declarar tipos e interfaces
    • Gerenciar variáveis de ambiente
  • Arquivos principais:
    • constants.ts: Definição de constantes
    • types.ts: Definição de tipos
  • Características:
    • Gerenciamento centralizado de configuração
    • Segurança de tipos
    • Fácil de manter e modificar

2. Camada de controladores (Controllers)

Localização: 服务目录/controllers/

  • Responsabilidades:
    • Processar requisições e respostas MCP
    • Validação de parâmetros e tratamento de erros
    • Chamar métodos da camada de serviço
  • Arquivos principais:
    • XXXController.ts: Controlador de negócios específico
  • Características:
    • Validação de parâmetros de requisição
    • Tratamento de erros e logs
    • Formatação de respostas

3. Camada de serviço (Service)

Localização: 服务目录/service/

  • Responsabilidades:
    • Implementar a lógica de negócios principal
    • Processar transformação de dados
    • Chamar APIs externas
  • Arquivos principais:
    • XXXService.ts: Serviço de negócios específico
  • Características:
    • Encapsulamento da lógica de negócios
    • Processamento e transformação de dados
    • Integração com serviços externos

Ponto de entrada do serviço (index.ts)

Localização: 服务目录/index.ts

  • Responsabilidades:
    • Inicializar instâncias de serviço
    • Registrar ferramentas MCP
    • Processar entrada e saída padrão
  • Características:
    • Ponto de entrada unificado
    • Registro de ferramentas MCP
    • Tratamento de erros

Fluxo de desenvolvimento

  1. Criar novo serviço

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

  2. Implementar as funcionalidades de cada camada

    • Camada de configuração: definir constantes e tipos
    • Camada de controladores: processar requisições e respostas
    • Camada de serviço: implementar a lógica de negócios

  3. Criar arquivos de configuração

    • package.json: dependências e scripts do serviço
    • tsconfig.json: configuração do TypeScript

  4. Escrever o arquivo de entrada

    • Criar index.ts
    • Registrar ferramentas MCP
    • Implementar o processamento de requisições

Início rápido

1. Clonar o projeto

git clone <repository-url>
cd mcp-servers

2. Instalar dependências

npm install

3. Compilar o projeto

# 构建所有服务
npm run build

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

4. Configurar o MCP

Editar o arquivo ~/.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 o serviço

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

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

Descrição dos serviços disponíveis

1. Serviço de exemplo (Demo)

  • Localização: src/demo/
  • Funcionalidade: demonstrar a estrutura básica e o método de desenvolvimento de serviços MCP
  • Características:
    • Exemplo simples de requisição e resposta
    • Tratamento básico de erros
    • Comentários de código completos, adequado para aprendizado

2. Serviço de clima (Weather)

  • Localização: src/weather/
  • Funcionalidade: fornecer serviço de consulta de clima global
  • Características:
    • Consulta de clima em tempo real
    • Previsão do tempo para 5 dias
    • Suporte a consulta de múltiplas cidades
    • Informações meteorológicas detalhadas

Consulte a documentação detalhada de cada serviço:

Guia de desenvolvimento

Criar novo serviço

  1. Criar um novo diretório de serviço no diretório src
  2. Consultar a estrutura de diretórios dos serviços existentes
  3. Implementar os controladores e serviços necessários
  4. Adicionar os scripts de compilação e inicialização correspondentes em package.json

Métodos de depuração

  1. Usar console.error() para gerar informações de depuração
  2. Verificar os logs MCP do Cursor IDE
  3. Usar o recurso de mapeamento de código-fonte do TypeScript

Testes

# 运行所有测试
npm test

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

Perguntas frequentes

  1. O serviço não inicia

    • Verificar se a porta está em uso
    • Confirmar a configuração das variáveis de ambiente
    • Validar a saída da compilação

  2. Falha na chamada da API

    • Verificar a configuração da API Key
    • Confirmar a conexão de rede
    • Consultar os logs de erro

  3. O Cursor IDE não reconhece o serviço

    • Verificar a configuração do MCP
    • Reiniciar o Cursor IDE
    • Confirmar o status do serviço

Guia de contribuição

  1. Fazer fork do projeto
  2. Criar um branch de funcionalidade
  3. Enviar as alterações
  4. Enviar para o branch
  5. Criar um Pull Request

Licença

MIT License