MCP OpenAPI Connector

Conecte-se a qualquer API baseada em OpenAPI com gerenciamento de autenticação OAuth2 integrado.

Documentação

MCP OpenAPI Connector

Um servidor unificado de Model Context Protocol (MCP) para conectar APIs baseadas em OpenAPI com gerenciamento de autenticação integrado. Este projeto permite que Claude Desktop, Cursor e outros clientes compatíveis com MCP interajam com APIs baseadas em OpenAPI autenticadas, sem a necessidade de servidores proxy separados.

Recursos

Arquitetura de Processo Único: Sem necessidade de servidor proxy separado
Autenticação OAuth2 Integrada: Gerenciamento automático de tokens e renovação
Integração OpenAPI: Geração automática de ferramentas MCP a partir de especificações OpenAPI/Swagger
Sistema de Ferramentas Extensível: Fácil adição de ferramentas e recursos personalizados
Tratamento de Erros: Repetição automática e recuperação de erros de autenticação
Configuração Simples: Arquivo de configuração único para todas as configurações
Suporte a Múltiplas APIs: Adaptação fácil a qualquer API baseada em OAuth2

Instalação

Via npm (Recomendado)

npm install -g @ssossan/mcp-openapi-connector

Ou use diretamente com npx:

npx @ssossan/mcp-openapi-connector

A partir do Código Fonte

git clone https://github.com/ssossan/mcp-openapi-connector.git
cd mcp-openapi-connector
npm install

Configuração Rápida (Recomendado)

Execute o assistente de configuração interativo:

npm run setup

Isso irá:

Coletar a configuração da sua API por meio de prompts interativos
Gerar o arquivo generated/.env com suas configurações
Criar generated/claude-desktop-config.json para integração fácil com Claude Desktop
Fornecer instruções passo a passo para a configuração do Claude Desktop

Configuração Manual

Alternativamente, você pode configurar manualmente:

Copie .env.example para .env:

cp .env.example .env

Edite .env com suas credenciais de API:

CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
API_BASE_URL=https://api.example.com
AUTH_PATH=/oauth/token
OPENAPI_SPEC_PATH=./config/openapi.json

Uso

Modo de Desenvolvimento

Para desenvolvimento com recompilação automática:

npm run dev

Modo de Produção

Compile e execute a versão compilada:

npm run build
npm start

Configuração do Claude Desktop

Adicione ao arquivo de configuração do seu Claude Desktop:

Usando o pacote npm (Recomendado):

{
  "mcpServers": {
    "openapi-connector": {
      "command": "npx",
      "args": ["@ssossan/mcp-openapi-connector"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Usando instalação global:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Usando a partir do código fonte:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "node",
      "args": ["/path/to/mcp-openapi-connector/dist/mcp-openapi-connector.js"],
      "cwd": "/path/to/mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Integração OpenAPI

O servidor gera automaticamente ferramentas a partir de uma especificação OpenAPI. Uma especificação OpenAPI é necessária para o funcionamento do servidor.

Coloque seu arquivo de especificação OpenAPI (formato JSON) no projeto
Defina o caminho no seu ambiente:

OPENAPI_SPEC_PATH=./config/openapi.json
OPENAPI_TOOL_PREFIX=api_  # Optional: prefix for generated tool names
OPENAPI_INCLUDE_ONLY=listItems,createItem  # Optional: only include specific operations
OPENAPI_EXCLUDE=deleteItem  # Optional: exclude specific operations

O servidor gerará automaticamente ferramentas MCP a partir de todas as operações na sua especificação OpenAPI. Sem uma especificação OpenAPI, o servidor fornecerá apenas ferramentas de teste/depuração.

Ferramentas Personalizadas

Crie ferramentas personalizadas adicionando um arquivo JavaScript:

export default {
  register(server) {
    server.registerCustomTool('my_tool', {
      name: 'my_tool',
      description: 'My custom tool',
      inputSchema: {
        type: 'object',
        properties: {
          param: { type: 'string', required: true }
        }
      },
      apiEndpoint: '/my-endpoint',
      method: 'POST'
    });
  }
};

Em seguida, defina CUSTOM_TOOLS_PATH no seu ambiente:

CUSTOM_TOOLS_PATH=./src/tools/my-custom-tools.ts

Publicação no npm

Para mantenedores:

npm run build
npm test
npm publish --access public

Desenvolvimento

Scripts Disponíveis

npm run dev          # Development mode with tsx
npm run build        # Compile TypeScript to JavaScript
npm start            # Build and run production version
npm run test         # Build and run test server
npm run test:dev     # Run test server in development mode
npm run typecheck    # Type check without compilation
npm run clean        # Remove build output

Desenvolvimento em TypeScript

Este projeto é construído com TypeScript para melhor segurança de tipos e experiência de desenvolvimento:

Código fonte: diretório src/
Saída de compilação: diretório dist/
Definições de tipos: arquivos .d.ts gerados automaticamente

Arquitetura

Claude Desktop ↔ MCP Server (stdio) → OpenAPI-based API
                    ↓
             TokenManager
           (OAuth2 handling)

Componentes Principais

src/mcp-openapi-connector.ts - Ponto de entrada principal do servidor
src/lib/token-manager.ts - Gerenciamento de tokens OAuth2 com cache
src/lib/saas-client.ts - Cliente HTTP com autenticação automática
src/lib/mcp-handler.ts - Tratamento do protocolo MCP e registro de ferramentas
src/lib/openapi-loader.ts - Analisador de especificações OpenAPI e gerador de ferramentas
src/types/ - Definições de tipos TypeScript

Migração da v1.x

Se você está usando a versão anterior baseada em gateway:

Remova a configuração do servidor proxy
Atualize a configuração do Claude Desktop para apontar diretamente para este servidor
Use as mesmas variáveis de ambiente (sem alterações necessárias)

Exemplo: Uso com uma API Genérica Baseada em OpenAPI

Consulte o arquivo config/openapi-example.json para uma especificação OpenAPI de exemplo que demonstra como estruturar sua API para integração com MCP.

Solução de Problemas

Erros de Autenticação

Verifique se CLIENT_ID e CLIENT_SECRET estão corretos
Confirme se AUTH_URL aponta para o endpoint OAuth2 correto
Garanta que suas credenciais tenham os escopos necessários

Problemas de Conexão

Verifique se API_BASE_URL está correto
Confirme a conectividade de rede
Verifique os logs do servidor para mensagens de erro detalhadas

Modo de Depuração

Defina NODE_ENV=development para registro detalhado:

NODE_ENV=development npm run dev

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

MIT

Agradecimentos

Construído usando o Model Context Protocol SDK da Anthropic.