MCPizer

Permite que los asistentes de IA llamen a cualquier API REST o servicio gRPC convirtiendo automáticamente sus esquemas en herramientas MCP.

GitHub

Prueba este MCPPatrocinado

Documentación

MCPizer

MCPizer permite que tu asistente de IA (Claude, VS Code, etc.) llame a cualquier API REST o servicio gRPC convirtiendo automáticamente sus esquemas en herramientas MCP (Model Context Protocol).

Características principales:

🚀 Integración con GitHub - obtén esquemas directamente con URLs github://
📄 Soporte de archivos .proto - usa gRPC sin reflexión habilitada
🔐 Soporte de repositorios privados - autenticación automática mediante CLI gh
🌐 Soporte Connect-RPC - modos HTTP/JSON y gRPC
🔧 Auto-descubrimiento - encuentra endpoints OpenAPI/Swagger automáticamente

¿Qué es MCPizer?

MCPizer es un servidor que:

Auto-descubre esquemas de API de tus servicios (OpenAPI/Swagger, reflexión gRPC, archivos .proto)
Los convierte en herramientas que tu IA puede usar
Gestiona todas las llamadas a la API con tipos adecuados y manejo de errores

Funciona con cualquier framework que exponga esquemas OpenAPI (FastAPI, Spring Boot, Express, etc.) o servicios gRPC (con reflexión o archivos .proto). No se necesitan cambios de código en tus APIs: ¡solo apunta MCPizer hacia ellas!

Cómo 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

Descripción general de la arquitectura

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

Instalación

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

# Verify installation
mcpizer --help

Ejemplos 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: Asegúrate de que $GOPATH/bin esté en tu PATH. Si no está instalado, instala Go primero.

Inicio rápido

Paso 1: Configura tus APIs

Crea un archivo de configuración con tus 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

Paso 2: Elige tu modo de transporte

MCPizer admite dos modos de transporte:

📝 Modo STDIO (para clientes que gestionan el ciclo de vida del proceso)

Usado por clientes que inician MCPizer como subproceso y se comunican mediante entrada/salida estándar.

Ejemplo: Claude Desktop

Añade a tu archivo de configuración:

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"]
    }
  }
}

El cliente iniciará MCPizer automáticamente cuando sea necesario.

🌐 Modo SSE (Server-Sent Events sobre HTTP)

Usado por clientes que se conectan a un servidor MCPizer en ejecución mediante HTTP.

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

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

Configura tu cliente MCP para conectarse a http://localhost:8080/sse

Nota: Algunos clientes pueden iniciar el servidor automáticamente, mientras que otros requieren inicio manual.

🧪 Para pruebas/desarrollo

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

# Interactive mode
mcpizer -transport=stdio

Guía de uso

Cuándo usar cada cosa

Quiero...	Haz esto...
Usar mi API con Claude Desktop	Añade configuración a `claude_desktop_config.json` (ver Inicio rápido)
Probar si mi API funciona con MCP	Ejecuta `mcpizer -transport=stdio` y revisa la lista de herramientas
Ejecutar como servicio en segundo plano	Usa el modo SSE con `mcpizer` (sin argumentos)
Depurar problemas de conexión	Establece `MCPIZER_LOG_LEVEL=debug`
Usar un repositorio privado de GitHub	Usa URLs `github://` (requiere CLI `gh`)
Usar gRPC sin reflexión	Usa archivos .proto con el campo `server`
Múltiples entornos, misma API	Usa el mismo archivo de esquema, diferentes valores de `server`

Configuración

MCPizer busca la configuración en este orden:

Indicador de línea de comandos -config (mayor prioridad)
Variable de entorno $MCPIZER_CONFIG_FILE
configs/mcpizer.yaml (predeterminado)

Tipos de API compatibles

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

Servicios Connect-RPC (¡NUEVO!)

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

Características de Connect-RPC:

Modo HTTP/JSON: Legible para humanos, funciona con curl y herramientas de navegador
Modo gRPC: Protocolo binario, más eficiente
Soporte dual: El mismo servicio se puede acceder mediante ambos modos
Sin necesidad de proxy: Comunicación HTTP/JSON directa

Archivos de esquema separados y servidores de API

MCPizer admite archivos de esquema OpenAPI que están alojados por separado del servidor de API real. Esto es útil cuando:

La API no expone su propio esquema - Puedes escribir una especificación OpenAPI para cualquier API
El esquema se gestiona por separado - El equipo de documentación mantiene los esquemas de forma independiente
Múltiples entornos - Un archivo de esquema para APIs de desarrollo/staging/producción

Cómo 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

La especificación OpenAPI contiene URLs de servidor:

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

MCPizer:

Obtendrá el esquema desde la URL de schema_sources
Leerá la sección servers de la especificación OpenAPI
Usará la primera URL de servidor disponible para las llamadas reales a la API

Ejemplo: Crear una especificación OpenAPI para una API sin documentación

Si tienes una API en https://internal-api.company.com que no proporciona OpenAPI:

Escribe tu propia especificación 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}

Alójala en cualquier lugar:
- GitHub: https://raw.githubusercontent.com/yourorg/specs/main/api.yaml
- S3/CDN: https://cdn.company.com/api-specs/v1/openapi.json
- Archivo local: ./schemas/third-party-api.yaml
Apunta MCPizer a tu archivo de esquema

Proceso de auto-descubrimiento

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 compatibles:

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
Ver lista completa

Servicios 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

Opción 1: Reflexión gRPC (requiere reflexión habilitada):

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

Opción 2: Archivos .proto (¡NUEVO! - más seguro, no se necesita reflexión):

Aloja tus archivos .proto en cualquier lugar (GitHub, S3, CDN, etc.)
Las URLs de GitHub (github://) usan automáticamente la autenticación CLI de gh
Especifica el endpoint server por separado
Perfecto para producción donde la reflexión está deshabilitada
Permite versionado de esquemas y validación CI/CD

Para implementaciones alternativas de reflexión, consulta:

connectrpc/grpcreflect-go La implementación de reflexión de Connect-Go

Archivos locales

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

Integración con GitHub (¡NUEVO!)

MCPizer puede obtener esquemas directamente de repositorios de GitHub usando la herramienta CLI gh - incluyendo archivos OpenAPI y .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

Beneficios:

✅ Funciona con repositorios privados (usa autenticación gh)
✅ Especifica ramas/etiquetas con la sintaxis @ref
✅ No es necesario gestionar URLs raw de GitHub ni tokens
✅ Admite archivos OpenAPI y .proto
✅ Los archivos de configuración también se pueden almacenar en GitHub

Requisitos:

Instala GitHub CLI: brew install gh (macOS) o consulta la documentación
Autentícate: gh auth login

Variables de entorno

Variable	Predeterminado	Cuándo usarla
`MCPIZER_CONFIG_FILE`	`~/.mcpizer.yaml`	Configuración diferente por entorno ¡Puede ser una URL `github://`!
`MCPIZER_LOG_LEVEL`	`info`	Establécelo en `debug` para solucionar problemas
`MCPIZER_LOG_FILE`	`/tmp/mcpizer.log`	Cambia la ubicación del registro (modo STDIO)
`MCPIZER_LISTEN_ADDR`	`:8080`	Cambia el puerto (modo SSE)
`MCPIZER_HTTP_CLIENT_TIMEOUT`	`30s`	Las APIs lentas necesitan más tiempo

Escenarios comunes

"Quiero que Claude use mi aplicación 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?"

"Quiero probar si MCPizer ve mi 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

"Mi API necesita autenticación"

# 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: Estos encabezados se usan al obtener los archivos de esquema. Los encabezados necesarios para las llamadas reales a la API deben definirse en la propia especificación OpenAPI.

"Estoy obteniendo 'no hay herramientas disponibles'"

# 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

"Quiero usar los servicios gRPC de mi empresa"

Opción 1: Si la reflexión está habilitada

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

Opción 2: Usando archivos .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

"Quiero ejecutar MCPizer como servicio"

Opción 1: Ejecución directa del binario

# 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

Solución de problemas

Comandos de depuración

# 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 comunes

Problema	Solución
"No hay herramientas disponibles"	• Verifica que la API esté en ejecución • Prueba la URL directa del esquema • Revisa los registros de depuración
"Conexión rechazada"	• ¿Puerto incorrecto? • Verifica si la API está en ejecución • ¿Firewall bloqueando?
"La cadena debe tener como máximo 64 caracteres"	Actualiza MCPizer - esto está corregido en la última versión
gRPC "conexión rechazada"	• Habilita la reflexión en tu servidor gRPC • Verifica con `grpcurl` • O usa el enfoque de archivos .proto en su lugar
"Esquema no encontrado en la URL base"	• Especifica la ruta exacta del esquema • Verifica si la API expone OpenAPI
"Archivo .proto sin servidor"	• Añade `server: grpc://host:port` a tu configuración • Requerido para archivos .proto

Ejemplos

Ejemplo de flujo completo

Así es como MCPizer funciona con un servicio 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

Ejemplo de 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

Ejemplo de gRPC

Opción 1: Usando reflexión

// 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)
}

Opción 2: Usando archivos .proto (recomendado para producción)

# 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

Beneficios:

✅ No se necesita reflexión en producción
✅ Esquemas con control de versiones
✅ CI/CD puede validar esquemas
✅ El mismo .proto para múltiples entornos

Desarrollo

# 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

Consulta examples/ para ejemplos más completos:

proto-config.yaml - Uso de archivos .proto con múltiples entornos
fastapi/ - Ejemplo de integración con FastAPI
grpc-service/ - Servicio gRPC con reflexión

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Revisa los problemas existentes primero
Haz un fork y crea una rama de funcionalidad
Añade pruebas para la nueva funcionalidad
Envía un PR

Licencia

MIT - consulta LICENSE