MCP REST Server

Um servidor para interagir com APIs REST, com suporte a autenticação e documentação Swagger.

GitHubExperimente este MCPPatrocinado

Documentação

MCP REST Server

Um servidor Model Context Protocol (MCP) que fornece funcionalidade de cliente REST API com suporte a autenticação e integração com documentação Swagger.

Recursos

  • Múltiplos Métodos de Autenticação: Suporte para autenticação baseada em token e baseada em login
  • Integração Swagger: Descoberta automática de endpoints e documentação a partir de especificações OpenAPI/Swagger
  • Gerenciamento Automático de Token: Lida com renovação de token e reautenticação
  • Métodos HTTP Abrangentes: Suporte para requisições GET, POST, PUT, DELETE e PATCH
  • Tratamento de Erros: Tratamento robusto de erros com lógica de repetição
  • Compatível com MCP: Totalmente compatível com o Model Context Protocol

Instalação

npm install
npm run build

Desenvolvimento

npm run dev

Configuração

O servidor suporta dois métodos de autenticação:

Autenticação por Token

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-token-here"
  },
  "timeout": 30000,
  "retries": 3
}

Autenticação por Login

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "login",
    "username": "your-username",
    "password": "your-password",
    "loginEndpoint": "/auth/login",
    "tokenField": "access_token"
  },
  "timeout": 30000,
  "retries": 3
}

Ferramentas Disponíveis

1. configure_rest_client

Configure o cliente REST com autenticação e detalhes da API.

Parâmetros:

  • baseUrl (obrigatório): URL base para a API REST
  • auth (obrigatório): Configuração de autenticação (token ou login)
  • swaggerUrl (opcional): URL para documentação Swagger/OpenAPI
  • timeout (opcional): Tempo limite de requisição em milissegundos (padrão: 30000)
  • retries (opcional): Número de tentativas para requisições com falha (padrão: 3)

2. http_request

Faça requisições HTTP para a API configurada.

Parâmetros:

  • method (obrigatório): Método HTTP (GET, POST, PUT, DELETE, PATCH)
  • path (obrigatório): Caminho do endpoint da API
  • params (opcional): Parâmetros de consulta ou parâmetros do corpo da requisição
  • body (opcional): Corpo da requisição para requisições POST, PUT, PATCH
  • headers (opcional): Cabeçalhos adicionais

3. get_swagger_documentation

Obtenha a lista completa de endpoints disponíveis na documentação Swagger.

4. search_endpoints

Pesquise endpoints na documentação Swagger.

Parâmetros:

  • query (obrigatório): Consulta de pesquisa para encontrar endpoints correspondentes

5. get_endpoint_info

Obtenha informações detalhadas sobre um endpoint específico.

Parâmetros:

  • path (obrigatório): Caminho do endpoint
  • method (obrigatório): Método HTTP

6. check_authentication

Verifique se o cliente está autenticado no momento.

7. logout

Faça logout e limpe o estado de autenticação.

Exemplos de Uso

Configuração Básica

  1. Configure o cliente:
{
  "baseUrl": "https://jsonplaceholder.typicode.com",
  "auth": {
    "type": "token",
    "token": "dummy-token"
  }
}
  1. Faça uma requisição GET:
{
  "method": "GET",
  "path": "/posts/1"
}
  1. Faça uma requisição POST:
{
  "method": "POST",
  "path": "/posts",
  "body": {
    "title": "New Post",
    "body": "Post content",
    "userId": 1
  }
}

Com Documentação Swagger

{
  "baseUrl": "https://petstore.swagger.io/v2",
  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-key"
  }
}

Então você pode:

  • Pesquisar endpoints: search_endpoints com a consulta "pet"
  • Obter informações do endpoint: get_endpoint_info com o caminho "/pet" e método "POST"
  • Visualizar toda a documentação: get_swagger_documentation

Fluxo de Autenticação

Autenticação por Token

  1. O token é armazenado e usado imediatamente
  2. Adicionado às requisições como Authorization: Bearer <token>
  3. Se 401 for recebido, não há repetição automática (token considerado inválido)

Autenticação por Login

  1. Faz requisição de login para o endpoint especificado
  2. Extrai o token da resposta usando tokenField
  3. Armazena o token em memória
  4. Adiciona o token às requisições subsequentes
  5. Se 401 for recebido, reautentica automaticamente e tenta novamente

Tratamento de Erros

  • Erros de rede: Repetição automática com backoff exponencial
  • Erros de autenticação: Reautenticação automática para autenticação baseada em login
  • Erros de validação: Mensagens de erro claras com detalhes
  • Erros de API: Encaminhamento do status HTTP e mensagem de erro

Desenvolvimento

Estrutura do Projeto

src/
├── types.ts          # TypeScript type definitions
├── auth.ts           # Authentication manager
├── swagger.ts        # Swagger documentation parser
├── rest-client.ts    # REST client implementation
└── index.ts          # MCP server implementation

Compilação

npm run build

Execução

npm start

Configuração do Cliente MCP

O servidor MCP REST agora suporta configuração automática através de múltiplos métodos, eliminando a necessidade de configurar APIs manualmente para cada projeto.

Métodos de Configuração (em ordem de prioridade)

  1. Argumentos de Linha de Comando (maior prioridade)
  2. Variáveis de Ambiente
  3. Arquivo de Configuração
  4. Configuração Manual (via ferramentas MCP - menor prioridade)

Configuração do Cursor

Opção 1: Auto-configuração com Variáveis de Ambiente (Recomendado)

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://api.github.com",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-github-token-here",
        "MCP_REST_SWAGGER_URL": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      }
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://petstore.swagger.io/v2",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-api-key",
        "MCP_REST_SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

Opção 2: Auto-configuração com Arquivos de Configuração

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/github-api.json"]
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/petstore.json"]
    }
  }
}

Opção 3: Auto-configuração com Argumentos de Linha de Comando

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-rest/dist/index.js",
        "--base-url", "https://api.github.com",
        "--auth-type", "token",
        "--token", "your-github-token-here",
        "--swagger-url", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      ]
    }
  }
}

Configuração do Claude Desktop

Localização:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Use as mesmas opções de configuração do Cursor acima.

Exemplos de Configuração

O projeto inclui vários exemplos de configuração no diretório examples/:

  • examples/github-api.json - Configuração da API do GitHub
  • examples/petstore.json - Configuração da API Swagger Petstore
  • examples/jsonplaceholder.json - Configuração da API JSONPlaceholder

Variáveis de Ambiente

VariávelDescrição
MCP_REST_BASE_URLURL base para a API REST (obrigatório)
MCP_REST_AUTH_TYPETipo de autenticação: 'token' ou 'login' (obrigatório)
MCP_REST_TOKENToken da API (obrigatório para autenticação por token)
MCP_REST_USERNAMENome de usuário (obrigatório para autenticação por login)
MCP_REST_PASSWORDSenha (obrigatório para autenticação por login)
MCP_REST_LOGIN_ENDPOINTCaminho do endpoint de login (obrigatório para autenticação por login)
MCP_REST_TOKEN_FIELDNome do campo do token na resposta de login (padrão: access_token)
MCP_REST_SWAGGER_URLURL para documentação Swagger/OpenAPI
MCP_REST_TIMEOUTTempo limite de requisição em milissegundos (padrão: 30000)
MCP_REST_RETRIESNúmero de tentativas para requisições com falha (padrão: 3)
MCP_REST_CONFIG_FILECaminho para o arquivo de configuração JSON

Nota: Substitua /path/to/your/mcp-rest/ pelo caminho real do diretório do seu servidor MCP REST.

Uso no Claude/Cursor

Com Auto-configuração (Recomendado)

Se você configurou o servidor com auto-configuração (variáveis de ambiente, argumentos de CLI ou arquivo de configuração), o servidor estará pronto para uso imediato:

Make a GET request to /posts/1
Show me all available endpoints
Search for endpoints related to "user"

Com Configuração Manual

Se você não forneceu auto-configuração, ainda pode configurar o cliente manualmente:

  1. Configure o cliente primeiro:
Please configure the REST client with:
- Base URL: https://api.example.com
- Authentication: token
- Token: your-api-token-here
- Swagger URL: https://api.example.com/swagger.json
  1. Depois faça requisições à API:
Make a GET request to /users/123

Testando a Configuração

Você pode testar sua configuração antes de usá-la no Claude/Cursor:

# Test with config file
node dist/index.js --config examples/jsonplaceholder.json

# Test with CLI arguments
node dist/index.js --base-url https://api.github.com --auth-type token --token your-token

# Test with environment variables
MCP_REST_BASE_URL=https://httpbin.org MCP_REST_AUTH_TYPE=token MCP_REST_TOKEN=test node dist/index.js

Se você vir "✅ Auto-configured REST client for [URL]", a configuração está funcionando corretamente.

Licença

MIT