Zuar Portal — MCP Server

Permite que Claude gestione tu Zuar Portal (zPortal) por ti — crea bloques HTML, construye páginas, gestiona fuentes de datos, consultas, temas y usuarios, explora datos reales y mantén un historial versionado en git y reversible de cada cambio, todo a través de lenguaje natural.

Un servidor MCP que expone la API REST y de autenticación de Zuar Portal a cualquier cliente MCP (Claude Desktop, Claude Code, …). Convierte «hazme un panel de ventas» en la secuencia correcta de llamadas autenticadas — descubrir fuentes de datos → escribir una consulta guardada → crear un bloque HTML validado → vincularlo → colocarlo en una página — con guía de creación integrada, seguridad de escritura por capas y un historial reversible.

[!TIP] Instalación (Claude Code) — clónalo, compílalo y regístralo:

git clone https://github.com/zuarbase/Zuar-Portal-MCP-Public.git ~/zuar-portal-mcp
cd ~/zuar-portal-mcp && npm install && npm run build
claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js

Luego haz cd a una carpeta de proyecto y ejecuta /portal-setup para conectarlo a un portal. Detalles ↓

Sin terminal (Claude Desktop): descarga zuar-portal-mcp.mcpb desde la última versión y haz doble clic en él. Detalles ↓

De un vistazo

flowchart TB
    CD["<b>MCP Client</b><br/>Claude Desktop · Claude Code · any MCP client"]
    CD -- "JSON-RPC / stdio" --> S

    subgraph server["zuar-portal-mcp server"]
        direction TB
        S["index.ts → buildServer()"]
        S --> BT["🧱 <b>Block tools</b><br/>typed authoring + place_blocks"]
        S --> RT["📦 <b>Resource tools</b><br/>generic CRUD · 18 kinds (blocks included)"]
        S --> AT["⚡ <b>Action tools</b><br/>query · profile · users · config"]
        S --> VC["🕓 <b>Version-control tools</b><br/>snapshot · history · diff · restore"]
        S --> EL["🪄 <b>Setup &amp; design</b><br/>configure_project · synthesize_theme"]
        G{{"🛡️ <b>Safety &amp; integrity gates</b><br/>write-domain · structure · refs · impact · SQL"}}
        BT & RT & AT & VC & EL --> G
    end

    G --> HTTP["portalClient.ts<br/>login · X-Api-Key · retry · circuit breaker"]
    HTTP -- "/api + /auth · HTTPS" --> P[("Zuar Portal")]
    BT -. "mirrors every content write" .-> GIT[("git VC repo<br/>revertible")]

    classDef gate fill:#fde68a,stroke:#b45309,color:#000;
    class G gate

Cada escritura está etiquetada con un dominio de riesgo y pasa las compuertas de seguridad antes de que nada llegue al portal; cada escritura de contenido con éxito se replica en un repositorio git para que pueda revertirse.

Related MCP server: LaunchNotes MCP Server

Contenido

• Aspectos destacados

• Qué puede hacer Claude con él — el catálogo de 38 herramientas

• El ecosistema de agentes de Claude Code — pipeline, agentes, enrutamiento de modelo/esfuerzo

• Onboarding y personalización de temas

• Requisitos y credenciales

• 🖱️ Instalación — Claude Desktop (un clic)

• ⌨️ Instalación — Claude Code y otros clientes

• Configuración por proyecto (múltiples portales)

• Primeros pasos

• Seguridad de escritura y limitación de herramientas

• Resiliencia, observabilidad y endurecimiento

• Solución de problemas · Seguridad · Licencia

¿Trabajas en el servidor en lugar de con él? Consulta CONTRIBUTING.md.

[!NOTE] 📚 Documentación completa en docs/ — guía rápida de 5 minutos, instalación y configuración, una referencia generada de las 40 herramientas, creación de bloques, el sistema de diseño, el control de versiones, la API zPortal dentro de un bloque, el ecosystem de agentes y enrutamiento de modelos, la limitación de herramientas, las compuertas de seguridad y la resolución de problemas.

Aspectos destacados

Qué puede hacer Claude con él

40 herramientas — un única superficie uniforme ("un recurso es un recurso") en apostas de 11 grupos de capacidad. La referencia completa por herramienta se genera. directamente desde el servidor en vivo (npm run gen:docs, no pueden desfasar): docs/03 · Referencia de herramientas.

[!IMPORTANT] ¿Actualizas desde 2.x? v3.0.0 es un rediseño de la API no compatible (48 → 37 herramientas). Cada nombre v2 eliminado se .map a una primitiva v3 — consulta CHANGELOG.md. Define PORTAL_COMPAT_TOOLS=1 para registrar temporalmente los nombres antiguos como alias obsoletos que reenvían a los mismos controladores v3 controlados.

🧱 Herramientas de bloque — tipadas y validadas

Los bloques forman parte ahora de un tipo de recurso de primera clase: lista, vet, and delete them con la herramienta genérica de recursos (resource: "block"), y las reglas de autoría de bloque se aplican con un validador en función del recurso en el nodo de entrada del registro — create_resource (block) se valida exactamente igual que create_block. Los frentes tipados siguen existiendo para una authoría ergonómica:

Entrada de archivo [4.2.0] — create_block, update_block y validate_block admiten html_file y css_file. El servidor es quien lee los bytes, de modo que un modelo nunca los maneja directamente. Reescribir un bloque grande llamando a una herramienta no es copiar, sino retranscribir: gasta tokens y normaliza caracteres silenciosamente (una raya que parece un guión dentro de una clase de caracteres cambia lo que el patrón detecta — y le pasa a revisión). En su lugar dal una ruta, edita el archivo en el sitio, y así solo se transcribe lo cambiado. Todas la compuertas actúan igual en una y otra case. Las lecturas se aplican a , y PORTAL_FILE_ROOTS. | `bind_block_query` | Enlaza un bloque a una fuente de datos/query (crea automáticamente la consulta); define `ui_queries`. | | `place_blocks` | Una sola primitiva de colocación — agregar, actualizar, ocultar o quitar bloques de un grid en un instante. mode: "merge" agrega/actualiza (y respeta remove: [...]); mode: "replace" + confirm: true hace la página exactamente la lista indicada y conserva las grid.layouts y flags de ocultación ya personalizadas. |

Pass resource de operación/body/id. Contains una API describe_resource para campos de cada recurso, los campos obligatorios, verbos válidos. Read new resources via pair estimaciones.

Recursos cubiertos: block, layout (páginas), datasource, query, db_modification, partial, theme, snippet, translation, dashboard, tag, user, group, permission, access_policy, api_key, credential, system.

Cada herramienta de escritura acepta dry_run: true — se ejecutan todas las compuertas (dominio, estructura, reglas por tipo, referencias, impacto), no se escribe nada, y la respuesta lleva applied: false más lo que se habría escrito.

El perfil del usuario actual es ahora un CRUD de recurso simple: get_resource / update_resource con resource: "user", id: "me". El alcance de la migración guiada es el prompt migration_kickoff (ver Prompts más abajo).

Consulta docs/07 · Control de versiones.

Recursos (zportal://guide/*): orientación de autoría que Claude lee antes de construir, para que los bloques sigan las convenciones de zPortal incluso en una máquina nueva: block-structure, currentblock, zportal-api, charting, conventions, design-system, visual-verification, migration-1.18, loading-overlay, migration-playbook y block-performance.

Prompts: los flujos de trabajo guiados ahora viven aquí en lugar de en la superficie de la herramienta (9): zuar_portal_start (el abridor de sesión más económico: confirma la conexión en una sola llamada, informa una línea y pregunta qué sigue), zuar_portal_quickstart (orientar → enrutar), create_zportal_block (descubrir → construir → crear), setup_zuar_project (conectar esta carpeta, enruta a configure_project), migrate_block_to_118 (un bloque heredado → el ciclo de vida 1.18), add_loading_overlay (el spinner autorizado + desvanecimiento), block_perf_pass (la auditoría de rendimiento con grandes conjuntos de datos: medir → recortar SELECT * → precarga de la librería de gráficos → timeouts honestos de 60 s), design_intake (temática guiada: recorre marca/sitio web/densidad/radio, impulsa synthesize_theme y luego crea el tema mediante create_resource) y migration_kickoff (alcance de migración guiado: agrupa las decisiones de alcance, escribe .zuar-portal/migration-scope.json y luego ejecuta migration_preflight).

El ecosistema de agentes de Claude Code

Cuando este repositorio es tu directorio de trabajo de Claude Code, las herramientas MCP vienen con un equipo de especialistas en .claude/. No manejas create_block/bind_block_query a mano: describes lo que quieres y un pipeline con compuertas construye, estiliza, refuerza y revisa. Guía completa: docs/13 · Agentes y flujos de trabajo.

El pipeline de bloques

Los bloques nunca se publican en bruto. Una especificación fluye a través de compuertas de calidad, cada una un subagente enfocado:

flowchart LR
    spec([spec]) --> B["🏗️ builder"] --> St["🎨 stylist"] --> R["📱 responsive"] --> D["🔧 debugger"]
    D --> A{"🚨 adversary<br/><b>CODE GATE</b>"}
    A -- "blocking (≤2 rounds)" --> D
    A -- "clean" --> V{"👁️ visual<br/><b>GATE</b>"}
    V -- "blocking (≤2 rounds)" --> D
    V -- "clean / skipped" --> Ad["🧭 advisor"] --> ship([ship ✅])

    classDef gate fill:#fde68a,stroke:#b45309,color:#000;
    classDef ro fill:#dbeafe,stroke:#1d4ed8,color:#000;
    class A,V gate
    class Ad ro

El adversario (compuerta) pone a prueba el bloque y demuestra cada hallazgo con evidencia; mientras devuelva hallazgos bloqueantes, el pipeline vuelve al depurador. La compuerta visual (el adversario con ojos de navegador) entonces abre el bloque renderizado en Claude for Chrome: captura de pantalla, consola, red; y un renderizado en blanco, un error de consola, datos de muestra no en vivo o un desbordamiento también devuelven al depurador; es de mejor esfuerzo y se omite con una nota cuando la extensión no está conectada o el bloque no está en una página. El asesor pregunta: "¿es este el bloque correcto?" Todas las compuertas son de solo lectura: no llevan herramientas de escritura y físicamente no pueden mutar el portal (navegar/capturar pantallas es de solo lectura). Más allá de los seis agentes del pipeline, cuatro especialistas manejan trabajos más amplios: portal-data-expert, portal-theme-designer, portal-bulk-operator (primero instantánea) y portal-onboarding.

Ver el portal (Claude for Chrome)

Cada compuerta anterior razona sobre un bloque a partir de su código y filas de consulta, pero un bloque puede validar, vincular y aun así renderizar en blanco, lanzar un error de consola en tiempo de ejecución, desbordar su celda de cuadrícula o mostrar silenciosamente su respaldo de muestra codificado en lugar de datos en vivo. Con la extensión Claude for Chrome conectada, los agentes pueden ver el portal: abrir la página, capturar el bloque y leer la consola/red del navegador, para depuración visual y una aprobación visual final.

• Registrado en la configuración. configure_project pregunta si usas Claude for Chrome y almacena browser.claudeInChrome en ./.zuar-portal/config.json; get_capabilities lo informa.

• Se usa donde vale la pena. El depurador mira antes de adivinar; el adversario es dueño de la compuerta visual; el estilista y el especialista en responsive capturan su trabajo (este último recorre anchos con resize_window); el asesor verifica que se lea de un vistazo.

• Advertencia de inicio de sesión. El MCP se autentica con una clave API, pero el navegador necesita una sesión iniciada: para ver páginas privadas debes haber iniciado sesión en tu portal en Chrome. El MCP no puede iniciar sesión por ti.

• Elegante por diseño. ¿Sin extensión, o el bloque no está en una página? Cada agente recurre a la revisión solo con código y lo indica. La doctrina vive en el recurso zportal://guide/visual-verification.

Comandos de barra

Enrutamiento de modelo y esfuerzo

Cada agente se ejecuta con el modelo y el esfuerzo de razonamiento que se ajustan a su trabajo: preciso donde importa el juicio, barato donde el trabajo es mecánico. Tres capas que se componen:

1 · Valores predeterminados de agente (model:/effort: en frontmatter): para una llamada directa (una edición quirúrgica rápida, o un agente despachado desde un comando):

2 · Alternancia de tier del flujo de trabajo: portal-block-pipeline.js y portal-audit.js aceptan args:{ …, tier } y establecen el modelo/esfuerzo de cada etapa explícitamente:

3 · Comandos fijados en sonnet · medio: solo orquestan (pre-vuelo → despacho → síntesis); la calidad vive en los agentes/flujo de trabajo que llaman. /portal-build y /portal-audit infieren el tier a partir de tu redacción.

El servidor MCP nunca selecciona un modelo: solo lo hacen los agentes, comandos y flujos de trabajo que lo impulsan. Re-nivela mediante el frontmatter del agente o la tabla ROUTING de un flujo de trabajo; consulta .claude/README.md.

Incorporación guiada y temática

Por defecto, configure_project sirve un pequeño formulario web de bucle local (http://127.0.0.1:<puerto-aleatorio>) desde el proceso MCP, abre tu navegador con el mejor esfuerzo y devuelve el enlace de inmediato: escribes la URL, la clave API, los interruptores de seguridad de escritura, el alcance de acceso y el control de versiones en el navegador, de modo que la clave API nunca pasa por el modelo. Al guardar, valida en vivo, escribe la configuración 0600 ignorada por git y aplica el cambio en vivo. Recurre a la elicitación del MCP (indicaciones campo por campo) y luego a argumentos cuando no se puede usar un navegador: pasa ui:false, o pasa portal_url + api_key + user_id como argumentos. La temática guiada es el prompt MCP design_intake, que orquesta la herramienta pura synthesize_theme. Consulta El formulario de configuración del navegador.

flowchart TB
    subgraph setup["🔌 configure_project — connect a portal"]
        direction TB
        s1["Portal URL"] --> s2["API key 🔒"] --> s3["User ID"] --> s4{"add GitHub VC?<br/>(optional)"}
        s4 --> s4b{"use Claude for Chrome?<br/>👁️ visual checks"}
        s4b --> s5["✓ live portal login<br/>✓ GitHub token + repo (API)"] --> s6[["writes .zuar-portal/config.json<br/>+ .gitignore"]]
    end
    subgraph intake["🎨 design_intake prompt — theme the portal"]
        direction TB
        d1["brand + website"] --> d2["fetch site 🛡️ SSRF-guarded<br/>→ suggest brand colors"] --> d3["palette · density · radius"]
        d3 --> d4["header + sidebar style"] --> d5{"confirm?"} --> d6[["synthesize_theme →<br/>create_resource (theme)"]]
    end

• configure_project se niega a sobrescribir una configuración existente, valida con un inicio de sesión real y escribe un ./.zuar-portal/ ignorado por git. También pregunta si usas Claude for Chrome (almacenado como browser.claudeInChrome) para que el pipeline de construcción pueda ver renderizar tus bloques: depuración visual + una compuerta visual final (consulta Ver el portal). El prompt setup_zuar_project y /portal-setup enrutan a él; pasa interactive: false para la ruta directa sin indicaciones. (Reemplaza setup_portal e init_project_config de la v2.)

• El prompt design_intake obtiene el sitio web de la marca a través de la búsqueda protegida contra SSRF de synthesize_theme para sugerir una paleta, luego recorre densidad/radio/encabezado/barra lateral y, con tu confirmación, crea un recurso theme mediante create_resource. synthesize_theme en sí es puro: devuelve el mapa de tokens y la llamada exacta create_with, y nunca escribe.

Requisitos

• Un Zuar Portal accesible por HTTPS, con una cuenta que pueda gestionar bloques (se recomienda administrador).

• Node.js 18+: para Claude Code y cualquier otro cliente MCP. (El .mcpb de un clic de Claude Desktop incluye su propio Node, así que no necesitas nada.)

Obtener tus credenciales del portal

Necesitas tres valores, introducidos una vez durante la instalación.

[!IMPORTANT] Mantén privadas la API Key y el User ID. En el bundle de Claude Desktop se declaran como sensibles (enmascaradas, guardadas de forma segura) y no abandonan jamás la máquina donde se ejecuta el servidor.

Instalación — Claude Desktop (un clic)

1. Descarga zuar-portal-mcp.mcpb de la última versión.

2. Haz doble clic en el archivo, o bien arrástrelo a la ventana de Claude Desktop. Se abrirá un diálogo de instalación.

3. Rellena Portal URL, Portal API Key y Portal User ID (y, opcionalmente, los conmutadores para la seguridad de escritura).

4. Confirma. Las herramientas, los recursos y los prompts quedan disponibles para Claude.

Para actualizarlo más adelante, instala un .mcpb más nuevo sobre el anterior.

Instalación — Claude Code y otros clientes MCP

Este servidor habla MCP por stdio, así que cualquier cliente compatible con MCP puede usarlo. Clónalo, compílalo una vez y registra el punto de entrada de la compilación; para eso necesitas Node ≥ 18 y git.

Regístralo una sola vez para todos los proyectos:

git clone https://github.com/zuarbase/Zuar-Portal-MCP-Public.git ~/zuar-portal-mcp
cd ~/zuar-portal-mcp
npm install
npm run build
claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js

[!IMPORTANT] Deja el clon donde está. claude mcp add registra la ruta absoluta a dist/index.js; si mueves o borras la carpeta, el servidor se romperá con un spawn ENOENT. Elige un destino permanente — ni /tmp ni ~/Downloads.

Para actualizarlo: haz pull y recompila en el lugar. La ruta no cambia, así que no tienes que volver a registar; pero reinicia el cliente, porque la lista de herramientas solo se obtiene durante el handshake.

cd ~/zuar-portal-mcp && git pull && npm install && npm run build

Luego, se en cada carpeta de proyecto del portal conéctalo a ese portal:

mkdir ~/work/acme-portal && cd ~/work/acme-portal
claude
> /portal-setup

/portal-setup te pide tus tres valores, los verifica con un inicio de sesión real y escribe un ./.zuar-portal/config.json ignorado por .gitignore. Cada carpeta puede apuntar a un portal diferente — ver Configuración por proyecto ↓.

En el \.mcp\.json del proyecto (o en claude_desktop_config.json) — apunta args al punto de entrada compilado de tu clon, con una ruta absoluta (aquí ~ no se expande):

{
  "mcpServers": {
    "zuar-portal": {
      "command": "node",
      "args": ["/Users/you/zuar-portal-mcp/dist/index.js"]
    }
  }
}

[!IMPORTANT] Deja env vacío. No pongas PORTAL_URL / PORTAL_API_KEY / PORTAL_USER_ID en tu config del cliente. Las credenciales en el mapa env del cliente deben guardar one portal global que todos los proyectos heredan en silencio — así que una que una encontrada carpeta que crees que apunta a preproducción acaba publicando en producción sin que te des cuenta. En su lugar, deja que /portal-setup credades de escritura por proyecto. Así, cada proyecto lleva una fe de huella, y el servidor rechaza una escritura dirigida a un portal al que esa carpeta no está vinculada. Las variables de entorno siguen funcionando (últiles para la CI o un instalación de un solo portal), pero el archivo de proyecto es la vía que no te puede dar sorpresas.

Configuración por proyecto (varios portales)

Una instalación de MCP puede impulsar un portal diferente — y un repositorio de estado git diferente — en cada carpeta. Al arranaryerver, el servidor resuelve las credenciales por capas, que nadie tenga prioridad:

flowchart LR
    A["1 · Project config<br/><code>./.zuar-portal/config.json</code><br/>(walks up from cwd)"] --> R{{"resolved<br/>credentials"}}
    B["2 · Environment<br/><code>PORTAL_*</code> env vars<br/>(Desktop / MCPB)"] --> R
    C["3 · Bundle config<br/><code>config.json</code> beside bundle"] --> R

La mayoría de las opciones se resuelven por campo, así que un archivo de proyecto puede definir solo vc.dir y heredar el resto. Los valores vacíos se ignoran, de modo que un valdo en blanco en Desktop puede heredar de la herencia de un proyecto.

[!WARNING] Las credenciales del portal son la excepción: el situarlas de un solo desde UNA capa (de la capa) (v4.0.0). Una capa que nombre cualquiera de url / apiKey / userId debe proporcionar todas las tres, o el arranque falla con error explícito. La fusión por campos supuso un riesgo entre portales: un proyecto con url pero sin apiKey tomaba silenciosamente PORTAL_API_KEY del entorno — la dirección de un portal junto con la clave de otro.

El archivo usa un único esquema tanto para el portal como para su repo de control de versiones:

{
  "portal": { "url": "https://team-a.zuarbase.net", "apiKey": "…", "userId": "…" },
  "vc":     { "dir": "/path/to/team-a-state", "push": true,
              "remote_url": "https://github.com/you/team-a-portal-state.git", "token": "…" }
}

Móntalo sin editar el JSON a mano: pide a Claude que ejecute configure_project (ver Incours guidado ↑). get_capabilities muestra el portal/repo que está en vigor bajo su clave config (secretos enmascarados). ./.zuar-portal/ está en .gitignore, así que las credenciales no se gitignore.

Primeros pasos

¿Portal nuevo? Empieza aquí. Desde la carpeta en la que trabajo:

cd ~/work/acme-portal
claude
> /portal-setup

Un solo comando, and conecta la carpeta al portal (escribe las credenciales ignorado por git + una huella de vinculación), per filtra las fuentes de datos, entabla una entrevista sobre el negocio y escribe un resumen del proyecto que leerán los demás. Todo lo que sigue asume que este paso ya está hecho.

A continuación, solo pregunta a Claude:

1. Comprueba la conexión — "Lista las fuentes de datos de mi portal." → list_resource (datasource).

2. Mira datos reales — "Muéstrame algunas filas de la fuente de datos Sales." → profile_datasource (estadísticas por columna y filas de ejemplo reales, para que Claude vea los nombres reales de las columnas).

3. Crea un bloque — "Crea un bloque tarjeta de estadística 'Total Orders' para mostrar el recuento de pedidos de Sales." → lee zportal://guide/*, construye el bloque de la dos-ficha, create_block e informa el UUID.

4. Itera — "Haz el número de mayor tamaño y que use el color principal del portal." / "Conviértelo en un gráfico de barras de pedidos por estado." → update_block.

[!TIP] En Claude Code, ejecuta /portal-build "a stat card of total orders from Sales" para cruzar todo el pipeline con barreras y compuertas, o utiliza el prompt create_zportal_block para un flujo estructurado de descubrir → construir → crear.

Seguridad de escritura y compuertas herramientas

Cada escritura lleva una etiqueta de dominio de riesgo, con una compuerta independiente:

• PORTAL_READONLY=1 desactiva todas las escrituras — aunque las lecturas y el descubrimiento siguen funcionando.

• Un escritura bloqueada devuelve un mensaje claro con el flag que debe activarse; no hay ninguna operación que en el portal.

• run_db_modification — además, require confirm: true en toda llamada.

• Las eliminaciones y las mutaciones de contraseñas de usuario se marcan como destructivas para los clientes MCP.

• dry_run: true uniforme (v3.0.0) — todas las compuertas se ejecutan (dominio, estructura, reglas por tipo, referencias, impacto), pero no se escribe nada; la respuesta informa applied: false y qué what 's changed. Una ejecucion seca nunca se salta una compuerta.

Ámbito de herramientas de privilegio mínimo (v2.5.0) — desactiva grupo completo de capacidad con PORTAL_DISABLE_TOOLS=users,config, o activa una lista blanca de solo compilación con PORTAL_ENABLE_TOOLS=blocks,resources,data (la denegación gana).

Actualización desde 2.x — PORTAL_COMPAT_TOOLS=1 (apagado por defecto) registra los nombres de herramientas de v2 eliminadas como aliases deprecated en un grupo compat; cada alias reenvía al mismo handle de v3 con compuertas, por lo que los aliases no agregan ningún privilegio adicional.

Compuertas de integridad (v2.5–2.6, en el servidor, no se puede eludir) — toda escritura de contenido se comprueba con estructura compatible del portal (una página que falda de grid.layouts se reviertea/rechaza) y referencias a badeas; el eliminación ejecuta anális de impacto previo de eliminar y evita la huérfanización de dependientes sin force=true; los borrados de usuarios no permiten eliminar al último administrador; el SQL masivo sin ámbito (destructive verb without a real WHERE — 1=1 doesn't count — plus MERGE/TRUNCATE/DROP/ALTER…DROP/GRANT) needs allow_unfiltered=true, and the check fails closed when the SQL can't be inspected. Run the read-only validate_portal anytime to fix code / find issues. Full manual: docs/16 · Safety & Integrity.

Seguridad para bucles desatendidos (no publicado) — las garantías de que los bucles paralelos/nocturnos de agentes se pueden dejar sin atención:

• Sin duplicaradores de creación: Un create que falla de modo ambiguo (la red se cayó después de que la solicitud haya quedado registrada) se verifica por nombre y se adopta si de la ya existe: nunca se vuelve a enviar a ciegas. run_db_modification nunca se reintenta automáticamente.

• Sin actualizaciones perdidas: pasa expected_updated_at (desde tu lectura) a update_resource / update_block / place_blocks y, si alguien modifica algo a mitad de vuelo, responde con un conflicto en lugar de sobrescribir en silencio.

• Sin objetos residuales: los nombres de los temporales del bucle atmp · <propósito> (o etiquetarlos scratch) y ponlos a soplar con cleanup_scratch — por defecto solo prueba contra y elimina solo candidatos sin referencia ni recientes, con el camino de compuertas, manteniendo el contenido restorable desde el VC.

• Progreso verificable: score_portal pone el puntaje a cada bloque/página con la indicación 0–100 sobre el issues reproduciblesmente y se calcula un diff contra un offline(base) guardado — la regresión del bucle es un delta por registro, no un anécdota.

• Admin no se protege a sí mismo: eliminar tu propio acceso a administración requiere allow_self_lockout=true; update_config y change_password exigen confirm (las ediciones de configuración devuelven previous_at_path para revertir con una sola llamada).

estos interruptores en el Desktop se ofrecen en el diálogo de instalación; para otros clientes, configúralos como variables de entorno. Para más: docs/14 · Tool Gating & Guidance.

Resiliencia, observabilidad y endurecimiento

Comportamiento de nivel de producción para un servidor local de un solo usuario — con valores por defecto seguros, sin configuración requerida.

Resiliencia (el cliente HTTP del portal por el que pasa toda herramienta):

Seguridad de reintentos: GET se reintenta ante cualquier señal transitoria; las escrituras solo se reintentan ante una contrapresión explícita 429/503 o un fallo de red que demuestre que nunca llegó a conectarse — nunca ante un 502/504 ambiguo, y una creación cuyo error de red pueda haber entregado la solicitud se verifica por nombre y se adopta en lugar de reenviarse (sin duplicados silenciosos).

Observabilidad — cada llamada recibe un id de solicitud, una latencia y un recuento de errores. get_metrics (siempre activo) reporta recuentos por herramienta, tasa de error, latencia, tiempo de actividad y el estado del interruptor — solo metadatos, sin cargas útiles ni secretos. Configura PORTAL_LOG_FORMAT=json para obtener registros estructurados en stderr; PORTAL_AUDIT_LOG agrega JSONL solo con metadatos para cada escritura de contenido/datos/administración.

Enmascaramiento de secretos en la salida. — los campos que contienen secretos (password, secret, token, api_key, …) se enmascaran como [redacted] en las lecturas de recursos, de modo que nunca llegan al contexto del modelo; los secretos también se detectan por forma dentro de cualquier valor o nombre — contraseñas de cadenas de conexión (postgresql://user:[redacted]@host), JWTs, claves privadas PEM, ids de claves AWS — incluidos en los resultados de execute_query / profile_datasource. Las formas genéricas hexadecimales y key=value no se enmascaran deliberadamente (los UUIDs, los git shas y los parámetros SQL son contenido legítimo que viaja de vuelta a las escrituras). Los campos de identificador *_id nunca se enmascaran; las respuestas de crear/actualizar se conservan intactas (para que un secreto recién generado pueda verse una vez). Desactívelo con PORTAL_REDACT_SECRETS=0. El contenido de Portal se devuelve, además, dentro de un envoltorio de datos no confiables, de modo que un nombre de registro envenenado se lea como datos, no como instrucciones.

Solución de problemas

Más: docs/12 · Solución de problemas.

Seguridad

• Las credenciales nunca se registran. La salida de depuración (controlada por PORTAL_DEBUG=1) va solo a stderr, así que nunca corrompe el flujo stdio de MCP.

• La clave de API y el ID de usuario se declaran sensibles en el manifiesto del paquete.

• El servidor solo habla con la URL del portal que configures; la URL base se valida como un origen http(s) bien formado al inicio. La recuperación web de synthesize_theme (impulsada por el prompt design_intake) está protegida contra SSRF.

• create_block / update_block están restringidos a type: "html" y rechazan otros tipos antes de cualquier llamada al portal.

• Los campos con secretos se redactan en las lecturas; las entradas de herramientas y los cuerpos de solicitud tienen límite de tamaño.

Ver SECURITY.md para la postura completa: la matriz de acceso a datos por grupo de herramientas, el manejo de credenciales, la salida de red y la retención de datos.

Licencia

MIT.