SpecBridge

SpecBridge

Un servidor MCP que convierte especificaciones OpenAPI en herramientas MCP. Escanea una carpeta en busca de archivos de especificación OpenAPI y genera automáticamente las herramientas correspondientes. Sin archivos de configuración, sin servidores separados: solo coloca las especificaciones en una carpeta y obtén las herramientas.

Construido con FastMCP para TypeScript.

✨ Características

• 🎯 Configuración Cero: El sistema de archivos es la interfaz: solo coloca especificaciones OpenAPI en una carpeta
• 🔐 Autenticación Automática: Archivo .env simple con patrón {API_NAME}_API_KEY
• 🏷️ Aislamiento de Espacios de Nombres: Múltiples APIs coexisten limpiamente (p. ej., petstore_getPet, github_getUser)
• 📝 Soporte Completo de OpenAPI: Maneja parámetros, cuerpos de solicitud, autenticación y respuestas
• 🚀 Múltiples Transportes: Soporte para stdio y transmisión HTTP
• 🔍 Depuración Integrada: Comando list para ver las especificaciones y herramientas cargadas

🚀 Inicio Rápido

1️⃣ Instalación (opcional)

npm install -g specbridge

2️⃣ Crea una carpeta de especificaciones

mkdir ~/mcp-apis

3️⃣ Añade especificaciones OpenAPI

Coloca cualquier archivo de especificación OpenAPI .json, .yaml o .yml en tu carpeta de especificaciones:

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

4️⃣ Configura la autenticación (opcional)

Crea un archivo .env en tu carpeta de especificaciones:

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

5️⃣ Añade a la configuración del cliente MCP

Para Claude Desktop o Cursor, añade a tu configuración de MCP:

Si está instalado en tu máquina:

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

De lo contrario:

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

💻 Uso de CLI

🚀 Inicia el servidor

# Default: stdio transport, current directory
specbridge

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

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

📋 Lista las especificaciones y herramientas cargadas

# List all loaded specifications and their tools
specbridge list

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

🔑 Patrones de Autenticación

El servidor detecta automáticamente la autenticación a partir de variables de entorno usando estos patrones:

Patrón	Tipo de Autenticación	Uso
{API_NAME}_API_KEY	🗝️ API Key	Cabecera X-API-Key
{API_NAME}_TOKEN	🎫 Bearer Token	Authorization: Bearer {token}
{API_NAME}_BEARER_TOKEN	🎫 Bearer Token	Authorization: Bearer {token}
{API_NAME}_USERNAME + {API_NAME}_PASSWORD	👤 Basic Auth	Authorization: Basic {base64}

El {API_NAME} se deriva del nombre de archivo de tu especificación OpenAPI:

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

🏷️ Nombrado de Herramientas

Las herramientas se nombran automáticamente usando este patrón:

• Con operationId: {api_name}_{operationId}
• Sin operationId: {api_name}_{method}_{path_segments}

Ejemplos:

• petstore_getPetById (de operationId)
• github_get_user_repos (generado de GET /user/repos)

📁 Estructura de Archivos

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

📄 Ejemplo de Especificación OpenAPI

Aquí tienes un ejemplo mínimo que crea dos herramientas:

# ~/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

Esto crea herramientas llamadas:

• example_getUser
• example_createUser

🔧 Solución de Problemas

❌ ¿No aparecen herramientas?

1. Comprueba que tus especificaciones OpenAPI son válidas:

   specbridge list --specs /path/to/specs
   

2. Asegúrate de que los archivos tengan las extensiones correctas (.json, .yaml, .yml)

3. Revisa los registros del servidor para ver errores de análisis

⚠️ Nota: Specbridge funciona mejor cuando usas rutas absolutas (sin espacios) para el argumento --specs y otras rutas de archivo. Las rutas relativas o que contengan espacios pueden causar problemas en algunas plataformas o con algunos clientes MCP.

🔐 ¿La autenticación no funciona?

1. Verifica que tu archivo .env esté en el directorio de especificaciones
2. Comprueba que el patrón de nombres coincida con el nombre de archivo de tu especificación
3. Usa el comando list para verificar la configuración de autenticación:

   specbridge list
   

🔄 ¿Las herramientas no se actualizan después de cambios en las especificaciones?

1. Reinicia el servidor MCP para recargar las especificaciones
2. Comprueba los permisos de archivo
3. Reinicia el cliente MCP si es necesario

🛠️ Desarrollo

# 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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar problemas y pull requests.