MCP de Notiqo

Servidor MCP local para contrastar e importar una guía de tagging canónica en Notiqo. Está pensado para Claude Code y Codex: el agente lee la guía JSON, ejecuta siempre un dry-run y sólo escribe cuando la persona usuaria lo pide expresamente.

Requisitos

• Node.js 20 o posterior.
• Una cuenta de Notiqo que sea miembro activo del proyecto. Para escribir se requiere uno de estos roles: owner, admin, editor o contributor.
• La guía JSON que acompaña a la guía Markdown y sigue guia_analitica.schema.json.

Instalar como plugin

La forma recomendada es el plugin de packages/agent-plugin, que registra el servidor en Claude Code o Codex con npx -y @notiqo/mcp; véase su README. Requiere que este paquete esté publicado en npm. Las secciones siguientes describen la instalación manual desde el repositorio.

Instalar desde este repositorio

El paquete todavía vive dentro de este monorepo. En una copia de trabajo del repositorio de Notiqo:

cd packages/mcp
npm install
npm run build

Conectar Claude Code

En el repositorio del tenant cree o actualice .mcp.json. Sustituya la ruta por la ruta absoluta de su clon de Notiqo:

{
  "mcpServers": {
    "notiqo": {
      "command": "node",
      "args": ["/ruta/absoluta/a/friendly_track/packages/mcp/dist/index.js"],
      "env": {
        "NOTIQO_TOKEN": "${NOTIQO_TOKEN}",
        "NOTIQO_PROJECT_ID": "${NOTIQO_PROJECT_ID}"
      }
    }
  }
}

Cuando se publique el paquete, el comando equivalente será npx -y @notiqo/mcp; no copie el token dentro de .mcp.json.

Cierre y vuelva a abrir Claude Code en ese repositorio. El servidor aparece como notiqo y expone notiqo_import_guide.

Conectar Codex

En Codex CLI o Codex Desktop, añada esta entrada al archivo de configuración de usuario ~/.codex/config.toml (en Windows, normalmente C:\Users\<usuario>\.codex\config.toml). Use barras normales en la ruta aunque trabaje desde PowerShell:

[mcp_servers.notiqo]
command = "node"
args = ["C:/ruta/absoluta/a/friendly_track/packages/mcp/dist/index.js"]
env = { NOTIQO_TOKEN = "ntq_live_…", NOTIQO_PROJECT_ID = "uuid-del-proyecto" }

Reemplace los dos valores, guarde el archivo y reinicie Codex. Mejor aún, omita NOTIQO_TOKEN del TOML y guarde el token con npx -y @notiqo/mcp login <proyecto> (ver abajo): así no queda en ningún archivo de configuración. Codex soporta tools MCP; esta configuración registra el servidor local por stdio siguiendo la configuración de servidor MCP de Codex descrita en la documentación oficial de OpenAI.

Crear el token y configurar el repo

1. En Notiqo abra Integrate (barra lateral) → CLI token y pulse Create CLI token. Copie el token ntq_live_… en ese momento: Notiqo sólo conserva su hash y no puede volver a mostrarlo.

2. Guárdelo con login, desde cualquier terminal. Pide el token sin mostrarlo, lo comprueba contra Notiqo y sólo entonces lo guarda en ~/.notiqo/credentials.json (permisos 600; NOTIQO_CONFIG_DIR cambia la carpeta):

   npx -y @notiqo/mcp login uuid-del-proyecto

   El dashboard muestra este comando, ya con el proyecto, al crear el token. El servidor lee el archivo en cada llamada, así que no hace falta reiniciar Claude Code ni Codex: basta con repetir la petición al agente. El CLI notiqo usa el mismo archivo. npx -y @notiqo/mcp logout <proyecto> borra el token guardado.

   Para CI o un servidor sin home de usuario siga valiendo la variable de entorno, que tiene prioridad sobre el archivo (como GH_TOKEN en gh):

   export NOTIQO_TOKEN='ntq_live_…'

   Un NOTIQO_TOKEN vacío o con el texto literal ${NOTIQO_TOKEN} (lo que pasa .mcp.json cuando la variable no existe) se ignora y se usa el archivo.

3. Desde el repositorio del tenant ejecute el inicializador. Crea .notiqo/config.json con el proyecto y desactiva el envío de snippets:

   node /ruta/absoluta/a/friendly_track/packages/mcp/dist/index.js init uuid-del-proyecto

   Añada .notiqo/config.json a .gitignore si el identificador del proyecto no debe compartirse entre el equipo.

Uso con el agente

Adjunte o indique al agente el JSON hermano de la guía y pídale, por ejemplo:

Ejecuta notiqo_import_guide con esta guía y dryRun: true. Resume los cambios, avisos y dimensiones nuevas; no escribas todavía.

La tool carga el contexto real del proyecto, ejecuta el mismo plan Dart que usa el dashboard y devuelve el informe del dry-run. No construya ni edite una cola de operaciones manualmente.

Para aplicar exactamente lo revisado, confirme de forma explícita:

Confirmo que documentes esta guía en Notiqo. Ejecuta la misma tool con dryRun: false.

La importación crea eventos como draft, conserva la procedencia code, y es idempotente por ticket/nombre: repetir la misma guía no debe crear altas nuevas.

Uso programático (planificador y esquema)

El paquete expone el planificador determinista y el esquema JSON de la guía para que otras herramientas (por ejemplo el CLI notiqo) reutilicen la misma lógica de importación:

await import("@notiqo/mcp/assets/guide_plan.js"); // define globalThis.buildGuideImportOps / renderGuideImportPlan
const schema = require("@notiqo/mcp/schema.json"); // guia_analitica.schema.json
const { ops, issues } = JSON.parse(globalThis.buildGuideImportOps(JSON.stringify(guide), JSON.stringify(target)));

target es la respuesta de mcp-context (events, params, funnels, metrics, naming). El esquema se copia desde docs/plantillas/guia_analitica.schema.json en cada npm run build (script copy-schema, que resuelve ../../docs/ desde packages/mcp); no se edita a mano en assets/.

Regenerar assets/guide_plan.js

guide_plan.js no se escribe a mano: es la compilación a JavaScript del planificador determinista en Dart (apps/web/lib/core/helpers/guide_import.dart, vía apps/web/tool/guide_plan_web.dart). Todavía no hay script npm que lo haga; el comando exacto, desde la raíz del monorepo, es:

cd apps/web
dart compile js tool/guide_plan_web.dart -o ../../packages/mcp/assets/guide_plan.js

Hay que regenerarlo cada vez que cambie guide_import.dart, y el resultado debe quedar idéntico byte a byte si el Dart no cambió. dart compile js deja además guide_plan.js.deps y guide_plan.js.map junto al .js; sólo guide_plan.js viaja en el paquete publicado (ver files en package.json).

Seguridad y resolución de problemas

• Nunca suba NOTIQO_TOKEN, una clave de Supabase ni un PAT a Git.
• El token se resuelve en cada llamada: primero un NOTIQO_TOKEN real, después el guardado por login para ese proyecto. Si no hay ninguno, el error pide ejecutar npx -y @notiqo/mcp login <proyecto>; no hace falta reiniciar el cliente. Los errores dicen de dónde salió el token rechazado (NOTIQO_TOKEN o el guardado por login).
• Si define NOTIQO_TOKEN en la shell, recuerde que el cliente sólo ve las variables que existían cuando arrancó; por eso login es la vía recomendada en local.
• Un 401 del backend indica el motivo (code): unknown_token (no existe o se copió incompleto), revoked_token, expired_token, malformed_token o unexpanded_placeholder. Salvo en el primer caso, cree un token nuevo. Un 403 indica que no pertenece al proyecto o no tiene rol de edición.
• El token está limitado a un proyecto y caduca a los 90 días.
• El MCP no sube código fuente. Sólo procesa el JSON de la guía que usted le proporciona.