MCPizer

Permite que assistentes de IA chamem qualquer API REST ou serviço gRPC convertendo automaticamente seus esquemas em ferramentas MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

MCPizer

O MCPizer permite que seu assistente de IA (Claude, VS Code, etc.) chame qualquer API REST ou serviço gRPC convertendo automaticamente seus esquemas em ferramentas MCP (Model Context Protocol).

Principais recursos:

🚀 Integração com GitHub - busque esquemas diretamente com URLs github://
📄 Suporte a arquivos .proto - use gRPC sem reflection habilitado
🔐 Suporte a repositórios privados - autenticação automática via CLI gh
🌐 Suporte a Connect-RPC - modos HTTP/JSON e gRPC
🔧 Descoberta automática - encontra endpoints OpenAPI/Swagger automaticamente

O que é o MCPizer?

O MCPizer é um servidor que:

Descobre automaticamente esquemas de API dos seus serviços (OpenAPI/Swagger, gRPC reflection, arquivos .proto)
Converte em ferramentas que sua IA pode usar
Gerencia todas as chamadas de API com tipos adequados e tratamento de erros

Funciona com qualquer framework que exponha esquemas OpenAPI (FastAPI, Spring Boot, Express, etc.) ou serviços gRPC (com reflection ou arquivos .proto). Não são necessárias alterações de código nas suas APIs - basta apontar o MCPizer para elas!

Como Funciona

sequenceDiagram
    participant AI as AI Assistant<br/>(Claude/VS Code)
    participant MCP as MCPizer
    participant API as Your APIs<br/>(REST/gRPC)
    
    Note over AI,API: Initial Setup
    MCP->>API: Auto-discover schemas
    API-->>MCP: OpenAPI/gRPC reflection
    MCP->>MCP: Convert to MCP tools
    
    Note over AI,API: Runtime Usage
    AI->>MCP: List available tools
    MCP-->>AI: Tools from all APIs
    AI->>MCP: Call tool "create_user"
    MCP->>API: POST /users
    API-->>MCP: {"id": 123, "name": "Alice"}
    MCP-->>AI: Tool result

Visão Geral da Arquitetura

graph TB
    subgraph "AI Assistants"
        Claude[Claude Desktop]
        VSCode[VS Code Extensions]
        Other[Other MCP Clients]
    end
    
    subgraph "MCPizer"
        Transport{Transport Layer}
        Discovery[Schema Discovery]
        Converter[Tool Converter]
        Invoker[API Invoker]
        
        Transport -->|STDIO/SSE| Discovery
        Discovery --> Converter
        Converter --> Invoker
    end
    
    subgraph "Your APIs"
        FastAPI[FastAPI<br/>Auto-discovery]
        Spring[Spring Boot<br/>Auto-discovery]
        gRPC[gRPC Services<br/>Reflection/.proto]
        Custom[Custom APIs<br/>Direct schema URL]
    end
    
    Claude --> Transport
    VSCode --> Transport
    Other --> Transport
    
    Invoker --> FastAPI
    Invoker --> Spring
    Invoker --> gRPC
    Invoker --> Custom
    
    style MCPizer fill:#e1f5e1
    style Transport fill:#fff2cc
    style Discovery fill:#fff2cc
    style Converter fill:#fff2cc
    style Invoker fill:#fff2cc

Instalação

# Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest

# Verify installation
mcpizer --help

Exemplos de Uso

# Use default config file (configs/mcpizer.yaml)
mcpizer

# Specify config file via command line (highest priority)
mcpizer -config=/path/to/config.yaml

# Use GitHub-hosted config
mcpizer -config=github://myorg/configs/mcpizer-prod.yaml

# Or via environment variable
export MCPIZER_CONFIG_FILE=/path/to/config.yaml
mcpizer

# STDIO mode with custom config
mcpizer -transport=stdio -config=./my-config.yaml

Nota: Certifique-se de que $GOPATH/bin esteja no seu PATH. Se não estiver instalado, instale o Go primeiro.

Início Rápido

Passo 1: Configure Suas APIs

Crie um arquivo de configuração com seus endpoints de API:

schema_sources:
  # Production APIs with HTTPS
  - https://api.mycompany.com              # Auto-discovers OpenAPI
  - https://api.example.com/openapi.json   # Direct schema URL
  
  # GitHub-hosted schemas (NEW: use github:// URLs)
  - github://myorg/api-specs/main/user-api.yaml     # Uses gh CLI auth
  - github://OAI/OpenAPI-Specification/examples/v3.0/petstore.yaml@master
  - https://raw.githubusercontent.com/myorg/api-specs/main/user-api.yaml  # Direct URL also works
  
  # Internal services (FastAPI, Spring Boot, etc.)
  - http://my-fastapi-app:8000     # Auto-discovers at /openapi.json, /docs
  - http://spring-service:8080     # Auto-discovers at /v3/api-docs
  
  # gRPC services (must have reflection enabled)
  - grpc://my-grpc-service:50051
  
  # gRPC with .proto files (NEW! - no reflection needed)
  - url: https://raw.githubusercontent.com/myorg/protos/main/service.proto
    server: grpc://production.example.com:50051
  
  # Or use github:// for private repos (uses gh CLI)
  - url: github://myorg/protos/service.proto@main
    server: grpc://production.example.com:50051
  
  # Connect-RPC services (NEW!)
  # If the service supports gRPC reflection:
  - grpc://connect.example.com:50051
  
  # Connect-RPC with HTTP/JSON mode:
  - url: github://connectrpc/examples/eliza/eliza.proto
    server: https://demo.connectrpc.com
    type: connect
    mode: http  # Use HTTP/JSON for easier debugging
  
  # Local development
  - http://localhost:3000
  - grpc://localhost:50052
  
  # Public test APIs
  - https://petstore3.swagger.io/api/v3/openapi.json
  - grpc://grpcb.in:9000

Passo 2: Escolha Seu Modo de Transporte

O MCPizer suporta dois modos de transporte:

📝 Modo STDIO (para clientes que gerenciam o ciclo de vida do processo)

Usado por clientes que iniciam o MCPizer como subprocesso e se comunicam via entrada/saída padrão.

Exemplo: Claude Desktop

Adicione ao seu arquivo de configuração:

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

{
  "mcpServers": {
    "mcpizer": {
      "command": "mcpizer",
      "args": ["-transport=stdio", "-config=/path/to/your/config.yaml"]
    }
  }
}

O cliente iniciará o MCPizer automaticamente quando necessário.

🌐 Modo SSE (Server-Sent Events via HTTP)

Usado por clientes que se conectam a um servidor MCPizer em execução via HTTP.

# Start MCPizer server (if your client doesn't start it automatically)
mcpizer

# Server runs at http://localhost:8080/sse

Configure seu cliente MCP para conectar a http://localhost:8080/sse

Nota: Alguns clientes podem iniciar o servidor automaticamente, enquanto outros exigem inicialização manual.

🧪 Para Testes/Desenvolvimento

# Quick test - list available tools
mcpizer -transport=stdio << 'EOF'
{"jsonrpc":"2.0","method":"tools/list","id":1}
EOF

# Interactive mode
mcpizer -transport=stdio

Guia de Uso

Quando Usar o Quê

Eu quero...	Faça isso...
Usar minha API com Claude Desktop	Adicione configuração a `claude_desktop_config.json` (veja Início Rápido)
Testar se minha API funciona com MCP	Execute `mcpizer -transport=stdio` e verifique a lista de ferramentas
Executar como serviço em segundo plano	Use o modo SSE com `mcpizer` (sem argumentos)
Depurar problemas de conexão	Defina `MCPIZER_LOG_LEVEL=debug`
Usar um repositório GitHub privado	Use URLs `github://` (requer CLI `gh`)
Usar gRPC sem reflection	Use arquivos .proto com o campo `server`
Múltiplos ambientes, mesma API	Use o mesmo arquivo de esquema, valores diferentes de `server`

Configuração

O MCPizer procura configuração nesta ordem:

Flag de linha de comando -config (maior prioridade)
Variável de ambiente $MCPIZER_CONFIG_FILE
configs/mcpizer.yaml (padrão)

Tipos de API Suportados

APIs REST (OpenAPI/Swagger)

schema_sources:
  # Auto-discovery from base URL
  - https://api.production.com      # Tries /openapi.json, /swagger.json, etc.
  - http://internal-api:8000        # For internal services
  
  # Direct schema URLs
  - https://api.example.com/v3/openapi.yaml
  - https://raw.githubusercontent.com/company/api-specs/main/openapi.json

Serviços Connect-RPC (NOVO!)

schema_sources:
  # Connect-RPC with gRPC reflection (if supported)
  - grpc://connect.example.com:50051
  
  # Connect-RPC with HTTP/JSON mode
  - url: github://connectrpc/examples/eliza/eliza.proto
    server: https://demo.connectrpc.com
    type: connect
    mode: http    # HTTP/JSON mode (default)
  
  # Connect-RPC with gRPC mode
  - url: https://raw.githubusercontent.com/myorg/protos/service.proto
    server: grpc://connect.example.com:50051
    type: connect
    mode: grpc    # Use gRPC transport

Recursos do Connect-RPC:

Modo HTTP/JSON: Legível por humanos, funciona com curl e ferramentas de navegador
Modo gRPC: Protocolo binário, mais eficiente
Suporte duplo: O mesmo serviço pode ser acessado por ambos os modos
Sem proxy necessário: Comunicação HTTP/JSON direta

Arquivos de Esquema Separados e Servidores de API

O MCPizer suporta arquivos de esquema OpenAPI hospedados separadamente do servidor de API real. Isso é útil quando:

A API não expõe seu próprio esquema - Você pode escrever uma especificação OpenAPI para qualquer API
O esquema é gerenciado separadamente - A equipe de documentação mantém esquemas de forma independente
Múltiplos ambientes - Um arquivo de esquema para APIs de dev/staging/produção

Como funciona:

schema_sources:
  # Schema file points to production API
  - https://docs.company.com/api/v1/openapi.yaml
  
  # Local schema file for external API
  - ./schemas/third-party-api.yaml

A especificação OpenAPI contém URLs de servidor:

servers:
  - url: https://api.production.com
    description: Production server
  - url: https://api.staging.com
    description: Staging server

O MCPizer irá:

Buscar o esquema da URL de schema_sources
Ler a seção servers da especificação OpenAPI
Usar a primeira URL de servidor disponível para chamadas reais de API

Exemplo: Criando especificação OpenAPI para uma API sem documentação

Se você tem uma API em https://internal-api.company.com que não fornece OpenAPI:

Escreva sua própria especificação OpenAPI:

openapi: 3.0.0
info:
  title: Internal API
  version: 1.0.0
servers:
  - url: https://internal-api.company.com
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: {type: integer}
                    name: {type: string}

Hospede-a em qualquer lugar:
- GitHub: https://raw.githubusercontent.com/yourorg/specs/main/api.yaml
- S3/CDN: https://cdn.company.com/api-specs/v1/openapi.json
- Arquivo local: ./schemas/third-party-api.yaml
Aponte o MCPizer para seu arquivo de esquema

Processo de Descoberta Automática

graph TD
    Start["Base URL provided:<br/>http://your-api:8000"] 
    
    Try1["/openapi.json<br/>FastAPI default"]
    Try2["/docs/openapi.json<br/>FastAPI alt"]
    Try3["/swagger.json<br/>Swagger 2.0"]
    Try4["/v3/api-docs<br/>Spring Boot"]
    Try5["...more paths..."]
    
    Found["✓ Schema found!<br/>Parse and convert"]
    NotFound["✗ Not found<br/>Try direct URL"]
    
    Start --> Try1
    Try1 -->|404| Try2
    Try2 -->|404| Try3
    Try3 -->|404| Try4
    Try4 -->|404| Try5
    
    Try1 -->|200| Found
    Try2 -->|200| Found
    Try3 -->|200| Found
    Try4 -->|200| Found
    
    Try5 -->|All fail| NotFound
    
    style Start fill:#e3f2fd
    style Found fill:#c8e6c9
    style NotFound fill:#ffcdd2

Frameworks suportados:

FastAPI: /openapi.json, /docs/openapi.json
Spring Boot: /v3/api-docs, /swagger-ui/swagger.json
Express/NestJS: /api-docs, /swagger.json
Rails: /api/v1/swagger.json, /apidocs
Veja a lista completa

Serviços gRPC

schema_sources:
  # Using gRPC reflection (requires reflection enabled on server)
  - grpc://your-grpc-host:50051     # Your service
  - grpc://grpcb.in:9000            # Public test service
  
  # Using .proto files (NEW! - no reflection needed)
  - url: https://raw.githubusercontent.com/grpc/grpc-go/master/examples/helloworld/helloworld/helloworld.proto
    server: grpc://production.example.com:50051
  
  # Private GitHub .proto files (uses gh CLI authentication)
  - url: github://myorg/protos/user-service.proto
    server: grpc://user-service:50051
  
  # With specific branch/tag
  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@v1.65.0
    server: grpc://production.example.com:50051

Opção 1: gRPC Reflection (requer reflection habilitado):

// In your gRPC server
import "google.golang.org/grpc/reflection"
reflection.Register(grpcServer)

Opção 2: Arquivos .proto (NOVO! - mais seguro, sem necessidade de reflection):

Hospede seus arquivos .proto em qualquer lugar (GitHub, S3, CDN, etc.)
URLs do GitHub (github://) usam automaticamente autenticação da CLI gh
Especifique o endpoint server separadamente
Perfeito para produção onde reflection está desabilitado
Permite versionamento de esquema e validação CI/CD

Para implementações alternativas de reflection, veja:

connectrpc/grpcreflect-go - Implementação de reflection do Connect-Go

Arquivos Locais

schema_sources:
  - ./api-spec.json
  - /path/to/openapi.yaml

Integração com GitHub (NOVO!)

O MCPizer pode buscar esquemas diretamente de repositórios GitHub usando a ferramenta CLI gh - incluindo arquivos OpenAPI e .proto:

schema_sources:
  # OpenAPI schemas from GitHub
  - github://owner/repo/path/to/openapi.yaml
  - github://microsoft/api-guidelines/graph/openapi.yaml@v1.0
  
  # .proto files from GitHub (NEW!)
  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@master
    server: grpc://production.example.com:50051
  
  # Private repositories (uses gh CLI authentication)
  - github://myorg/private-apis/user-api.yaml
  - url: github://myorg/private-protos/service.proto@v2.0
    server: grpc://internal-service:50051
  
  # Load MCPizer config itself from GitHub!
  # Set MCPIZER_CONFIG_FILE=github://myorg/configs/mcpizer.yaml

Benefícios:

✅ Funciona com repositórios privados (usa autenticação gh)
✅ Especifique branches/tags com sintaxe @ref
✅ Sem necessidade de gerenciar URLs raw do GitHub ou tokens
✅ Suporta arquivos OpenAPI e .proto
✅ Arquivos de configuração também podem ser armazenados no GitHub

Requisitos:

Instale a CLI do GitHub: brew install gh (macOS) ou veja a documentação
Autentique: gh auth login

Variáveis de Ambiente

Variável	Padrão	Quando usar
`MCPIZER_CONFIG_FILE`	`~/.mcpizer.yaml`	Configuração diferente por ambiente Pode ser URL `github://`!
`MCPIZER_LOG_LEVEL`	`info`	Defina como `debug` para solução de problemas
`MCPIZER_LOG_FILE`	`/tmp/mcpizer.log`	Alterar local do log (modo STDIO)
`MCPIZER_LISTEN_ADDR`	`:8080`	Alterar porta (modo SSE)
`MCPIZER_HTTP_CLIENT_TIMEOUT`	`30s`	APIs lentas precisam de mais tempo

Cenários Comuns

"Quero que o Claude use meu aplicativo FastAPI local"

# 1. Your FastAPI runs on port 8000
python -m uvicorn main:app

# 2. Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest

# 3. Configure (~/.mcpizer.yaml)
echo "schema_sources:\n  - http://localhost:8000" > ~/.mcpizer.yaml

# 4. Add to Claude Desktop config and restart
# Now ask Claude: "What endpoints are available?"

"Quero testar se o MCPizer vê minha API"

# Quick check - what tools are available?
mcpizer -transport=stdio << 'EOF'
{"jsonrpc":"2.0","method":"tools/list","id":1}
EOF

# Should list all your API endpoints as tools

"Minha API precisa de autenticação"

# For APIs that require authentication headers
schema_sources:
  # Object format with headers (for fetching schemas)
  - url: https://api.example.com/openapi.json
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"
      X-API-Key: "YOUR_API_KEY"
  
  # GitHub private repos (automatic auth via gh CLI)
  - github://myorg/private-apis/openapi.yaml     # No headers needed!
  - url: github://myorg/private-protos/api.proto  # gh handles auth
    server: grpc://api.example.com:50051
  
  # Simple format (no auth required)
  - https://public-api.example.com/swagger.json

Nota: Esses cabeçalhos são usados ao buscar os arquivos de esquema. Cabeçalhos necessários para chamadas reais de API devem ser definidos na própria especificação OpenAPI.

"Estou recebendo 'no tools available'"

# 1. Check if your API is running
curl http://localhost:8000/openapi.json  # Should return JSON

# 2. Run with debug logging
MCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio

# 3. Check the log file
tail -f /tmp/mcpizer.log

"Quero usar os serviços gRPC da minha empresa"

Opção 1: Se reflection estiver habilitado

# Simple - just point to the service
schema_sources:
  - grpc://my-service:50051

Opção 2: Usando arquivos .proto (recomendado)

# More secure - no reflection needed in production
schema_sources:
  # From GitHub (private repos supported)
  - url: github://mycompany/protos/user-service.proto@v1.0.0
    server: grpc://user-service.prod:443
  
  # From any HTTPS URL
  - url: https://cdn.mycompany.com/schemas/order-service.proto
    server: grpc://order-service.prod:443

"Quero executar o MCPizer como um serviço"

Opção 1: Execução direta do binário

# Run in background with specific config
mcpizer -config /etc/mcpizer/production.yaml &

# Or use systemd (create /etc/systemd/system/mcpizer.service)
[Unit]
Description=MCPizer MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mcpizer
Environment="MCPIZER_CONFIG_FILE=/etc/mcpizer/production.yaml"
Restart=always
User=mcpizer

[Install]
WantedBy=multi-user.target

Solução de Problemas

Comandos de Depuração

# See what's happening
MCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio

# Watch logs (STDIO mode)
tail -f /tmp/mcpizer.log

# Test your API is accessible
curl http://your-api-host:8000/openapi.json

# Test gRPC reflection
grpcurl -plaintext your-grpc-host:50051 list

Problemas Comuns

Problema	Solução
"No tools available"	• Verifique se a API está em execução • Tente URL de esquema direta • Verifique logs de depuração
"Connection refused"	• Porta errada? • Verifique se a API está em execução • Firewall bloqueando?
"String should have at most 64 characters"	Atualize o MCPizer - isso foi corrigido na versão mais recente
gRPC "connection refused"	• Habilite reflection no seu servidor gRPC • Verifique com `grpcurl` • Ou use a abordagem de arquivo .proto
"Schema not found at base URL"	• Especifique o caminho exato do esquema • Verifique se a API expõe OpenAPI
".proto file missing server"	• Adicione `server: grpc://host:port` à sua configuração • Necessário para arquivos .proto

Exemplos

Exemplo de Fluxo Completo

Veja como o MCPizer funciona com um serviço FastAPI:

flowchart LR
    subgraph "Your FastAPI App"
        API[FastAPI Service<br/>Port 8000]
        Schema["/openapi.json<br/>Auto-generated"]
        API --> Schema
    end
    
    subgraph "MCPizer Config"
        Config["~/.mcpizer.yaml<br/>schema_sources:<br/>http://my-fastapi:8000"]
    end
    
    subgraph "MCPizer Process"
        Discover["(1) Discover schema<br/>at /openapi.json"]
        Convert["(2) Convert endpoints<br/>to MCP tools"]
        Register["(3) Register tools<br/>with MCP protocol"]
        
        Discover --> Convert
        Convert --> Register
    end
    
    subgraph "AI Assistant"
        List["List tools:<br/>• get_item<br/>• create_item<br/>• update_item"]
        Call["Call: get_item<br/>{item_id: 123}"]
        Result["Result:<br/>{id: 123, name: 'Test'}"]
        
        List --> Call
        Call --> Result
    end
    
    Config --> Discover
    Schema --> Discover
    Register --> List
    Call -->|HTTP GET /items/123| API
    API -->|JSON Response| Result
    
    style API fill:#e8f4fd
    style Config fill:#fff4e6
    style Register fill:#e8f5e9
    style Result fill:#f3e5f5

Exemplo FastAPI

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

# MCPizer auto-discovers at http://localhost:8000/openapi.json

Exemplo gRPC

Opção 1: Usando Reflection

// Enable reflection for MCPizer
import "google.golang.org/grpc/reflection"

func main() {
    s := grpc.NewServer()
    pb.RegisterYourServiceServer(s, &server{})
    reflection.Register(s)  // This line enables MCPizer support
    s.Serve(lis)
}

Opção 2: Usando Arquivos .proto (Recomendado para Produção)

# config.yaml
schema_sources:
  # Your .proto file in version control
  - url: github://myorg/protos/user-service.proto@v1.0.0
    server: grpc://user-service.prod.example.com:443
  
  # Multiple environments, same schema
  - url: github://myorg/protos/user-service.proto@v1.0.0
    server: grpc://user-service.staging.example.com:443

Benefícios:

✅ Sem necessidade de reflection em produção
✅ Esquemas com controle de versão
✅ CI/CD pode validar esquemas
✅ Mesmo .proto para múltiplos ambientes

Desenvolvimento

# Run tests
go test ./...

# Run integration tests (requires internet connection)
go test -tags=integration ./...

# Build locally
go build -o mcpizer ./cmd/mcpizer

# Run with example services (includes Petstore, gRPC test service, Jaeger)
docker compose up

# Run individual examples
cd examples/fastapi && pip install -r requirements.txt && python main.py

Veja examples/ para exemplos mais completos:

proto-config.yaml - Usando arquivos .proto com múltiplos ambientes
fastapi/ - Exemplo de integração FastAPI
grpc-service/ - Serviço gRPC com reflection

Contribuindo

Contribuições são bem-vindas! Por favor:

Verifique os problemas existentes primeiro
Faça um fork e crie uma branch de funcionalidade
Adicione testes para novas funcionalidades
Envie um PR

Licença

MIT - veja LICENSE