marcos2872/generic-mcp-server

Generic MCP Server

Um servidor MCP (Model Context Protocol) genérico e configurável para integração com APIs externas, inicialmente configurado para as APIs públicas da NASA. Este projeto permite criar ferramentas MCP dinamicamente através de um arquivo de configuração JSON, facilitando a extensão para outras APIs.

Funcionalidades

• Configurável: Defina ferramentas e endpoints via config.json.
• Suporte a Autenticação: API Keys, Bearer Tokens e outros tipos.
• Flexibilidade: Parâmetros em query, body ou path.
• Integração com MCP: Compatível com o protocolo Model Context Protocol para uso em aplicações como Claude Desktop.

Instalação

1. Clone o repositório ou baixe os arquivos.
2. Navegue até o diretório do projeto:

   cd generic-mcp-server
   

3. Instale as dependências:

   npm install
   

   ou

   pnpm install
   

Configuração

Arquivo config.json

O arquivo config.json define as informações do servidor e as ferramentas disponíveis. Ele está localizado na raiz do projeto.

Exemplo de estrutura:

{
  "serverInfo": {
    "name": "generic-mcp-server",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "nome_da_ferramenta",
      "description": "Descrição da ferramenta",
      "inputSchema": {
        "type": "object",
        "properties": {
          "parametro": {
            "type": "string",
            "description": "Descrição do parâmetro"
          }
        },
        "required": ["parametro"]
      },
      "apiConfig": {
        "baseUrl": "https://api.exemplo.com",
        "path": "/endpoint",
        "pathTemplate": "/endpoint/{param}",
        "method": "GET",
        "paramLocation": "query",
        "auth": {
          "type": "apiKey",
          "paramName": "api_key",
          "envVar": "API_KEY_ENV"
        },
        "responseType": "json"
      }
    }
  ]
}

• serverInfo: Informações básicas do servidor.
• tools: Array de ferramentas, cada uma com:
  • name: Nome único da ferramenta.
  • description: Descrição para o usuário.
  • inputSchema: Esquema JSON Schema para os parâmetros de entrada.
  • apiConfig: Configuração da API:
    • baseUrl: URL base da API.
    • path: Caminho do endpoint (usado se não houver pathTemplate).
    • pathTemplate: Caminho com placeholders (ex: /users/{id}).
    • method: Método HTTP (GET, POST, etc.).
    • paramLocation: Onde colocar os parâmetros ("query" ou "body").
    • auth: Configuração de autenticação (opcional).
    • responseType: Tipo de resposta ("json" ou "redirectUrl").

Configurando para Outras APIs

Para usar o servidor com outras APIs além da NASA, substitua o conteúdo do config.json existente pelos dados da nova configuração. Você pode criar arquivos de exemplo na pasta jsons/ para referência.

Exemplo: Para uma API de clima (como OpenWeatherMap), substitua o conteúdo do config.json pelo seguinte:

{
  "serverInfo": {
    "name": "weather-mcp-server",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "get_current_weather",
      "description": "Obtém o clima atual para uma cidade específica",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "Nome da cidade (ex: 'London')"
          },
          "units": {
            "type": "string",
            "description": "Unidades de medida: 'metric', 'imperial' ou 'standard'",
            "enum": ["metric", "imperial", "standard"],
            "default": "metric"
          }
        },
        "required": ["city"]
      },
      "apiConfig": {
        "baseUrl": "https://api.openweathermap.org/data/2.5",
        "path": "/weather",
        "method": "GET",
        "paramLocation": "query",
        "auth": {
          "type": "apiKey",
          "paramName": "appid",
          "envVar": "OPENWEATHER_API_KEY"
        },
        "responseType": "json"
      }
    }
  ]
}

Certifique-se de definir as variáveis de ambiente necessárias (ex: OPENWEATHER_API_KEY).

Variáveis de Ambiente

Para ferramentas que requerem autenticação, defina as variáveis de ambiente correspondentes. Por exemplo:

export NASA_API_KEY="sua_chave_aqui"

No config.json, use "envVar": "NASA_API_KEY".

Uso

Executando o Servidor

Execute o servidor com:

node index.js

Ou usando o binário definido no package.json:

npx generic-mcp-server

O servidor se conecta via stdio e lê o config.json automaticamente.

Integração com MCP Clients

Para usar com aplicações MCP como Claude Desktop, configure o cliente para executar este servidor. Exemplo de configuração no claude_desktop_config.json:

{
  "mcpServers": {
    "generic-mcp-server": {
      "command": "node",
      "args": ["/caminho/para/generic-mcp-server/index.js"]
    }
  }
}

Substitua /caminho/para/generic-mcp-server/index.js pelo caminho absoluto.

Ferramentas Disponíveis

As ferramentas são definidas no config.json. Atualmente, o projeto inclui ferramentas para APIs da NASA:

1. get_apod

   • Descrição: Obtém a Astronomy Picture of the Day (APOD) da NASA.
   • Parâmetros:
     • date (opcional): Data no formato YYYY-MM-DD.
     • hd (opcional): Booleano para imagem em alta definição.

2. search_nasa_images

   • Descrição: Busca imagens, vídeos e áudios no arquivo da NASA.
   • Parâmetros:
     • q (obrigatório): Termo de busca.
     • media_type (opcional): "image", "video" ou "audio".
     • year_start (opcional): Ano inicial (YYYY).
     • year_end (opcional): Ano final (YYYY).

3. get_mars_rover_photos

   • Descrição: Obtém fotos dos rovers de Marte.
   • Parâmetros:
     • rover (obrigatório): "curiosity", "opportunity" ou "spirit".
     • sol (opcional): Sol marciano.
     • earth_date (opcional): Data terrestre (YYYY-MM-DD).
     • camera (opcional): Câmera específica.

4. get_neo_feed

   • Descrição: Obtém dados sobre asteroides próximos à Terra.
   • Parâmetros:
     • start_date (opcional): Data inicial (YYYY-MM-DD).
     • end_date (opcional): Data final (YYYY-MM-DD).

5. get_earth_imagery

   • Descrição: Obtém imagens de satélite da Terra.
   • Parâmetros:
     • lat (obrigatório): Latitude.
     • lon (obrigatório): Longitude.
     • date (opcional): Data (YYYY-MM-DD).
     • dim (opcional): Dimensão em graus.

Desenvolvimento

Para adicionar novas ferramentas, edite o config.json e adicione entradas no array tools. Certifique-se de que o inputSchema corresponda aos parâmetros esperados.

Para estender o código, modifique index.js para suportar novos tipos de autenticação ou tratamento de resposta.

Contribuição

Contribuições são bem-vindas! Abra issues ou pull requests no repositório.

Licença

Este projeto está licenciado sob a ISC License.