orquestra-mcp 1.70.0 → 1.72.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.70.0",
+  "version": "1.72.0",
   "description": "Servidor MCP de Orquestra -- 161 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {

package/src/server.mjs

@@ -2961,15 +2961,16 @@ export function createServer() {
   server.registerTool(
     'upsert_design_tokens',
     {
-      description: `Carga en lote (hasta 100) tokens de identidad de diseño: es el camino para poblar o sincronizar la identidad visual de una vez. ${DESIGN_TOKEN_PURPOSE} Cada token se identifica por (name, kind, platform): si existe se actualiza, si no se crea; nada se borra. Se valida todo antes de escribir (un token inválido o repetido en el lote rechaza el lote entero). Devuelve { created, updated, items }.`,
+      description: `Carga en lote (hasta 100) tokens de identidad de diseño: es el camino para poblar o sincronizar la identidad visual de una vez. ${DESIGN_TOKEN_PURPOSE} Cada token se identifica por (name, kind, platform): si existe se actualiza, si no se crea; nada se borra. Se valida todo antes de escribir (un token inválido o repetido en el lote rechaza el lote entero). Devuelve { created, updated, items }; por defecto compact=true y items trae solo {id,name,key?,platform?,action}, con compact=false devuelve las filas completas.`,
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        compact: z.boolean().optional().describe('true (default) = el lote devuelve items resumidos {id,name,key?,platform?,action}; false = filas completas'),
         tokens: z.array(z.object(designTokenFields(false))).min(1).max(100).describe('Tokens a crear/actualizar (1-100)'),
       },
     },
-    async ({ projectId, tokens }) => {
+    async ({ projectId, tokens, compact }) => {
       try {
-        return textResult(await apiPost(config, '/v1/design-tokens/bulk', { projectId: resolveProjectId(projectId), tokens }))
+        return textResult(await apiPost(config, '/v1/design-tokens/bulk', { projectId: resolveProjectId(projectId), tokens, compact: compact ?? true }))
       } catch (err) {
         return errorResult(err)
       }
@@ -2985,6 +2986,24 @@ export function createServer() {
     name: z.string().describe('Nombre del bloque, ej: "Encabezado", "Lista de tareas"'),
     description: z.string().optional().describe('Qué contiene o hace'),
   })).describe('Bloques de la pantalla de arriba a abajo, ej: [{"name":"Encabezado","description":"Título y filtros"},{"name":"Lista de tareas"}]')
+  const navItemKey = z.string().min(1).max(60).regex(/^[a-z0-9.-]+$/, 'key en minúsculas, dígitos, punto o guion').describe('minúsculas, dígitos, punto o guion (≤60), única en el nodo')
+  const uniqueKeys = (arr, ctx) => {
+    const seen = new Set()
+    arr.forEach((it, i) => {
+      if (seen.has(it.key)) ctx.addIssue({ code: 'custom', path: [i, 'key'], message: `key repetida en el nodo: ${it.key}` })
+      seen.add(it.key)
+    })
+  }
+  const navActionsSchema = z.array(z.object({
+    key: navItemKey.describe('Key de la acción, convención entidad.verbo, ej: "task.create", "task.assign"; minúsculas, dígitos, punto o guion (≤60), única en el nodo'),
+    name: z.string().min(1).max(120).describe('Nombre visible de la acción, ej: "Crear tarea" (≤120)'),
+    description: z.string().optional().describe('Qué hace'),
+    roles: z.array(z.string()).optional().describe('Roles que pueden ejecutarla, ej: ["owner","admin"]'),
+  })).max(60).superRefine(uniqueKeys).describe('Acciones que el usuario puede hacer en el nodo (hasta 60). Convención entidad.verbo (task.create); la misma acción lleva la MISMA key en web, iOS y Android: eso permite compararlas en get_design_parity.')
+  const navStatesSchema = z.array(z.object({
+    key: navItemKey.describe('Key del estado; recomendados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty'),
+    note: z.string().optional().describe('Cómo se ve o se comporta en ese estado'),
+  })).max(20).superRefine(uniqueKeys).describe('Estados de la pantalla (hasta 20). Recomendados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty. Misma key en las tres plataformas.')
   const navNodeFields = optional => {
     const f = {
       name: z.string().describe('Nombre visible del nodo, ej: "Tareas"'),
@@ -2998,6 +3017,8 @@ export function createServer() {
       order: z.number().optional().describe('Orden entre hermanos'),
       description: z.string().optional().describe('Qué hace o muestra'),
       blocks: navBlocksSchema.optional(),
+      actions: navActionsSchema.optional(),
+      states: navStatesSchema.optional(),
       sourceRef: z.string().optional().describe('Dónde vive en el código, ej: archivo y símbolo'),
     }
     if (optional) { f.name = f.name.optional(); f.platform = f.platform.optional(); f.kind = f.kind.optional() }
@@ -3027,10 +3048,10 @@ export function createServer() {
     }
   )
   registerCreate('create_design_nav_node', '/v1/design-nav',
-    `Crea un nodo de navegación de diseño. ${NAV_PURPOSE} Para cargar muchos de una vez usa upsert_design_nav, no esta tool en bucle.`,
+    `Crea un nodo de navegación de diseño. ${NAV_PURPOSE} Para cargar muchos de una vez usa upsert_design_nav, no esta tool en bucle. Cada nodo acepta "actions" (convención entidad.verbo, ej. task.create; la misma acción lleva la MISMA key en web, iOS y Android) y "states" (recomendados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty). La matriz de paridad compara primero por capacidades (acciones y estados) y cae a bloques si la referencia no las define.`,
     navNodeFields(false))
   registerUpdate('update_design_nav_node', '/v1/design-nav',
-    `Edita un nodo de navegación de diseño existente (parche parcial: manda solo lo que cambia; parentId puede mover el nodo o ponerlo en null para dejarlo en la raíz). ${NAV_PURPOSE}`,
+    `Edita un nodo de navegación de diseño existente (parche parcial: manda solo lo que cambia; parentId puede mover el nodo o ponerlo en null para dejarlo en la raíz). Ojo: "actions" y "states" REEMPLAZAN el array completo del nodo (manda la lista final; para mezclar por key usa upsert_design_nav). Convención de actions: entidad.verbo (task.create), misma key en web, iOS y Android; states recomendados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty. La matriz de paridad compara primero por capacidades (acciones y estados) y cae a bloques si la referencia no las define. ${NAV_PURPOSE}`,
     navNodeFields(true))
 
   server.registerTool(
@@ -3075,18 +3096,19 @@ export function createServer() {
   server.registerTool(
     'upsert_design_nav',
     {
-      description: `Carga en lote (hasta 300 nodos) la navegación de diseño: es el camino para cargar el árbol completo de una plataforma leyendo su código (rutas del router, tab bar, sidebar, pantallas y sus bloques). ${NAV_PURPOSE} En vez de parentId cada nodo lleva parentKey (la key del padre, que puede venir en el mismo lote; sin parentKey = raíz). Un nodo existente se identifica por (platform, key) o, si no hay key, por (platform, parentId, name): se actualiza, si no se crea; nada se borra. Ejemplo: [{"platform":"web","kind":"section","name":"Ajustes","key":"settings","route":"/settings"},{"platform":"web","kind":"screen","name":"General","key":"settings.general","parentKey":"settings","route":"/settings/general","blocks":[{"name":"Datos del workspace","description":"Nombre y logo"},{"name":"Zona de peligro"}],"sourceRef":"src/pages/Settings/General.jsx"}]. Usa la misma key para la misma pantalla en web, iOS y Android. Devuelve { created, updated, items }.`,
+      description: `Carga en lote (hasta 300 nodos) la navegación de diseño: es el camino para cargar el árbol completo de una plataforma leyendo su código (rutas del router, tab bar, sidebar, pantallas y sus bloques). ${NAV_PURPOSE} En vez de parentId cada nodo lleva parentKey (la key del padre, que puede venir en el mismo lote; sin parentKey = raíz). Un nodo existente se identifica por (platform, key) o, si no hay key, por (platform, parentId, name): se actualiza, si no se crea; nada se borra. "actions" (convención entidad.verbo, ej. task.create; la misma acción = la MISMA key en web, iOS y Android, es lo que permite compararlas) y "states" (recomendados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty) se MEZCLAN por key al actualizar un nodo existente (update_design_nav_node reemplaza el array completo). La paridad compara por capacidades y cae a bloques si la referencia no las define. Ejemplo: [{"platform":"web","kind":"section","name":"Ajustes","key":"settings","route":"/settings"},{"platform":"web","kind":"screen","name":"General","key":"settings.general","parentKey":"settings","route":"/settings/general","blocks":[{"name":"Datos del workspace","description":"Nombre y logo"},{"name":"Zona de peligro"}],"actions":[{"key":"workspace.rename","name":"Renombrar workspace","roles":["owner"]}],"states":[{"key":"loading"},{"key":"readonly"}]}]. Usa la misma key para la misma pantalla en web, iOS y Android. Devuelve { created, updated, items }; por defecto compact=true y items trae solo {id,name,key?,platform?,action}, con compact=false devuelve las filas completas.`,
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        compact: z.boolean().optional().describe('true (default) = el lote devuelve items resumidos {id,name,key?,platform?,action}; false = filas completas'),
         nodes: z.array(z.object({
           ...navBulkBase,
           parentKey: z.string().optional().describe('Key del nodo padre (en este lote o ya existente); ausente = raíz'),
         })).min(1).max(300).describe('Nodos a crear/actualizar (1-300)'),
       },
     },
-    async ({ projectId, nodes }) => {
+    async ({ projectId, nodes, compact }) => {
       try {
-        return textResult(await apiPost(config, '/v1/design-nav/bulk', { projectId: resolveProjectId(projectId), nodes }))
+        return textResult(await apiPost(config, '/v1/design-nav/bulk', { projectId: resolveProjectId(projectId), nodes, compact: compact ?? true }))
       } catch (err) {
         return errorResult(err)
       }
@@ -3158,15 +3180,16 @@ export function createServer() {
   server.registerTool(
     'upsert_design_components',
     {
-      description: `Carga en lote (hasta 200) componentes de diseño: es el camino para catalogar los componentes reales leyendo el código de cada plataforma (web, iOS y Android) y llenar platforms[].sourceRef con el archivo y símbolo de cada una. ${COMP_PURPOSE} Cada componente se identifica por name (sin distinguir mayúsculas): si existe se actualiza, si no se crea; nada se borra. Usa el mismo name para el mismo componente en las tres plataformas. Devuelve { created, updated, items }.`,
+      description: `Carga en lote (hasta 200) componentes de diseño: es el camino para catalogar los componentes reales leyendo el código de cada plataforma (web, iOS y Android) y llenar platforms[].sourceRef con el archivo y símbolo de cada una. ${COMP_PURPOSE} Cada componente se identifica por name (sin distinguir mayúsculas): si existe se crea o se MEZCLA, nada se borra. Cargar el MISMO name desde otra plataforma mezcla en vez de reemplazar: platforms se fusiona por plataforma, tokens/usedIn/states se unen y variants se combinan por nombre; para reemplazar de verdad usa update_design_component. Usa el mismo name para el mismo componente en las tres plataformas. Devuelve { created, updated, items, warnings }: warnings ([{name,field,value}], siempre presente) avisa de tokens o usedIn que no existen, corrígelos. Por defecto compact=true y items trae solo {id,name,key?,platform?,action}; con compact=false devuelve las filas completas.`,
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        compact: z.boolean().optional().describe('true (default) = el lote devuelve items resumidos {id,name,key?,platform?,action}; false = filas completas'),
         components: z.array(z.object(designComponentFields(false))).min(1).max(200).describe('Componentes a crear/actualizar (1-200)'),
       },
     },
-    async ({ projectId, components }) => {
+    async ({ projectId, components, compact }) => {
       try {
-        return textResult(await apiPost(config, '/v1/design-components/bulk', { projectId: resolveProjectId(projectId), components }))
+        return textResult(await apiPost(config, '/v1/design-components/bulk', { projectId: resolveProjectId(projectId), components, compact: compact ?? true }))
       } catch (err) {
         return errorResult(err)
       }
@@ -3178,17 +3201,18 @@ export function createServer() {
   server.registerTool(
     'get_design_parity',
     {
-      description: 'Matriz de paridad de diseño del proyecto: una fila por pantalla/componente (key, name, kind, route) y, por plataforma (web, ios, android), una celda con status (same | different | missing | not_applicable), source (auto | manual), nodeId, path, note, taskId y diff. Devuelve además summary (conteos por plataforma y total) y gaps (los huecos: [{key,name,platform,status}]). `ref` es la plataforma de referencia (default web). "distinto" (different) sale de comparar kind y bloques del nodo contra la plataforma de referencia; "falta" (missing) de que no exista un nodo con esa key en esa plataforma. Flujo para cerrar huecos: cada hueco (different | missing) puede convertirse en una tarea hermana con create_task (scope de esa plataforma y parityOf cuando aplique) y luego enlazarse a su celda con set_design_parity_cell(taskId=folio). Si una celda automática es incorrecta (ej. no aplica), fíjala a mano con set_design_parity_cell. Con soloHuecos:true devuelve solo { summary, gaps } para ahorrar tokens.',
+      description: 'Matriz de paridad de diseño del proyecto: una fila por pantalla/componente (key, name, kind, route) y, por plataforma (web, ios, android), una celda con status (same | different | missing | not_applicable), source (auto | manual), nodeId, path, note, taskId y diff. Cuando hay diff, cada celda suma además: basis ("capabilities" si se comparó por acciones y estados, "blocks" si la referencia no los define y se cayó a bloques), coverage, actionsMissing (acciones de la referencia que faltan aquí), actionsOnlyHere, statesMissing y statesOnlyHere; la raíz suma capabilitiesNodes. Devuelve además summary (conteos por plataforma y total) y gaps (los huecos: [{key,name,platform,status}]). `ref` es la plataforma de referencia (default web). "distinto" (different) sale de comparar kind y bloques del nodo contra la plataforma de referencia; "falta" (missing) de que no exista un nodo con esa key en esa plataforma. Flujo para cerrar huecos: cada hueco (different | missing) puede convertirse en una tarea hermana con create_task (scope de esa plataforma y parityOf cuando aplique) y luego enlazarse a su celda con set_design_parity_cell(taskId=folio). Si una celda automática es incorrecta (ej. no aplica), fíjala a mano con set_design_parity_cell. "Igual" (same) significa mismo tipo (kind) y similitud de bloques >= threshold (0..1, default 0.6); cada diff trae su similarity y la respuesta el threshold usado: sube el umbral para ser más estricto, bájalo para tolerar diferencias. Con soloHuecos:true devuelve solo { summary, gaps, threshold } para ahorrar tokens.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         ref: z.enum(PARITY_PLATFORMS).optional().describe('Plataforma de referencia: web | ios | android (default web)'),
-        soloHuecos: z.boolean().optional().describe('true = devuelve solo summary y gaps (sin las filas), para ahorrar tokens'),
+        soloHuecos: z.boolean().optional().describe('true = devuelve solo summary, gaps y threshold (sin las filas), para ahorrar tokens'),
+        threshold: z.number().min(0).max(1).optional().describe('Umbral de similitud de bloques (0..1, default 0.6) para considerar "same"'),
       },
     },
-    async ({ projectId, ref, soloHuecos }) => {
+    async ({ projectId, ref, soloHuecos, threshold }) => {
       try {
-        const data = await apiGet(config, '/v1/design-parity', { projectId: resolveProjectId(projectId), ref })
-        if (soloHuecos && data && typeof data === 'object') return textResult({ summary: data.summary, gaps: data.gaps })
+        const data = await apiGet(config, '/v1/design-parity', { projectId: resolveProjectId(projectId), ref, threshold })
+        if (soloHuecos && data && typeof data === 'object') return textResult({ summary: data.summary, gaps: data.gaps, threshold: data.threshold })
         return textResult(data)
       } catch (err) {
         return errorResult(err)