openapi-md-mcp

Servidor MCP que convierte el spec de OpenAPI en markdown mediante divulgación progresiva (progressive disclosure).

Por qué

• Swagger UI (/docs) es un shell de JS; la IA no puede capturar el contenido

• El /openapi.json completo suele ocupar decenas de miles de tokens; meterlo entero en el contexto es demasiado caro

• Esta herramienta hace que el contexto permanente de la IA sea solo una tabla de endpoints «clave + resumen» (~1k tokens); al pulsar la clave se obtiene el detalle en markdown de un endpoint / schema individual; en la práctica ahorra ~90% de contexto

Related MCP server: OpenAPI MCP Server

Superficie de herramientas (divulgación progresiva; todas las salidas son markdown)

Clave de profundización = METHOD /path o nombre de schema; se obtiene directamente de la salida de la capa superior.

Modo lote (select + get_batch)

La profundización con una sola clave no responde preguntas transversales (para «todos los endpoints autenticados» habría que llamar a get_endpoint una por una decenas de veces); la capa de lote lo complementa:

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • Los elementos de patterns tienen la forma "METHOD /path/glob": el método puede ser * (no distingue mayúsculas); el glob de la ruta distingue mayúsculas

  • security es el nombre del scheme; entre patterns se aplica OR, y con security/tag se aplica AND

  • Si no hay coincidencias, devuelve texto de éxito (schemes / tags disponibles + sugerencias para ampliar), no un error

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • Las claves se deduplican conservando el orden, con un máximo de 40; el total de caracteres renderizados tiene un límite de 100k; si se supera, se sugiere include_refs=False o hacer lotes

  • include_refs=True integra automáticamente los $ref referenciados en el renderizado como un «apéndice de schemas compartidos» (cada nombre se renderiza solo una vez)

Configuración (env)

• El spec admite JSON y YAML; tras cargarlo, se cachea en el proceso durante 60s

• Las peticiones son de conexión directa (trust_env=False): el objetivo es un spec de localhost / red interna, no se usa el proxy del sistema (el proxy del sistema de macOS secuestra localhost y devuelve 502)

• Solo lectura; no ofrece capacidad de invocar la API (las cabeceras de autenticación no entran en la capa MCP)

Integración en cualquier repositorio

Registro a nivel de usuario de Claude Code (con un solo registro, disponible en todos los repositorios):

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

Los repositorios que necesiten diferentes fuentes de datos solo tienen que sobrescribir env en su .mcp.json a nivel de proyecto.

Cumplimiento del protocolo (MCP 2026-07-28, conocido como 2.0)

• Los nombres de herramientas / descripciones / inputSchema cumplen la especificación §Tools (juego de caracteres y longitud de nombres, orden determinista de tools/list)

• Las cinco herramientas declaran annotations.readOnlyHint: true (solo lectura)

• La semántica de errores sigue la especificación §Tools Error Handling: fallo al cargar el spec, claves desconocidas (con sugerencias de claves similares), patrones de filtro no válidos y exceso del límite de lote se lanzan como Tool Execution Error ToolError → en línea se manifiesta como CallToolResult(isError=true); el cliente retroalimenta al modelo con las sugerencias para que se autocorrija; cero coincidencias es texto de éxito; no se ofrece capacidad de call (invocar API)

• Negociación de versión: stdio usa la época de handshake initialize (máximo 2025-11-25); la época de sobre sin estado de 2026-07-28 la maneja el SDK en la capa de transporte HTTP (server/discover); el escenario stdio no está involucrado

Desarrollo

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）