API Documentation MCP

Servidor Model Context Protocol que permite a un asistente consultar una especificación OpenAPI 3.x. Interpreta el documento, busca operaciones, devuelve el detalle de un endpoint o de un esquema, y publica esa información como herramientas, recursos y prompts.

La versión 1.0 lee un archivo local. No llama a la API documentada ni modifica el archivo.

Requisitos

• Node.js 22.19 o superior

• npm 10 o superior

Related MCP server: Swagger MCP Server

Instalación

npm install

El ejemplo incluido es examples/openapi.yaml, una API de usuarios. No hace falta descargar otra especificación para probar el servidor.

Configuración

Las variables son opcionales. Sin ellas se usa el ejemplo.

export DOCS_DIR=./examples
export OPENAPI_FILE=openapi.yaml

El archivo tiene que ser .yaml, .yml o .json y quedar, también si es un enlace simbólico, dentro de DOCS_DIR. Los detalles están en docs/security.md.

Ejecutar

npm run dev

El proceso espera mensajes MCP en stdin y responde por stdout. Los registros van a stderr. Si el documento no existe o no es OpenAPI 3.x válido, el proceso termina y stdout queda vacío.

Para el artefacto compilado:

npm run build
npm start

Conectar un cliente

{
  "mcpServers": {
    "api-documentation": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/ruta/al/proyecto",
      "env": {
        "DOCS_DIR": "./examples",
        "OPENAPI_FILE": "openapi.yaml"
      }
    }
  }
}

El servidor se identifica como api-documentation-mcp versión 1.0.0.

MCP Inspector

npx @modelcontextprotocol/inspector npm run dev

Pulsa Connect. En Tools, Resources y Prompts aparecen las capacidades de abajo. El cliente de las pruebas automáticas es @modelcontextprotocol/client; el inspector usa el mismo transporte STDIO.

Herramientas

search_documentation con autenticación devuelve POST /api/auth/login. get_schema con User devuelve id, email y role. Una búsqueda sin coincidencias devuelve matches vacío. Un método desconocido o un endpoint ausente vuelve como error de la herramienta.

Recursos

El overview del ejemplo informa la API Users API, cuatro operaciones y cuatro esquemas.

Prompts

review_endpoint con /api/users y GET incluye esa operación y la instrucción de no inventar datos. Si la operación no existe, el prompt falla con el mensaje de dominio.

Pruebas

npm test
npm run lint
npm run build
npm run format:check

npm test cubre el dominio, el parser, el repositorio, los casos de uso y el protocolo MCP, incluido un proceso STDIO real. La matriz está en docs/testing-guide.md.

Documentación

Licencia

MIT. Ver LICENSE.