SpecBridge MCP

SpecBridge MCP es un starter de MCP de tipo "clone-and-own" para exponer inteligencia de contratos OpenAPI/Huma a agentes de IA. Convierte especificaciones OpenAPI/Huma en metadatos de endpoints deterministas, esquemas, hechos de validación, DTOs referenciados y declaraciones TypeScript que los agentes pueden utilizar antes de modificar el código del frontend o del cliente.

Este proyecto está diseñado intencionalmente para ser primero un repositorio en lugar de un paquete publicado en npm: clónalo, adapta el registro de backend a tus especificaciones públicas o privadas, y registra el servidor MCP local con tu host de agentes. La implementación mantiene el núcleo neutral evitando la mutación de archivos en el flujo descendente, utilizando un backend de demostración público neutral, soportando múltiples backends inyectados y tratando las ayudas inferidas como un esfuerzo óptimo en lugar de garantías.

Estado: experimental. La superficie de la herramienta es útil para la automatización local, pero el repositorio está destinado a ser propiedad y adaptado por cada equipo.

Breve historia

SpecBridge MCP comenzó como una herramienta interna personal en SesameLab para mejorar el ciclo de desarrollo en torno a los contratos de API de backend. En la práctica, proporcionar a los agentes de IA datos estructurados de contratos OpenAPI/Huma a través de MCP redujo las alucinaciones en comparación con pedirles que leyeran las páginas de documentación de la API directamente.

Qué proporciona

• Registro de backend configurable para una o varias especificaciones compatibles con OpenAPI/Huma

• Backend de demostración de configuración cero utilizando una URL de OpenAPI pública real

• Carga y actualización de especificaciones con soporte para JSON/YAML

• Listado y filtrado de endpoints

• Paquetes de contratos de endpoints con hechos deterministas:

  • metadatos de la operación

  • parámetros

  • esquemas de solicitud y respuesta

  • esquemas de componentes referenciados

  • declaraciones DTO de TypeScript con alcance de endpoint

  • hechos de validación como required, nullable, enum, format, arrays, mapas y composición

• Generación de declaraciones DTO de TypeScript a partir de esquemas de componentes

• Ayudantes de propuesta de esfuerzo óptimo que son explícitamente secundarios a los hechos deterministas de la especificación

Objetivos no incluidos

• Publicar este proyecto en npm para la v1

• Proporcionar una abstracción CLI instalable genérica

• Mutar repositorios de frontend/cliente en el flujo descendente

• Convertirse en un generador de SDK o cliente específico de un framework

• Alojar especificaciones o almacenar datos de API de equipo de forma remota

Requisitos

• Node.js 18+

• pnpm 10+

Instalación

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

Configurar backends

SpecBridge se envía con openapi.backends.json apuntando a una API de demostración pública para que las herramientas funcionen de inmediato.

Para usar tus propias APIs, edita openapi.backends.json o apunta OPENAPI_BACKENDS_FILE a otro archivo JSON.

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

Precedencia de configuración

Para una llamada de herramienta, primero se intenta una anulación explícita de specUrl para esa llamada.

Las fuentes del registro de backend se combinan en este orden, con las fuentes posteriores anulando a las anteriores por id:

1. Backend de demostración público integrado

2. openapi.backends.json local del repositorio, cuando esté presente

3. OPENAPI_BACKENDS_FILE, cuando esté configurado

4. OPENAPI_BACKENDS, cuando esté configurado

DEFAULT_BACKEND_ID selecciona el backend predeterminado. Si no se establece, SpecBridge utiliza swagger-petstore.

Variables de entorno

• MCP_TRANSPORT: stdio o http

• MCP_HTTP_HOST: host de enlace HTTP

• MCP_HTTP_PORT: puerto HTTP

• MCP_HTTP_PATH: ruta del endpoint MCP, como /mcp

• MCP_HTTP_STATELESS: establecer en true para el modo HTTP sin estado

• DEFAULT_BACKEND_ID: ID del backend predeterminado

• OPENAPI_BACKENDS: matriz JSON de configuraciones de backend

• OPENAPI_BACKENDS_FILE: ruta a un archivo JSON de configuración de backend

• OPENAPI_FETCH_TIMEOUT_MS: tiempo de espera de recuperación para la carga de especificaciones

• OPENAPI_CACHE_TTL_MS: TTL de caché de especificaciones en memoria

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: optar por la extracción estricta de objetos JSON de scripts estáticos de Swagger UI; el JavaScript recuperado nunca se ejecuta

Ejecución

Modo stdio

pnpm mcp
# or
./mcp-server.sh

Modo HTTP

pnpm mcp:http

Modo HTTP sin estado:

pnpm mcp:http:stateless

Configuración del host MCP

Configuración stdio basada en comandos

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Ejemplo de config.toml para Codex

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

URL HTTP

Inicia el servidor:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

Luego conecta tu host a:

• http://127.0.0.1:3000/mcp

Si tu host tiene problemas con el estado de la sesión, vuelve a intentarlo con --stateless.

Herramientas

Flujo recomendado:

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

Enumera los objetivos de backend configurados, el ID del backend predeterminado y sugerencias de dominio opcionales.

load_openapi_spec

Carga o actualiza una especificación compatible con OpenAPI/Huma para un backend. Admite anulaciones directas de specUrl.

list_api_endpoints

Enumera los endpoints de una especificación cargada con filtros opcionales de etiqueta, método, subcadena de ruta y límite.

get_endpoint_contract

Devuelve un paquete de contrato de endpoint determinista: metadatos de operación, parámetros, cuerpo de solicitud, respuestas, esquemas referenciados, declaraciones DTO de TypeScript con alcance de endpoint, hechos de validación y sugerencias de esfuerzo óptimo.

generate_typescript_dto

Genera declaraciones DTO de TypeScript a partir de un nombre de esquema de componente e incluye tipos DTO anidados referenciados.

propose_new_endpoint

Devuelve una propuesta de endpoint y DTO de esfuerzo óptimo alineada con los patrones encontrados en la especificación actual. Trátalo como una ayuda para el agente, no como una garantía determinista.

Desarrollo

pnpm install
pnpm check
pnpm build
pnpm test

Scripts útiles:

• pnpm check: verificación de Biome

• pnpm format: aplicar formato de Biome

• pnpm lint: solo lint de Biome

• pnpm build: compilación limpia de TypeScript

• pnpm test: compilar y ejecutar todas las pruebas

• pnpm test:e2e: compilar y ejecutar pruebas de humo de MCP

Guía de "clone-and-own"

SpecBridge es intencionalmente primero un repositorio. Mantén el núcleo pequeño, adapta la configuración del backend localmente y deja que los agentes descendentes decidan cómo editar el código de tu cliente. Si tu equipo necesita autenticación personalizada, reglas de nomenclatura internas o hechos de contrato adicionales, agrégalos en tu clon en lugar de luchar contra una abstracción de paquete global.