orquestra-mcp 1.70.0 → 1.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.70.0",
+  "version": "1.74.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/api.mjs

@@ -115,9 +115,9 @@ export async function apiDeletePath(config, path, { projectId, ...query }) {
 // es la autorización completa. Plazo más largo (sube bytes); un PUT a la
 // misma key es idempotente, pero igual no se reintenta para no duplicar
 // tiempos largos de subida.
-export async function putToPresignedUrl(uploadUrl, buffer, contentType) {
+export async function putToPresignedUrl(uploadUrl, buffer, contentType, headers) {
   try {
-    await request(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: buffer }, { timeoutMs: 120_000, retries: 0 })
+    await request(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType, ...(headers || {}) }, body: buffer }, { timeoutMs: 120_000, retries: 0 })
   } catch (err) {
     throw new Error(`Falló la subida a S3: ${err.status ? `HTTP ${err.status}` : err.message}`)
   }

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,16 @@ 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(),
+      screenshots: z.array(z.object({
+        key: z.string().describe('Key de S3 (de add_design_screenshot)'),
+        caption: z.string().max(200).optional(),
+        state: z.string().optional().describe('Estado que muestra'),
+        width: z.number().int().positive().optional(),
+        height: z.number().int().positive().optional(),
+        takenAt: z.number().optional().describe('ms epoch'),
+      })).max(12).optional().describe('Capturas (máx. 12); usa add_design_screenshot. PATCH reemplaza la lista'),
       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 +3056,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(
@@ -3071,22 +3100,93 @@ export function createServer() {
     }
   )
 
-  const { parentId: _navParentId, ...navBulkBase } = navNodeFields(false)
+  const { parentId: _navParentId, screenshots: _navShots, ...navBulkBase } = navNodeFields(false) // capturas: solo con add/remove_design_screenshot
   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)
+      }
+    }
+  )
+
+  // ═══ CAPTURAS POR PANTALLA (ORQ-573) ═══════════════════════════════════════
+  const SHOT_MIME_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' }
+  const SHOT_MAX_BYTES = 5 * 1024 * 1024
+  const SHOT_NOTE = 'Las capturas son INTERNAS del equipo (se guardan en un bucket privado y se ven con URL firmada de 1 h). No uses capturas del workspace real si van a usarse en marketing o videos: arma un usuario demo.'
+  const findNavNode = async (pid, platform, key) => {
+    const list = await apiGet(config, '/v1/design-nav', { projectId: pid, platform })
+    const node = (list.items || []).find(n => n.key === key)
+    if (!node) throw new Error(`No hay un nodo con key "${key}" en ${platform}; revisa list_design_nav o créalo con upsert_design_nav`)
+    return node
+  }
+  server.registerTool(
+    'add_design_screenshot',
+    {
+      description: `Sube una captura de pantalla (imagen local png/jpg/webp, máx. 5 MB) y la agrega al nodo de navegación de diseño (platform + key) para ver cómo se ve esa pantalla en cada plataforma y compararlas lado a lado. Valida extensión y tamaño ANTES de subir, pide la URL firmada, hace el PUT a S3 y guarda la clave en el nodo MEZCLANDO por key (no pisa las otras capturas; máx. 12 por nodo). "state" marca qué estado muestra (empty, loading, error...). ${SHOT_NOTE} Devuelve { key, name, screenshots }.`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(NAV_PLATFORMS).describe('Plataforma del nodo: web | ios | android'),
+        key: z.string().describe('Key del nodo de navegación (ej: "tasks", "settings.general")'),
+        filePath: z.string().describe('Ruta local a la imagen (png/jpg/jpeg/webp, máx. 5 MB)'),
+        caption: z.string().max(200).optional().describe('Pie de la captura (máx. 200)'),
+        state: z.string().optional().describe('Estado que muestra, ej: empty, loading, error'),
+      },
+    },
+    async ({ projectId, platform, key, filePath, caption, state }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const ext = path.extname(filePath).slice(1).toLowerCase()
+        const mime = SHOT_MIME_BY_EXT[ext]
+        if (!mime) throw new Error('Solo imágenes png, jpg/jpeg o webp')
+        const stat = statSync(filePath)
+        if (!stat.isFile()) throw new Error('filePath no es un archivo')
+        if (stat.size > SHOT_MAX_BYTES) throw new Error(`La imagen pesa ${(stat.size / 1048576).toFixed(1)} MB; el máximo es 5 MB`)
+        const node = await findNavNode(pid, platform, key)
+        const name = path.basename(filePath)
+        const { uploadUrl, key: shotKey, headers } = await apiPost(config, '/v1/design-assets/presign', { projectId: pid, nodeId: node.id, filename: name, contentType: mime, size: stat.size })
+        await putToPresignedUrl(uploadUrl, readFileSync(filePath), mime, headers)
+        const shot = { key: shotKey, takenAt: Date.now(), ...(caption ? { caption } : {}), ...(state ? { state } : {}) }
+        const res = await apiPost(config, '/v1/design-nav/bulk', { projectId: pid, compact: false, nodes: [{ platform, kind: node.kind, name: node.name, key, screenshots: [shot] }] })
+        const updated = res.items?.[0]
+        return textResult({ key: shotKey, name, nodeId: node.id, screenshots: updated?.screenshots ?? [shot] })
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+  server.registerTool(
+    'remove_design_screenshot',
+    {
+      description: `Quita una captura de un nodo de navegación de diseño (platform + key del nodo + screenshotKey de la captura, la que devolvió add_design_screenshot o list_design_nav). La API también intenta borrar el archivo de S3. ${SHOT_NOTE}`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(NAV_PLATFORMS).describe('Plataforma del nodo: web | ios | android'),
+        key: z.string().describe('Key del nodo de navegación'),
+        screenshotKey: z.string().describe('Key de S3 de la captura a quitar'),
+      },
+    },
+    async ({ projectId, platform, key, screenshotKey }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const node = await findNavNode(pid, platform, key)
+        const current = node.screenshots || []
+        if (!current.some(s => s.key === screenshotKey)) throw new Error(`El nodo "${key}" no tiene una captura con key "${screenshotKey}"`)
+        const data = await apiPatch(config, '/v1/design-nav', { projectId: pid, id: node.id, screenshots: current.filter(s => s.key !== screenshotKey) })
+        return textResult({ removed: screenshotKey, nodeId: node.id, screenshots: data.screenshots ?? [] })
       } catch (err) {
         return errorResult(err)
       }
@@ -3158,15 +3258,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 +3279,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)
@@ -3199,7 +3301,7 @@ export function createServer() {
   server.registerTool(
     'set_design_parity_cell',
     {
-      description: 'Fija a mano una celda de la matriz de paridad de diseño (get_design_parity): el override manual gana sobre el cálculo automático. Úsala para marcar not_applicable (la pantalla no existe en esa plataforma a propósito), corregir un estado, dejar una nota o enlazar la tarea hermana que cierra el hueco (taskId = folio, ej. ORQ-123). Con status:null quita el override y la celda vuelve al cálculo automático.',
+      description: 'Fija a mano una celda de la matriz de paridad de diseño (get_design_parity): el override manual gana sobre el cálculo automático. Úsala para marcar not_applicable (la pantalla no existe en esa plataforma a propósito), corregir un estado, dejar una nota o enlazar la tarea hermana que cierra el hueco (taskId = folio, ej. ORQ-123). Con status:null y SIN note ni taskId quita el override y la celda vuelve al cálculo automático; con status:null y note o taskId conserva la nota y el folio sin fijar estado manual (la celda sigue automática). Regla: fijar status:"not_applicable" EXIGE un `reason` (motivo) no vacío; para los demás estados es opcional. `adr` enlaza la celda a un doc del proyecto (normalmente un ADR que documenta la decisión): pásale el id del doc (obtenlo con search types=["doc"] o listando los docs); "" lo quita. get_design_parity devuelve en la celda reason y decision {docId,title,type}.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         key: z.string().min(1).describe('Key de la fila (ver get_design_parity)'),
@@ -3207,11 +3309,142 @@ export function createServer() {
         status: z.enum(['same', 'different', 'missing', 'not_applicable']).nullable().describe('Estado manual; null = quitar el override'),
         note: z.string().optional().describe('Nota de la celda'),
         taskId: z.string().optional().describe('Folio de la tarea que cierra el hueco, ej: ORQ-123'),
+        reason: z.string().max(500).optional().describe('Motivo de la decisión (máx. 500). Obligatorio al fijar status not_applicable'),
+        adr: z.string().max(60).optional().describe('Id del doc (ADR) que documenta la decisión; se envía como docId. "" lo quita'),
+      },
+    },
+    async ({ projectId, key, platform, status, note, taskId, reason, adr }) => {
+      try {
+        if (status === 'not_applicable' && !(reason && reason.trim())) {
+          return errorResult(new Error('motivo obligatorio al fijar No aplica: pasa reason con el porqué (y opcionalmente adr con el id del doc)'))
+        }
+        return textResult(await apiPut(config, '/v1/design-parity/cell', { projectId: resolveProjectId(projectId), key, platform, status, note, taskId, reason, docId: adr }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'create_parity_tasks',
+    {
+      description: 'Convierte huecos de la paridad de diseño en tareas. Flujo: primero get_design_parity con soloHuecos:true para ver los huecos (gaps); luego create_parity_tasks con las celdas {key, platform} que quieras cerrar. Crea UNA tarea por celda, con scope de esa plataforma y el detalle de la diferencia contra la plataforma de referencia (ref, default web; threshold para el umbral de similitud). No duplica: si la celda ya tiene folio la omite (aparece en skipped con su reason) salvo force:true; el folio nuevo se guarda en la celda. La tarea exige módulo y fecha: si no pasas moduleId/dueDate se resuelven solos (módulo de la plataforma, hoy + 14 días); priority es opcional. Responde { created: [{key,platform,taskId,id}], skipped: [{key,platform,reason}], warnings }. No la uses para cientos de celdas a la vez: máximo 50 por llamada.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        cells: z.array(z.object({
+          key: z.string().min(1).describe('Key de la fila (ver get_design_parity)'),
+          platform: z.enum(PARITY_PLATFORMS).describe('Plataforma de la celda: web | ios | android'),
+        })).min(1).max(50).describe('Celdas a convertir en tarea (1 a 50)'),
+        ref: z.enum(PARITY_PLATFORMS).optional().describe('Plataforma de referencia: web | ios | android (default web)'),
+        threshold: z.number().min(0).max(1).optional().describe('Umbral de similitud de bloques (0..1, default 0.6)'),
+        moduleId: z.string().optional().describe('Módulo de las tareas; si falta se usa el de la plataforma'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato YYYY-MM-DD').optional().describe('Fecha límite YYYY-MM-DD; si falta, hoy + 14 días'),
+        priority: z.enum(['high', 'medium', 'low']).optional().describe('Prioridad de las tareas'),
+        force: z.boolean().optional().describe('true = crea la tarea aunque la celda ya tenga folio'),
+      },
+    },
+    async ({ projectId, cells, ref, threshold, moduleId, dueDate, priority, force }) => {
+      try {
+        return textResult(await apiPost(config, '/v1/design-parity/tasks', { projectId: resolveProjectId(projectId), cells, ref, threshold, moduleId, dueDate, priority, force }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // ═══ DERIVA DE TOKENS (ORQ-574) ═══════════════════════════════════════════
+  const DRIFT_KINDS = ['color', 'radius', 'spacing', 'typography', 'shadow']
+  const DRIFT_STATUSES = ['open', 'ignored', 'fixed']
+  const DRIFT_FLOW = 'Detector de deriva de tokens: valores de diseño (colores hex, radios, spacings, fuentes, sombras) escritos a mano en el código de una plataforma FUERA de la definición de tokens. FLUJO: 1) list_design_tokens para conocer los tokens de la plataforma; 2) recorre el código de UNA plataforma (web, ios o android) buscando colores hex, radios, spacings y fuentes escritos a mano; 3) compara cada valor con los tokens de esa MISMA plataforma y, si coincide, propón suggestedToken con el name del token; 4) reporta en lote con report_design_drift (hasta 200 por llamada; guarda la hora de inicio de la pasada, Date.now()); 5) al terminar una pasada COMPLETA de esa plataforma, llama a resolve_missing_design_drift en dryRun (platform + reportedBefore = hora de inicio de la pasada) para ver qué hallazgos abiertos ya no aparecen y, si es correcto, repítela con dryRun:false (se marcan fixed). NO es deriva: el archivo donde se DEFINEN los tokens (theme, tokens.css, Colors.swift, Color.kt, variables.css...), tests y fixtures, previews/storybook/SwiftUI previews, código generado, node_modules/build, ni valores dinámicos (calculados por el usuario o datos).'
+  const driftItemSchema = z.object({
+    platform: z.enum(PARITY_PLATFORMS).describe('Plataforma donde está el código: web | ios | android'),
+    file: z.string().min(1).max(300).describe('Ruta RELATIVA al repo de la plataforma, ej: src/pages/Tasks.jsx'),
+    line: z.number().int().min(1).optional().describe('Línea (>= 1); parte de la identidad del hallazgo'),
+    kind: z.enum(DRIFT_KINDS).describe('color | radius | spacing | typography | shadow'),
+    value: z.string().min(1).max(120).describe('Valor escrito a mano tal cual, ej: "#2F7A55", "13dp", "12px"'),
+    context: z.string().max(200).optional().describe('Símbolo o línea de código donde aparece (≤200)'),
+    suggestedToken: z.string().max(80).optional().describe('name de un design token EXISTENTE de esa plataforma que lo reemplazaría (≤80); si no existe la API avisa en warnings'),
+    note: z.string().max(300).optional().describe('Nota (≤300), solo se guarda al crear'),
+    reopen: z.boolean().optional().describe('true = reabre este hallazgo si estaba ignored o fixed (por default un reporte repetido NO los reabre)'),
+  })
+
+  server.registerTool(
+    'report_design_drift',
+    {
+      description: `Reporta en lote (1 a 200) hallazgos de deriva de tokens. ${DRIFT_FLOW} Cada hallazgo se identifica por (platform, file, line, value): reportar de nuevo uno existente solo refresca seenAt, suggestedToken y context y NO reabre los ignorados o corregidos (salvo reopen:true). Responde { created, updated, reopened, items (resumidos por default), warnings } donde warnings avisa de suggestedToken que no existe en los tokens. Valida todo el lote antes de escribir.`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        compact: z.boolean().optional().describe('true (default) = items resumidos {id,platform,file,line?,value,status,action}; false = filas completas'),
+        items: z.array(driftItemSchema).min(1).max(200).describe('Hallazgos a reportar (1-200)'),
+      },
+    },
+    async ({ projectId, items, compact }) => {
+      try {
+        return textResult(await apiPost(config, '/v1/design-drift/bulk', { projectId: resolveProjectId(projectId), items, compact: compact ?? true }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'list_design_drift',
+    {
+      description: 'Lista los hallazgos de deriva de tokens (valores de diseño escritos a mano que deberían ser un token), ordenados por archivo y línea, con filtros por plataforma, tipo y estado. Responde { items, summary: { open, ignored, fixed, byPlatform: { web, ios, android } } }; el summary es de todo el proyecto, no depende de los filtros. Úsala para ver qué falta migrar a tokens, antes de reportar de nuevo (no repitas lo ya ignorado) o para armar tareas de limpieza. Se llena con report_design_drift; si viene vacía, nadie ha recorrido el código todavía.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(PARITY_PLATFORMS).optional().describe('Filtra por plataforma'),
+        kind: z.enum(DRIFT_KINDS).optional().describe('Filtra por tipo'),
+        status: z.enum(DRIFT_STATUSES).optional().describe('Filtra por estado: open | ignored | fixed'),
+      },
+    },
+    async ({ projectId, platform, kind, status }) => {
+      try {
+        return textResult(await apiGet(config, '/v1/design-drift', { projectId: resolveProjectId(projectId), platform, kind, status }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'update_design_drift',
+    {
+      description: 'Cambia el estado de un hallazgo de deriva (list_design_drift): ignored (es intencional o no aplica: un preview, un valor dinámico; ponle una nota con el motivo), fixed (ya se migró a un token) u open (reabrir). También puede ajustar la nota y el suggestedToken. Un hallazgo ignorado o corregido NO se reabre solo cuando se vuelve a reportar. Para marcar como corregidos los que ya no aparecen tras una pasada completa usa resolve_missing_design_drift, no esta tool en bucle.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        driftId: z.string().describe('ID del hallazgo (ver list_design_drift)'),
+        status: z.enum(DRIFT_STATUSES).optional().describe('open | ignored | fixed'),
+        note: z.string().max(300).optional().describe('Nota (≤300), ej. el motivo de ignorarlo'),
+        suggestedToken: z.string().max(80).optional().describe('name del token que lo reemplazaría (≤80)'),
+      },
+    },
+    async ({ projectId, driftId, status, note, suggestedToken }) => {
+      if (status === undefined && note === undefined && suggestedToken === undefined) {
+        return errorResult(new Error('Nada que actualizar: manda status, note o suggestedToken'))
+      }
+      try {
+        return textResult(await apiPatch(config, '/v1/design-drift', { projectId: resolveProjectId(projectId), id: driftId, status, note, suggestedToken }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'resolve_missing_design_drift',
+    {
+      description: 'Cierre de una pasada COMPLETA de deriva sobre una plataforma: marca como fixed los hallazgos OPEN de esa plataforma que no se vieron desde reportedBefore (porque la pasada ya no los encontró en el código). Úsala solo si recorriste TODA la plataforma; con una pasada parcial marcarías como corregido lo que simplemente no revisaste. reportedBefore = hora de inicio de la pasada en ms epoch (Date.now() guardado ANTES de empezar a reportar). dryRun es true por default: solo informa { dryRun, platform, reportedBefore, count, items } sin escribir; revisa la lista y repite con dryRun:false para aplicar. No toca los ignorados ni los ya corregidos.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(PARITY_PLATFORMS).describe('Plataforma de la pasada: web | ios | android'),
+        reportedBefore: z.number().int().positive().describe('ms epoch: se marcan los open con seenAt anterior a este valor'),
+        dryRun: z.boolean().optional().describe('true (default) = solo informa; false = marca fixed'),
       },
     },
-    async ({ projectId, key, platform, status, note, taskId }) => {
+    async ({ projectId, platform, reportedBefore, dryRun }) => {
       try {
-        return textResult(await apiPut(config, '/v1/design-parity/cell', { projectId: resolveProjectId(projectId), key, platform, status, note, taskId }))
+        return textResult(await apiPost(config, '/v1/design-drift/resolve-missing', { projectId: resolveProjectId(projectId), platform, reportedBefore, dryRun: dryRun ?? true }))
       } catch (err) {
         return errorResult(err)
       }