SpecBridge

SpecBridge

Um servidor MCP que transforma especificações OpenAPI em ferramentas MCP. Escaneie uma pasta em busca de arquivos de especificação OpenAPI e gere automaticamente as ferramentas correspondentes. Sem arquivos de configuração, sem servidores separados — basta colocar as especificações em uma pasta e obter as ferramentas.

Construído com FastMCP para TypeScript.

✨ Recursos

• 🎯 Zero Configuração: O sistema de arquivos é a interface — basta colocar as especificações OpenAPI em uma pasta
• 🔐 Autenticação Automática: Arquivo .env simples com padrão {API_NAME}_API_KEY
• 🏷️ Isolamento por Namespace: Múltiplas APIs coexistem de forma limpa (ex.: petstore_getPet, github_getUser)
• 📝 Suporte Completo a OpenAPI: Lida com parâmetros, corpos de requisição, autenticação e respostas
• 🚀 Múltiplos Transportes: Suporte para stdio e streaming HTTP
• 🔍 Depuração Integrada: Comando list para ver especificações e ferramentas carregadas

🚀 Início Rápido

1️⃣ Instalação (opcional)

npm install -g specbridge

2️⃣ Crie uma pasta de especificações

mkdir ~/mcp-apis

3️⃣ Adicione especificações OpenAPI

Coloque quaisquer arquivos de especificação OpenAPI .json, .yaml ou .yml na sua pasta de especificações:

# Example: Download the Petstore spec
curl -o ~/mcp-apis/petstore.json https://petstore3.swagger.io/api/v3/openapi.json

4️⃣ Configure a autenticação (opcional)

Crie um arquivo .env na sua pasta de especificações:

# ~/mcp-apis/.env
PETSTORE_API_KEY=your_api_key_here
GITHUB_TOKEN=ghp_your_github_token
OPENAI_API_KEY=sk-your_openai_key

5️⃣ Adicione à configuração do cliente MCP

Para Claude Desktop ou Cursor, adicione à sua configuração MCP:

Se instalado na sua máquina:

{
  "mcpServers": {
    "specbridge": {
      "command": "specbridge",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}

Caso contrário:

{
  "mcpServers": {
    "specbridge": {
      "command": "npx",
      "args": ["-y", "specbridge", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}

💻 Uso via CLI

🚀 Inicie o servidor

# Default: stdio transport, current directory
specbridge

# Custom specs folder
specbridge --specs ~/my-api-specs

# HTTP transport mode
specbridge --transport httpStream --port 8080

📋 Liste especificações e ferramentas carregadas

# List all loaded specifications and their tools
specbridge list

# List specs from custom folder
specbridge list --specs ~/my-api-specs

🔑 Padrões de Autenticação

O servidor detecta automaticamente a autenticação a partir de variáveis de ambiente usando estes padrões:

Padrão	Tipo de Autenticação	Uso
{API_NAME}_API_KEY	🗝️ Chave de API	Cabeçalho X-API-Key
{API_NAME}_TOKEN	🎫 Token Bearer	Authorization: Bearer {token}
{API_NAME}_BEARER_TOKEN	🎫 Token Bearer	Authorization: Bearer {token}
{API_NAME}_USERNAME + {API_NAME}_PASSWORD	👤 Autenticação Básica	Authorization: Basic {base64}

O {API_NAME} é derivado do nome do arquivo da sua especificação OpenAPI:

• petstore.json → PETSTORE_API_KEY
• github-api.yaml → GITHUB_TOKEN
• my_custom_api.yml → MYCUSTOMAPI_API_KEY

🏷️ Nomenclatura de Ferramentas

As ferramentas são nomeadas automaticamente usando este padrão:

• Com operationId: {api_name}_{operationId}
• Sem operationId: {api_name}_{method}_{path_segments}

Exemplos:

• petstore_getPetById (a partir do operationId)
• github_get_user_repos (gerado a partir de GET /user/repos)

📁 Estrutura de Arquivos

your-project/
├── api-specs/           # Your OpenAPI specs folder
│   ├── .env            # Authentication credentials
│   ├── petstore.json   # OpenAPI spec files
│   ├── github.yaml     # 
│   └── custom-api.yml  # 
└── mcp-config.json     # MCP client configuration

📄 Exemplo de Especificação OpenAPI

Aqui está um exemplo mínimo que cria duas ferramentas:

# ~/mcp-apis/example.yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: User created

Isso cria ferramentas nomeadas:

• example_getUser
• example_createUser

🔧 Solução de Problemas

❌ Nenhuma ferramenta aparecendo?

1. Verifique se suas especificações OpenAPI são válidas:

   specbridge list --specs /path/to/specs
   

2. Garanta que os arquivos tenham as extensões corretas (.json, .yaml, .yml)

3. Verifique os logs do servidor para erros de análise

⚠️ Nota: Specbridge funciona melhor quando você usa caminhos absolutos (sem espaços) para o argumento --specs e outros caminhos de arquivo. Caminhos relativos ou caminhos com espaços podem causar problemas em algumas plataformas ou com alguns clientes MCP.

🔐 Autenticação não funcionando?

1. Verifique se o arquivo .env está no diretório de especificações
2. Verifique se o padrão de nomenclatura corresponde ao nome do arquivo da sua especificação
3. Use o comando list para verificar a configuração de autenticação:

   specbridge list
   

🔄 Ferramentas não atualizando após alterações na especificação?

1. Reinicie o servidor MCP para recarregar as especificações
2. Verifique as permissões dos arquivos
3. Reinicie o cliente MCP se necessário

🛠️ Desenvolvimento

# Clone and install
git clone https://github.com/TBosak/specbridge.git
cd specbridge
npm install

# Build
npm run build

# Test locally
npm run dev -- --specs ./examples

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar issues e pull requests.