automeli-docs-mcp

Servidor MCP (Model Context Protocol) que expone la documentación de la API pública de Automeli a LLMs (Claude Desktop, Claude Code, claude.ai, etc.).

Es solo lectura de la documentación: NO ejecuta la API real. Funciona como un wrapper de fetch + cache sobre los artefactos machine-readable que sirve www.automeli.com (openapi.json, errors.json, llms-full.txt, llms.txt). No duplica el spec → sin drift con la doc.

Versiones de la API (desde 0.2.0)

La doc canónica de la landing es la API v2; la v1 quedó congelada bajo /api-docs/v1/. Todas las tools aceptan un parámetro opcional version:

• "v2" (default) → artefactos canónicos (/api-docs/openapi.json, …).

• "v1" → artefactos congelados (/api-docs/v1/…), solo para integraciones legadas.

errors.json (catálogo de errores) y llms.txt son compartidos entre versiones. Las respuestas incluyen api_version, leído del propio artefacto, para que el cliente confirme qué versión está viendo.

Transición: mientras la landing desplegada siga siendo la vieja (canónica = v1, sin /api-docs/v1/), pedir "v1" cae a los artefactos canónicos — que en ese mundo son v1. Cuando la landing nueva (rama feat/api-docs-v2 de automeli.com) se despliegue, la canónica pasa a v2 y este server la sirve sin cambios. Después de ese deploy conviene refrescar el snapshot (pnpm run build).

Related MCP server: mcp-docs

Cómo obtiene los datos

1. Live + cache con TTL — al pedir un artefacto, lo trae de www.automeli.com, valida sintaxis y forma mínima (que openapi.paths sea un objeto con entradas, que errors.errors sea un array, que los .txt parezcan la doc) y lo cachea en memoria (default 15 min) con clave versión:artefacto. Un 200 con basura (p. ej. {} o un envelope de error de un CDN) NO se cachea: se degrada al snapshot. Mientras esté fresco, no vuelve a la red.

2. Fallback offline — si la red falla, sirve un snapshot bundleado (data/snapshot/) que se baja en cada build. Así el server arranca al instante y sigue andando sin conexión. El snapshot se cachea ya vencido: apenas vuelva la red, la próxima llamada reintenta live. Los artefactos v1 congelados se guardan como v1-* (opcionales: si la landing aún no los sirve, se omiten). Si un pedido de v1 termina servido por la doc canónica (fallback de transición), las tools estructuradas agregan version_warning y las de prosa (describe_flow, generate_snippet) anteponen el aviso en el propio texto.

La fuente de verdad es siempre la doc live; el snapshot es solo red de seguridad.

Tools (7, todas read-only)

Instalación y build

Este servidor se distribuye como repositorio para clonar (no se publica en npm). Requiere Node ≥ 20. Se recomienda pnpm, pero npm también funciona: el repo trae pnpm-lock.yaml para builds reproducibles con pnpm; npm resuelve desde package.json (solo 2 dependencias) y genera su propio lockfile.

git clone https://github.com/Automeli-Services-Organization/automeli-docs-mcp.git
cd automeli-docs-mcp

# con pnpm (recomendado):
pnpm install
pnpm run build          # corre prebuild (baja snapshot) + compila a dist/

# …o con npm:
npm install
npm run build

Verificación opcional (usa npm run … si instalaste con npm):

pnpm run smoke          # test de interoperabilidad con el cliente MCP real
pnpm run smoke:offline  # el mismo smoke contra una base muerta → fuerza el camino snapshot

El smoke es agnóstico de versión (descubre los operationIds vía list_endpoints), así que pasa igual antes y después del deploy de la landing v2. Para probarlo contra otra fuente (ej. un dev server con la doc nueva):

AUTOMELI_DOCS_BASE=https://<base> AUTOMELI_DOCS_TIMEOUT_MS=10000 pnpm run smoke

Conectarlo a un cliente MCP

Claude Code (CLI)

# apuntando al build local (usa la ruta ABSOLUTA a tu clon):
claude mcp add --scope user automeli-docs -- node /ruta/absoluta/a/automeli-docs-mcp/dist/index.js

Dos detalles que ahorran un rato de confusión:

• Usa --scope user. Sin él, el servidor queda registrado solo para la carpeta desde la que ejecutaste el comando — y como lo natural es ejecutarlo desde dentro del clon, después no aparece al trabajar en otro proyecto.

• Reinicia la sesión. Las herramientas de un servidor recién agregado no se cargan en la sesión en curso: cierra y vuelve a abrir claude. Que claude mcp list diga ✔ Connected no significa que ya las puedas usar ahí mismo.

Claude Desktop

En claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "automeli-docs": {
      "command": "node",
      "args": ["/ruta/absoluta/a/automeli-docs-mcp/dist/index.js"]
    }
  }
}

Configuración (variables de entorno)

Refrescar el snapshot

El snapshot se regenera solo en cada pnpm run build. Para refrescarlo a mano:

pnpm run fetch-snapshot

Notas / límites conocidos

• components.schemas del OpenAPI hoy trae pocos schemas nombrados (bodies inline). Suficiente para las tools; si se quisiera tipado fuerte por endpoint, enriquecer el registry de la doc (automeli.com/src/lib/api-spec/).

• explain_error devuelve when + doc_url (no hay un campo estructurado "cómo reaccionar"; esa guía vive en la prosa de la doc).

• generate_snippet extrae el bloque exacto de llms-full.txt (incluye los valores de query de ejemplo autorados). Si esa extracción fallara, cae a un snippet generado desde el OpenAPI (sin esos query de ejemplo).

• describe_flow y la sección de guías dependen de los headings de llms-full.txt / llms.txt; el formato de la landing nueva (rama v2) se verificó compatible (anclas {#operationId} en H3, fences bash/javascript/python, flujo como H2).