orquestra-mcp 1.58.0 → 1.70.0

package/README.md

@@ -1,6 +1,6 @@
 # orquestra-mcp
 
-Servidor MCP (Model Context Protocol) para Orquestra. Expone **149 tools**
+Servidor MCP (Model Context Protocol) para Orquestra. Expone **161 tools**
 (conteo al 24 oct 2026, v1.49.0; la lista real está en `src/server.mjs`)
 que llaman a la API de `orquestra-infra`: lectura de contexto/dashboard/
 workspace/infra/paridad/listados, escritura de tareas/ideas/changelog/
@@ -42,6 +42,14 @@ de su caché.
 publicada. Con `@latest` cada arranque la usa; el servidor que ya está corriendo conserva
 la suya hasta que reconectas (en Claude Code: `/mcp` → reconectar).
 
+**Forzar la actualización:** reinicia la sesión (o `/mcp` → reconectar) y, si sigue la
+versión vieja, `npx clear-npx-cache`. Si registraste el MCP como `orquestra-mcp` sin
+`@latest`, migra con un comando:
+`claude mcp remove orquestra && claude mcp add orquestra -e ORQUESTRA_AGENT=claude-code -- npx -y orquestra-mcp@latest`.
+`diagnostico_conexion` (cuando no hay conexión) muestra la versión en uso frente a la
+última publicada y detecta configs sin `@latest`; con conexión, `get_project_context`
+trae `orquestraMcpUpdate` si hay versión nueva.
+
 Variable opcional `ORQUESTRA_WEB_URL` para apuntar el login a otro lugar
 (ej. `http://localhost:5173` mientras desarrollas `orquestra-web` local en
 vez de contra producción).
@@ -133,6 +141,17 @@ claude mcp add orquestra \
   -- npx -y orquestra-mcp@latest
 ```
 
+## Novedades 1.66.0 (ORQ-532..535)
+
+- `close_task({id, comment, completeChecklist?, waiveVerifications?})`: cierra una tarea desde cualquier estatus
+  recorriendo el flujo (camino más corto por `nextIds` hasta el final, pasando por "En revisión"); un solo
+  `comment` (en el último paso). Respeta las guardas de checklist/verificaciones.
+- `get_tool_guide({topic})`: reglas completas de `update_task`, `create_task`, `update_tasks`, `close_task` y
+  `related_impact`; las descripciones de esas tools son cortas a propósito (test de tope en `test/mejorasMcp.test.mjs`).
+- `update_tasks` acepta `compact:true` (recomendado): cada resultado trae solo `{ index, id, ok, status, shortCode, statusId, relatedImpact?, unresolvedLinks?, error? }`.
+- `create_task` acepta `checklist: [{text, done?, assignedTo?}]` y responde `checklistCount` (y `checklistFailed` si algún ítem falló).
+- `search` documenta `statusId`/`tags` en los resultados (requiere la API con ORQ-536).
+
 ## Tools
 
 Lectura de contexto:
@@ -140,7 +159,9 @@ Lectura de contexto:
 | Tool | Args | Descripción |
 |---|---|---|
 | `get_project_context` | `projectId?` | Snapshot compacto del proyecto (fase, tareas abiertas/vencidas/bloqueadas, módulos, ideas, changelog reciente) |
-| `list_tasks` | `projectId?`, `statusId?` | Lista de tareas, filtro opcional por estatus |
+| `list_tasks` | `projectId?`, `statusId?`, `summary?`, `fields?`, `limit?`, `cursor?` | Lista de tareas, filtro opcional por estatus; en proyectos grandes usa `summary`/`fields`/`limit` y pagina con `nextCursor` |
+| `get_task` | `code?` o `id?` | Una tarea completa (checklist y verificaciones) por folio o id; 404 si no existe, 409 si el código es ambiguo |
+| `update_tasks` | `items[]` (1-50), `opId?` | Edita varias tareas en una llamada; respuesta parcial por ítem |
 | `search` | `projectId?`, `q` | Búsqueda por texto en tareas/notas/ideas/docs |
 | `get_dashboard_summary` | `projectId?` | Hoy/vencidas/bloqueadas, salud de módulos, actividad reciente |
 | `get_project_findings` | `projectId?` | Qué le falta al proyecto, priorizado por severidad (determinístico, sin créditos de IA) |
@@ -166,7 +187,7 @@ parcial: la lista completa está en `src/server.mjs`:
 | Entidad | Tools | Notas |
 |---|---|---|
 | Tareas | `create_task`, `update_task` | `update_task` incluye `scope` — úsalo para resolver desfases de paridad |
-| Verificaciones por plataforma | `list_verifications`, `add_verification`, `update_verification`, `delete_verification`, `verify_with_agent` | Confirmaciones (humanas o de agente) de que la tarea quedó bien en web/iOS/Android/API — NO van en el checklist. La tarea no cierra con verificaciones abiertas y se cierra sola al aprobarse la última; `failed` (con `note`) la regresa a su estatus anterior. También: `verifications` en `create_task`, `waiveVerifications` en `update_task` (solo con confirmación del usuario) y `verificationId` en `create_agent_run` |
+| Verificaciones por plataforma | `list_verifications`, `add_verification`, `add_verifications` (lote), `update_verification`, `delete_verification`, `verify_with_agent` | Confirmaciones (humanas o de agente) de que la tarea quedó bien en web/iOS/Android/API — NO van en el checklist. La tarea no cierra con verificaciones abiertas y se cierra sola al aprobarse la última; `failed` (con `note`) la regresa a su estatus anterior. También: `verifications` en `create_task`, `waiveVerifications` en `update_task` (solo con confirmación del usuario) y `verificationId` en `create_agent_run` |
 | Ideas | `list_ideas`, `create_idea`, `update_idea` | |
 | Changelog | `list_changelog`, `create_changelog_entry`, `update_changelog_entry` | Estilo Keep a Changelog |
 | Notas | `list_notes`, `create_note`, `update_note` | |
@@ -229,7 +250,7 @@ create/update sigue siendo criterio del agente y del humano.
 
 ## Estado
 
-149 tools (ver arriba): lectura (contexto, dashboard, workspace, infra, paridad, standup,
+161 tools (ver arriba): lectura (contexto, dashboard, workspace, infra, paridad, standup,
 sync report, setup guide, playbooks de etapa y de plataforma, catálogo de
 skills, search) + `list_*` de cada colección + creación/edición de tareas
 (con checklist, verificaciones por plataforma, tiempo, adjuntos, merge), ideas (con comentarios), notas,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.58.0",
-  "description": "Servidor MCP de Orquestra -- 135 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
+  "version": "1.70.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": {
     "orquestra-mcp": "bin/orquestra-mcp.mjs"

package/src/api.mjs

@@ -68,19 +68,24 @@ function buildUrl(config, path, params) {
 // Todas pasan por request() (http.mjs, ORQ-343): plazo por intento, cancelación de la tool y
 // reintentos acotados -- las lecturas ante fallas transitorias, las escrituras solo ante el
 // throttling del API Gateway (no llegó a la Lambda, no puede duplicar nada).
-const auth = config => ({ Authorization: `Bearer ${config.apiToken}` })
+// x-orquestra-client: la API lo lee para el origen de la bitácora de acceso (ORQ-480).
+const auth = config => ({ Authorization: `Bearer ${config.apiToken}`, 'x-orquestra-client': 'mcp' })
 const jsonHeaders = config => ({ ...auth(config), 'Content-Type': 'application/json' })
 
 export async function apiGet(config, path, params = {}) {
   return request(buildUrl(config, path, params), { headers: auth(config) })
 }
 
-export async function apiPost(config, path, { projectId, ...body }) {
-  return request(buildUrl(config, path, { projectId }), { method: 'POST', headers: jsonHeaders(config), body: JSON.stringify(body) })
+export async function apiPost(config, path, { projectId, ...body }, query = {}) {
+  return request(buildUrl(config, path, { projectId, ...query }), { method: 'POST', headers: jsonHeaders(config), body: JSON.stringify(body) })
 }
 
-export async function apiPatch(config, path, { projectId, id, ...body }) {
-  return request(buildUrl(config, `${path}/${id}`, { projectId }), { method: 'PATCH', headers: jsonHeaders(config), body: JSON.stringify(body) })
+export async function apiPut(config, path, { projectId, ...body }, query = {}) {
+  return request(buildUrl(config, path, { projectId, ...query }), { method: 'PUT', headers: jsonHeaders(config), body: JSON.stringify(body) })
+}
+
+export async function apiPatch(config, path, { projectId, id, ...body }, query = {}) {
+  return request(buildUrl(config, `${path}/${id}`, { projectId, ...query }), { method: 'PATCH', headers: jsonHeaders(config), body: JSON.stringify(body) })
 }
 
 // Mismo método que apiPatch, pero para un doc singleton SIN id en la ruta
@@ -94,14 +99,14 @@ export async function apiPatchPath(config, path, { projectId, ...body }) {
 // -- ver CLAUDE.md, "único delete_* real de la API/MCP"). Mismo shape que
 // apiPatch (arma la URL como `${path}/${id}`), sin body -- ningún delete de
 // esta API necesita mandar datos, solo identificar el recurso.
-export async function apiDelete(config, path, { projectId, id }) {
-  return request(buildUrl(config, `${path}/${id}`, { projectId }), { method: 'DELETE', headers: auth(config) })
+export async function apiDelete(config, path, { projectId, id }, query = {}) {
+  return request(buildUrl(config, `${path}/${id}`, { projectId, ...query }), { method: 'DELETE', headers: auth(config) })
 }
 
 // DELETE sobre un recurso singleton SIN id en la ruta (ej. /v1/client-portal,
 // ORQ-332) -- mismo criterio que apiPatchPath.
-export async function apiDeletePath(config, path, { projectId }) {
-  return request(buildUrl(config, path, { projectId }), { method: 'DELETE', headers: auth(config) })
+export async function apiDeletePath(config, path, { projectId, ...query }) {
+  return request(buildUrl(config, path, { projectId, ...query }), { method: 'DELETE', headers: auth(config) })
 }
 
 // PUT crudo a una presigned URL de S3 (createAttachmentUploadUrl en

package/src/closePath.mjs

@@ -0,0 +1,65 @@
+// ORQ-532: lógica pura de close_task. La API no recorre estatus sola (cada estatus solo permite pasar a su
+// `nextIds`), así que cerrar una tarea que está en Backlog/Bloqueado/etc. exige varios PATCH. Aquí se calcula
+// el camino más corto hacia el estatus de cierre normal (final, no cancelado ni archivo), sin tocar la red.
+
+const isClosed = s => !!(s && (s.isFinal || s.isCancel || s.isArchive))
+const isReview = s => /revisi[oó]n|review/i.test(s?.name || '')
+
+/** Normaliza la respuesta de GET /v1/statuses (arreglo directo o { items }). */
+export function normalizeStatuses(data) {
+  const list = Array.isArray(data) ? data : Array.isArray(data?.items) ? data.items : Array.isArray(data?.statuses) ? data.statuses : []
+  return list.filter(s => s && s.id)
+}
+
+/** Estatus de cierre normal: final y ni cancelado ni archivo. */
+export function closeTargets(statuses) {
+  return statuses.filter(s => s.isFinal && !s.isCancel && !s.isArchive)
+}
+
+/** BFS desde `fromId` por nextIds; no transita por estatus cerrados (final/cancelado/archivo) salvo como destino.
+ *  Devuelve el camino más corto como arreglo de estatus (sin incluir el origen) hacia `targetId`, o null. */
+function shortestPath(byId, fromId, targetId) {
+  const prev = new Map([[fromId, null]])
+  const queue = [fromId]
+  while (queue.length) {
+    const cur = queue.shift()
+    if (cur === targetId) break
+    for (const nid of byId.get(cur)?.nextIds || []) {
+      const next = byId.get(nid)
+      if (!next || prev.has(nid)) continue
+      if (isClosed(next) && nid !== targetId) continue
+      prev.set(nid, cur)
+      queue.push(nid)
+    }
+  }
+  if (!prev.has(targetId)) return null
+  const out = []
+  for (let id = targetId; id !== fromId; id = prev.get(id)) out.unshift(byId.get(id))
+  return out
+}
+
+/**
+ * @param {object[]} statuses estatuses del proyecto ({ id, name, order, nextIds, isFinal, isCancel, isArchive })
+ * @param {string} fromId estatus actual de la tarea
+ * @returns {{ alreadyClosed: true, current: object } | { path: object[], target: object } | { error: string }}
+ */
+export function findClosePath(statuses, fromId) {
+  const byId = new Map(statuses.map(s => [s.id, s]))
+  const current = byId.get(fromId)
+  if (!current) return { error: `El estatus actual de la tarea (${fromId}) no existe en el proyecto` }
+  if (isClosed(current)) return { alreadyClosed: true, current }
+  const targets = closeTargets(statuses)
+  if (!targets.length) return { error: 'El proyecto no tiene un estatus final (isFinal) al que cerrar' }
+  const candidates = targets
+    .map(t => ({ target: t, path: shortestPath(byId, fromId, t.id) }))
+    .filter(c => c.path)
+  if (!candidates.length) {
+    return { error: `No hay camino por nextIds desde "${current.name}" hasta un estatus final (${targets.map(t => `"${t.name}"`).join(', ')}). Revisa el flujo con list_statuses.` }
+  }
+  // Más corto; a igual largo, el que pasa por "En revisión" (flujo normal de cierre); luego el de menor order.
+  candidates.sort((a, b) =>
+    a.path.length - b.path.length
+    || Number(b.path.some(isReview)) - Number(a.path.some(isReview))
+    || (a.target.order ?? 0) - (b.target.order ?? 0))
+  return { path: candidates[0].path, target: candidates[0].target }
+}

package/src/platformPlaybooks.mjs

@@ -3,7 +3,7 @@
 // lo lee directo desde aca (mismo criterio que stages.mjs/foundations.mjs).
 // Puerto de TRACKING_TOOLS de la web: herramientas de medición conectables a una
 // distribución web. El ID vive en distributions.publishForm[key]. `pattern` valida
-// el formato (se serializa como string en la web, acá es el RegExp directo).
+// el formato (se serializa como string en la web, aquí es el RegExp directo).
 export const TRACKING_TOOLS = [
   { key: 'ga4_measurement_id', label: 'Google Analytics 4', idLabel: 'ID de medición', pattern: /^G-[A-Z0-9]{6,12}$/, example: 'G-ABC123DEF4', where: 'Google Analytics → Admin → Flujos de datos' },
   { key: 'meta_pixel_id',      label: 'Meta Pixel',         idLabel: 'ID del Pixel',    pattern: /^\d{8,20}$/,          example: '1234567890123456', where: 'Meta Business → Events Manager' },
@@ -312,7 +312,7 @@ export const PLATFORM_PLAYBOOKS = {
       {
         key: 'privacy_policy',
         title: 'Privacy policy URL',
-        body: 'Obligatoria para publicar -- Play Console valida que la URL responda 200 al guardarla, no solo que tenga formato de URL. Ojo con apps de una sola página (React Router y similares): si el hosting no tiene configurado el rewrite de SPA (servir index.html para cualquier ruta), una URL como /privacidad puede dar 404 real aunque el deploy haya salido bien -- probar la URL en el navegador ANTES de pegarla acá, no confiar en que "ya se desplegó" alcanza.',
+        body: 'Obligatoria para publicar -- Play Console valida que la URL responda 200 al guardarla, no solo que tenga formato de URL. Ojo con apps de una sola página (React Router y similares): si el hosting no tiene configurado el rewrite de SPA (servir index.html para cualquier ruta), una URL como /privacidad puede dar 404 real aunque el deploy haya salido bien -- probar la URL en el navegador ANTES de pegarla aquí, no confiar en que "ya se desplegó" alcanza.',
       },
       {
         key: 'ads_declaration',
@@ -332,7 +332,7 @@ export const PLATFORM_PLAYBOOKS = {
       {
         key: 'content_rating',
         title: 'Content rating questionnaire (IARC)',
-        body: 'Cuestionario largo, con sub-preguntas que se despliegan según tus respuestas. Puntos donde el criterio NO es obvio: "User Content Sharing" (¿la app permite nativamente intercambiar texto/voz/imágenes/audio entre usuarios?) es MÁS AMPLIO que el "User-Generated Content" de Apple -- Apple exime contenido privado dentro de un equipo, Google NO tiene esa excepción, así que comentarios/notas compartidas entre miembros de un workspace SÍ cuentan como "Yes" acá aunque sean privados. Si contestas "Yes" ahí, "¿las interacciones pueden limitarse a usuarios invitados?" responde "Yes" si el acceso es por invitación (esto ayuda a mantener la clasificación baja). El resto (violencia, sexual, lenguaje, drogas, apuestas) va en "No"/"None" para una app B2B típica -- resultado esperado: la clasificación más baja (3+/PEGI 3/Everyone).',
+        body: 'Cuestionario largo, con sub-preguntas que se despliegan según tus respuestas. Puntos donde el criterio NO es obvio: "User Content Sharing" (¿la app permite nativamente intercambiar texto/voz/imágenes/audio entre usuarios?) es MÁS AMPLIO que el "User-Generated Content" de Apple -- Apple exime contenido privado dentro de un equipo, Google NO tiene esa excepción, así que comentarios/notas compartidas entre miembros de un workspace SÍ cuentan como "Yes" aquí aunque sean privados. Si contestas "Yes" ahí, "¿las interacciones pueden limitarse a usuarios invitados?" responde "Yes" si el acceso es por invitación (esto ayuda a mantener la clasificación baja). El resto (violencia, sexual, lenguaje, drogas, apuestas) va en "No"/"None" para una app B2B típica -- resultado esperado: la clasificación más baja (3+/PEGI 3/Everyone).',
       },
       {
         key: 'target_audience',