@hablala/mcp

Servidor MCP de Hablalá. Deja que un agente —Claude Code en tu terminal, Cursor, o cualquier cliente MCP— construya el modelo de datos de tu workspace (los objects: un diccionario aislado) y configure tu Data API por lenguaje natural. Sin tocar una UI: describes lo que quieres, el agente lo crea.

Es la pieza del flujo headless donde el modelo lo construye el agente, no un formulario.

Qué hace

Expone tools de alto nivel que el agente invoca para modelar tu dominio y iterar sobre él:

| Grupo | Tools | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Leer | hablala_describe_objects, hablala_describe_object, hablala_search_objects, hablala_query_records, hablala_get_record, hablala_list_policies | | Diccionario | hablala_create_object, hablala_update_object, hablala_archive_object, hablala_add_attribute, hablala_update_attribute, hablala_archive_attribute, hablala_create_relationship | | Policies (recorte "publicado") | hablala_create_policy, hablala_update_policy, hablala_delete_policy | | Records y grafo | hablala_create_record, hablala_update_record, hablala_delete_record, hablala_restore_record, hablala_create_edge, hablala_delete_edge |

El diseño sigue el patrón de la industria (tools genéricas dirigidas por el diccionario, no una por endpoint) — así el agente no satura su ventana de contexto. Todas las tools llevan el prefijo de dominio hablala_ (namespacing MCP): evita colisiones con otros servers montados a la vez y ayuda al modelo a elegir la correcta. Cada tool declara además las annotations estándar del protocolo (readOnlyHint/destructiveHint/idempotentHint): el host MCP las lee para decidir cuándo pedir confirmación, de modo que las tools destructivas (hablala_archive_object, hablala_archive_attribute, hablala_delete_record, hablala_delete_policy, hablala_delete_edge) no se ejecutan a ciegas. Las tools de listado (hablala_describe_objects, hablala_query_records) aceptan control de verbosidad (responseFormat: CONCISE|DETAILED, default CONCISE para ahorrar contexto) y truncan los resultados grandes con un hint que empuja a filtrar. El detalle de cada tool (parámetros, reglas) vive en llms.txt.

La autoridad real vive en el backend, no aquí. El servidor solo traduce intención en llamadas HTTP tipadas; qué puede escribir tu token y qué expone el recorte "publicado" lo decide el motor de Hablalá.

Además de listar todo el diccionario, hay tools puntuales para no traer más de la cuenta en workspaces grandes: hablala_describe_object (un objeto por slug), hablala_search_objects (busca por texto en slug/título/descripción/synonyms) y hablala_get_record (lee un record por su id rec_…).

Configuración

1. Emite un access token de máquina

En la UI de Hablalá: Ajustes → Access tokens → Nuevo. Dale permisos de diccionario (objects:create, objects:update, objects:read) y, si el agente va a configurar el recorte público, roles:read. Guarda el secreto hpat_… — se muestra una sola vez.

2. Añade el servidor a tu cliente MCP

Claude Code (terminal):

claude mcp add hablala \
  --env HABLALA_ACCESS_TOKEN=hpat_tusecreto \
  -- npx -y @hablala/mcp

Cursor / VS Code / otros — añade a tu mcp.json:

{
  "mcpServers": {
    "hablala": {
      "command": "npx",
      "args": ["-y", "@hablala/mcp"],
      "env": {
        "HABLALA_ACCESS_TOKEN": "hpat_tusecreto"
      }
    }
  }
}

Variables de entorno

| Variable | Qué es | | ---------------------- | --------------------------------------------------------------------------------------------- | | HABLALA_ACCESS_TOKEN | El access token de máquina (hpat_…). Requerido. Nunca lo pongas en código; va aquí, en el entorno. | | HABLALA_ENDPOINT | Opcional. Base URL de la API (sin /v1); default https://api.hablala.com. |

No configuras la organización ni el workspace: el token apunta a un workspace concreto y el backend lo resuelve del token en cada llamada. Una credencial es una identidad completa —el token porta su tenant y su workspace, no falsificable—, el estándar de la industria. Por eso basta con HABLALA_ACCESS_TOKEN. Si operas varios workspaces, emite un token por workspace.

Ejemplo de uso

Una vez conectado, simplemente pídeselo al agente:

«Modela un blog: un objeto article con título, cuerpo y estado de publicación; un author que es un user; y haz que el storefront solo vea los artículos publicados.»

El agente encadena las tools: hablala_describe_objects → hablala_create_object → hablala_add_attribute (×3) → hablala_create_relationship → hablala_create_policy, y verifica con hablala_query_records. El modelo de datos queda creado en tu workspace, listo para que tu frontend lo consuma con @hablala/client.

Referencia para agentes (llms.txt)

El paquete incluye un llms.txt: documentación machine-readable (formato llms.txt) con el flujo completo, las 22 tools, las reglas exactas del diccionario (slugs, data_types, cardinalidades, operadores de filtro) y un ejemplo end-to-end. Es la referencia que un agente lee para construir el modelo de datos correctamente a la primera.

Transporte

Corre como proceso local sobre stdio (el estándar para servers MCP locales): tu cliente MCP lo lanza y se comunica por stdin/stdout. No abre puertos ni expone nada a la red.

Licencia

MIT