orquestra-mcp 1.23.1 → 1.26.0

package/README.md

@@ -1,6 +1,6 @@
 # orquestra-mcp
 
-Servidor MCP (Model Context Protocol) para Orquestra. Expone **99 tools**
+Servidor MCP (Model Context Protocol) para Orquestra. Expone **100 tools**
 que llaman a la API de `orquestra-infra`: lectura de contexto/dashboard/
 workspace/infra/paridad/listados, escritura de tareas/ideas/changelog/
 notas/docs/módulos/flujo/categorías/infra/proyectos, y corridas de QA —
@@ -111,6 +111,9 @@ Lectura de contexto:
 | `list_tasks` | `projectId?`, `statusId?` | Lista de tareas, filtro opcional por estatus |
 | `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) |
+| `ask_assistant` | `question`, `history?`, `projectId?` | Pregunta al Asistente sobre el proyecto; responde con propuestas (1 crédito de IA) |
+| `assess_project` | `projectId?` | Resumen y prioridades del proyecto con IA; se reusa 1 h si no cambian los hallazgos |
 | `get_infra_status` | `projectId?` | Servicios, entornos y distribuciones con conteos operational/degraded/down |
 | `get_parity_summary` | `projectId?` | Desfases de paridad multiplataforma (tasks y modules por separado) |
 | `get_workspace_summary` | — | Progreso agregado de todos los proyectos del workspace |
@@ -192,7 +195,7 @@ create/update sigue siendo criterio del agente y del humano.
 
 ## Estado
 
-99 tools: lectura (contexto, dashboard, workspace, infra, paridad, standup,
+100 tools: 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, tiempo, adjuntos, merge), ideas (con comentarios), notas,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.23.1",
-  "description": "Servidor MCP de Orquestra -- 89 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
+  "version": "1.26.0",
+  "description": "Servidor MCP de Orquestra -- 109 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

@@ -94,6 +94,19 @@ export async function apiPatch(config, path, { projectId, id, ...body }) {
   return parseResponse(res)
 }
 
+// Mismo método que apiPatch, pero para un doc singleton SIN id en la ruta
+// (ej. /v1/content-config) -- set_hourly_rate (8 oct 2026, ORQ-247) es el
+// primer caso real.
+export async function apiPatchPath(config, path, { projectId, ...body }) {
+  const url = buildUrl(config, path, { projectId })
+  const res = await fetch(url, {
+    method: 'PATCH',
+    headers: { Authorization: `Bearer ${config.apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  return parseResponse(res)
+}
+
 // Único método DELETE del cliente (21 ago 2026, para delete_checklist_item
 // -- 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

package/src/server.mjs

@@ -3,7 +3,7 @@ import path from 'node:path'
 import os from 'node:os'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
-import { loadConfig, apiGet, apiPost, apiPatch, apiDelete, putToPresignedUrl, ApiError } from './api.mjs'
+import { loadConfig, apiGet, apiPost, apiPatch, apiPatchPath, apiDelete, putToPresignedUrl, ApiError } from './api.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 import { PLATFORM_PLAYBOOKS, TRACKING_TOOLS } from './platformPlaybooks.mjs'
@@ -63,7 +63,7 @@ const SETUP_GUIDE = {
     { step: 3, section: 'Infraestructura', check: 'list_services / list_environments / list_distributions (o get_infra_status para los 3 juntos)', createOrUpdate: 'create_service|environment|distribution / update_*', matchBy: 'name (o type para servicios/distribuciones)' },
     { step: 4, section: 'Módulos', check: 'list_modules', createOrUpdate: 'create_module / update_module', matchBy: 'name', dependsOn: ['statusId (paso 1)', 'categoryId (paso 2)'] },
     { step: 5, section: 'Tareas', check: 'list_tasks', createOrUpdate: 'create_task / update_task', matchBy: 'title', dependsOn: ['statusId', 'categoryId', 'moduleId'] },
-    { step: 6, section: 'Ideas', check: 'search', createOrUpdate: 'create_idea / update_idea / convert_idea_to_task', matchBy: 'title' },
+    { step: 6, section: 'Ideas', check: 'list_ideas', createOrUpdate: 'create_idea / update_idea / convert_idea_to_task', matchBy: 'title' },
     { step: 7, section: 'Notas', check: 'list_notes', createOrUpdate: 'create_note / update_note', matchBy: 'title' },
     { step: 8, section: 'Changelog', check: 'list_changelog', createOrUpdate: 'create_changelog_entry / update_changelog_entry', matchBy: 'text' },
     { step: 9, section: 'Docs', check: 'search', createOrUpdate: 'create_doc (sin update_doc todavía)', matchBy: 'title' },
@@ -117,7 +117,7 @@ No le preguntes al usuario por workspaceId ni projectId -- ya están configurado
 
 No crees tareas ni entradas de changelog por preguntas triviales o exploración sin cambios reales -- solo por trabajo que de verdad avanza el proyecto.
 
-Si estás iniciando una sesión de trabajo real en un proyecto que YA tiene código (no un "vacío" recién conectado, ver arriba) y hace rato no se corrió este chequeo, o el usuario pide explícito "revisa fundamentos"/"qué le falta a este proyecto" (no lo hagas en cada mensaje ni en exploración sin cambios): llamá a get_foundations_checklist y, con acceso real al filesystem del repo (grep de dependencias, archivos de config, workflows de CI -- seguí el detectionHint de cada ítem), confirmá cuáles de verdad faltan -- filtrá por "scales" contra el scale real del proyecto (ver project.scale en get_project_context; un ítem con scales:["platform"] no aplica a una landing). Por cada uno que confirmes ausente con evidencia concreta, llamá a report_foundation_gap con esa evidencia específica -- nunca lo reportes solo porque el checklist lo menciona, sin haber revisado el código de verdad. No repitas un chequeo ya hecho recientemente en la misma sesión.
+Si estás iniciando una sesión de trabajo real en un proyecto que YA tiene código (no un "vacío" recién conectado, ver arriba) y hace rato no se corrió este chequeo, o el usuario pide explícito "revisa fundamentos"/"qué le falta a este proyecto" (no lo hagas en cada mensaje ni en exploración sin cambios): primero llamá a get_project_findings -- ya trae, calculado por el servidor y priorizado, lo que falta o está mal dentro de Orquestra (vencidas, bloqueadas, módulos en riesgo, paridad, infraestructura, servicios que faltan, duplicadas) -- y preséntaselo al usuario por severidad antes de seguir; luego, para lo que solo se ve en el código, llamá a get_foundations_checklist y, con acceso real al filesystem del repo (grep de dependencias, archivos de config, workflows de CI -- seguí el detectionHint de cada ítem), confirmá cuáles de verdad faltan -- filtrá por "scales" contra el scale real del proyecto (ver project.scale en get_project_context; un ítem con scales:["platform"] no aplica a una landing). Por cada uno que confirmes ausente con evidencia concreta, llamá a report_foundation_gap con esa evidencia específica -- nunca lo reportes solo porque el checklist lo menciona, sin haber revisado el código de verdad. No repitas un chequeo ya hecho recientemente en la misma sesión.
 
 Si el usuario pregunta explícito qué Claude Skills de terceros le faltan (o pide instalar alguna) -- no lo hagas sin que te lo pidan: llamá a get_skills_catalog y revisá con acceso real al filesystem cuáles de esos keys ya existen en .claude/skills/ (del proyecto) o ~/.claude/skills/ (global). Antes de instalar cualquiera con install_skill, llamá primero a preview_skill y mostrale al usuario el skillMdContent completo -- nunca instales sin que haya visto ese contenido y confirmado explícitamente, los SKILL.md de terceros pueden traer instrucciones que un agente ejecuta solo con cargarlas.`
 
@@ -228,9 +228,29 @@ export function createServer() {
   registerRead(
     'search',
     '/v1/search',
-    'Busca por texto en tareas, notas, ideas y docs de un proyecto de Orquestra.',
-    { q: z.string().describe('Texto a buscar') },
-    (args, projectId) => ({ projectId, q: args.q })
+    'Busca por texto en tareas, notas, ideas y docs de un proyecto de Orquestra. Tope de 30 resultados con las tareas primero: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
+    {
+      q: z.string().describe('Texto a buscar'),
+      types: z.array(z.enum(['task', 'note', 'idea', 'doc'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en los cuatro.'),
+    },
+    (args, projectId) => ({ projectId, q: args.q, types: args.types?.join(',') })
+  )
+
+  registerRead(
+    'list_ideas',
+    '/v1/ideas',
+    'Lista las ideas de un proyecto de Orquestra. Por default excluye las hechas y descartadas (mismo criterio que list_tasks): pide un `status` puntual (se respeta tal cual, incluso uno cerrado) o includeClosed=true para verlas. Filtros AND por módulo, prioridad y origen.',
+    {
+      status: z.enum(IDEA_STATUSES).optional().describe('Un estatus puntual (opcional)'),
+      includeClosed: z.boolean().optional().describe('true para incluir también hechas y descartadas'),
+      moduleId: z.string().optional().describe('ID de módulo para filtrar (opcional)'),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Prioridad para filtrar (opcional)'),
+      origin: z.enum(['cliente', 'soporte', 'equipo', 'ventas']).optional().describe('Origen para filtrar (opcional)'),
+    },
+    (args, projectId) => ({
+      projectId, status: args.status, includeClosed: args.includeClosed ? 'true' : undefined,
+      moduleId: args.moduleId, priority: args.priority, origin: args.origin,
+    })
   )
 
   // ═══ LECTURA (nivel A -- dashboard, workspace, infra, paridad, playbooks) ═══
@@ -243,6 +263,31 @@ export function createServer() {
     (args, projectId) => ({ projectId })
   )
 
+  registerRead(
+    'get_project_findings',
+    '/v1/findings',
+    'Qué le falta o qué está mal en un proyecto, ya calculado por el servidor y priorizado por severidad (high/medium/low): tareas vencidas o bloqueadas, módulos en riesgo, tareas sin módulo/fecha, referencias rotas, desfases de paridad, infraestructura caída, servicios que faltan (backend/base de datos/auth/analytics/push), posibles tareas duplicadas y fundamentos olvidados que ya se reportaron. Cada hallazgo trae título, detalle, entidades afectadas (con id) y una acción sugerida. Es determinístico, rápido y no consume créditos de IA. Lo ya descartado o aceptado como sugerencia no aparece.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerCreate(
+    'ask_assistant',
+    '/v1/assistant/ask',
+    'Pregúntale al Asistente de Orquestra sobre el proyecto (qué hacer hoy, qué está en riesgo, por qué algo está atorado). El servidor arma el contexto real del proyecto -- tareas abiertas, hallazgos, módulos -- y responde { answer, proposals } citando tareas por código. Consume 1 crédito de IA del workspace por pregunta; si solo necesitas saber qué falta, usa get_project_findings, que es gratis. Solo recomienda: no cambia nada en el proyecto.',
+    {
+      question: z.string().describe('La pregunta, en lenguaje natural (máx. 1000 caracteres)'),
+      history: z.array(z.object({ role: z.enum(['user', 'assistant']), text: z.string() })).optional().describe('Turnos previos de la conversación, si hay'),
+    }
+  )
+
+  registerCreate(
+    'assess_project',
+    '/v1/assistant/assess',
+    'Diagnóstico corto del proyecto con IA: un resumen del estado y de 1 a 3 prioridades, partiendo de los hallazgos de get_project_findings. El servidor lo guarda 1 hora mientras los hallazgos no cambien, así que repetirlo es gratis; solo cobra 1 crédito de IA cuando lo recalcula. Si no hay hallazgos no usa IA.',
+    {}
+  )
+
   registerRead(
     'get_infra_status',
     '/v1/infra',
@@ -290,6 +335,54 @@ export function createServer() {
     }
   )
 
+  // Config "suelta" que hasta el 8 oct 2026 solo se podía tocar desde la
+  // web (ver workspaceSettings.mjs en orquestra-infra) -- José pidió poder
+  // darla de alta también por acá.
+  server.registerTool(
+    'set_slack_webhook',
+    {
+      description: 'Configura (o quita, con url:"") el webhook de Slack del workspace -- cada notificación (tareas asignadas, QA, infra, contenido...) también se manda ahí, además de in-app/push/correo. Requiere un token de servicio SIN projectId (mismo criterio que get_workspace_summary/init_project) -- un token scopeado a un proyecto puntual no puede tocar esto.',
+      inputSchema: {
+        url: z.string().describe('URL del Incoming Webhook de Slack (https://hooks.slack.com/services/...), o "" para desactivarlo'),
+      },
+    },
+    async ({ url }) => {
+      try {
+        const data = await apiPatch(config, '/v1/workspaces', { id: config.workspaceId, slackWebhookUrl: url })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  registerRead('get_content_budget', '/v1/content-config',
+    'Lee los topes numéricos de presupuesto/tarifa de Inversión de Contenido de un proyecto (hourlyRate, monthlyBudget, dailyCap, perCampaignCap, alertThresholdPct). No trae el resto de contentConfig (guía de marca, imágenes, fragmentos aprobados) -- eso es contenido rico pensado para autoría humana en la web.',
+    {}, (args, projectId) => ({ projectId }))
+
+  server.registerTool(
+    'set_hourly_rate',
+    {
+      description: 'Configura la tarifa por hora (u otros topes numéricos de presupuesto de Inversión de Contenido) de un proyecto -- alimenta "Horas del equipo" (Σ timeEntries del mes en curso × esta tarifa) y el reporte de horas facturables de la web (sección Horas). Al menos un campo es obligatorio.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        hourlyRate: z.number().optional().describe('Tarifa por hora única del proyecto (misma moneda que el resto de Inversión)'),
+        monthlyBudget: z.number().optional().describe('Presupuesto asignado del mes'),
+        dailyCap: z.number().optional().describe('Tope diario -- informativo, no se aplica solo'),
+        perCampaignCap: z.number().optional().describe('Tope por campaña -- sí se aplica solo (pausa la campaña al llegar acá)'),
+        alertThresholdPct: z.number().optional().describe('Default 80 -- aviso cuando el gasto llega a este % del monthlyBudget'),
+      },
+    },
+    async ({ projectId, ...body }) => {
+      try {
+        const data = await apiPatchPath(config, '/v1/content-config', { projectId: resolveProjectId(projectId), ...body })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   registerRead(
     'list_modules',
     '/v1/modules',
@@ -516,7 +609,8 @@ export function createServer() {
       scope: z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean() })).optional()
         .describe('Alcance por distribución (paridad multiplataforma) -- para setearlo desde la creación en vez de crear y después update_task. Usa get_parity_summary/list_distributions para ver qué distId existen. Si una distId tiene hermanas (mismo productKey), el server suma las que falten solo, con done:false -- la respuesta trae parityAddedDistIds con lo que agregó: avísale al usuario que la tarea también quedó pendiente en esas plataformas.'),
       skipParity: z.boolean().optional().describe('true = NO sumar las plataformas hermanas al scope aunque tengan el mismo productKey. Solo cuando el trabajo es genuinamente de UNA plataforma (ej. un ajuste de Gradle que no tiene contraparte en iOS) -- no lo mandes por default. Las tareas type="bug" nunca propagan, sin necesidad de esto.'),
-      relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea. Esta tarea se muestra como bloqueada mientras esa otra no llegue a un estatus final (isFinal). Úsalo cuando el trabajo real depende de que otra tarea termine primero.'),
+      relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea. LEGACY desde ORQ-248: si vas a bloquear por más de una tarea, usa blockedByIds en vez de esto (relatedTaskId se sigue llenando solo, como blockedByIds[0], para paridad con iOS/Android).'),
+      blockedByIds: z.array(z.string()).optional().describe('"Bloqueada por" -- ids de otras tareas (puede ser más de una). Esta tarea se muestra como bloqueada mientras ALGUNA de esas no llegue a un estatus final (isFinal). Reemplaza a relatedTaskId para bloqueos múltiples -- preferí este campo, no relatedTaskId, salvo que de verdad sea un solo bloqueador.'),
       location: z.string().optional().describe('Solo relevante para type "meeting"/"call" (plataforma o lugar, ej. "Zoom", "Oficina") o "followup"/"business" (contexto libre) -- ignóralo para el resto de los tipos.'),
       estimatedDays: z.number().optional().describe('Estimación en días de trabajo.'),
       stack: z.array(z.string()).optional().describe('Tecnologías involucradas (mismo vocabulario que el stack de una distribución, ej. "node", "react", "postgres").'),
@@ -551,7 +645,8 @@ export function createServer() {
       tags: z.array(z.string()).optional(),
       scope: z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean() })).optional()
         .describe('Alcance por distribución -- usa get_parity_summary para ver el scope actual antes de editarlo'),
-      relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea, o "" para quitar el bloqueo. Ver create_task.'),
+      relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea, o "" para quitar el bloqueo. LEGACY, ver create_task -- preferí blockedByIds.'),
+      blockedByIds: z.array(z.string()).optional().describe('"Bloqueada por" -- reemplaza el array COMPLETO (no hace merge), [] quita todos los bloqueos. Ver create_task.'),
       location: z.string().optional().describe('Solo relevante para type "meeting"/"call"/"followup"/"business". Ver create_task.'),
       comment: z.string().optional().describe('Explica qué hiciste o por qué cambia la tarea -- queda como comentario visible en ella. Obligatorio en la práctica cuando mandas statusId: sin esto, alguien ve que la tarea cambió de estatus pero no por qué.'),
       estimatedDays: z.number().optional().describe('Estimación en días de trabajo.'),
@@ -1652,7 +1747,7 @@ export function createServer() {
     deployMode: z.enum(['auto', 'manual']).optional().describe('Modo de deploy -- web'),
     hasPush: z.boolean().optional().describe('Tiene push notifications -- apps (ios/android)'),
     storeUrl: z.string().optional(),
-    stack: z.array(z.string()).optional(),
+    stack: z.array(z.string()).optional().describe('Tecnologías de la plataforma. Puedes mandar nombres ("Kotlin", "Jetpack Compose", "Node.js"): la API los normaliza a las claves de su catálogo (schema/enums/TechStack.json en orquestra-infra) y conserva lo que no reconoce.'),
     version: z.string().optional().describe('Versión en store'),
     reviewVersion: z.string().optional().describe('Build en revisión -- apps'),
     repoUrl: z.string().optional().describe('URL del repo de este código (ej. de "git remote get-url origin") -- solo informativo, no requiere credenciales. Distinto de conectar el repo con PAT (eso es Workspace → Conexiones, un paso deliberado del usuario, nunca lo hagas solo).'),
@@ -1673,7 +1768,7 @@ export function createServer() {
     deployMode: z.enum(['auto', 'manual']).optional(),
     hasPush: z.boolean().optional(),
     storeUrl: z.string().optional(),
-    stack: z.array(z.string()).optional(),
+    stack: z.array(z.string()).optional().describe('Tecnologías de la plataforma. Puedes mandar nombres ("Kotlin", "Jetpack Compose", "Node.js"): la API los normaliza a las claves de su catálogo (schema/enums/TechStack.json en orquestra-infra) y conserva lo que no reconoce.'),
     version: z.string().optional(),
     reviewVersion: z.string().optional(),
     repoUrl: z.string().optional().describe('URL del repo de este código -- solo informativo, no requiere credenciales.'),
@@ -1763,6 +1858,39 @@ export function createServer() {
     status: z.enum(CAMPAIGN_STATUSES).optional(),
   })
 
+  // Registro de riesgos a nivel de proyecto (ORQ-246, 8 oct 2026) --
+  // distinto de "bloqueada" en una tarea puntual (relatedTaskId/
+  // isTaskBlocked): esto es "qué puede hacer fallar el proyecto" en
+  // general, sin necesitar estar ligado a una tarea.
+  const RISK_LEVELS = ['low', 'medium', 'high']
+  const RISK_STATUSES = ['open', 'mitigating', 'closed']
+
+  registerRead('list_risks', '/v1/risks',
+    'Lista los riesgos/bloqueos a nivel de proyecto (dependencias externas, decisiones pendientes de un cliente, etc. -- no ligados necesariamente a una tarea puntual). Úsala antes de create_risk para no duplicar.',
+    {}, (args, projectId) => ({ projectId }))
+
+  registerCreate('create_risk', '/v1/risks', 'Registra un riesgo/bloqueo a nivel de proyecto -- algo que puede hacer fallar o atrasar el proyecto en general, no el bloqueo puntual de una tarea (para eso usa relatedTaskId en update_task).', {
+    title: z.string(),
+    description: z.string().optional(),
+    probability: z.enum(RISK_LEVELS).optional().describe('Default: medium'),
+    impact: z.enum(RISK_LEVELS).optional().describe('Default: medium'),
+    mitigation: z.string().optional().describe('Plan o texto libre de qué se hace para reducir este riesgo'),
+    status: z.enum(RISK_STATUSES).optional().describe('Default: open. "closed" en vez de borrar -- nunca se borra un riesgo.'),
+    ownerUid: z.string().optional().describe('Dueño del riesgo -- le avisa solo a esa persona al asignarla (ver list de miembros del workspace)'),
+    moduleId: z.string().optional().describe('Módulo relacionado, si aplica (ver list_modules)'),
+  })
+
+  registerUpdate('update_risk', '/v1/risks', 'Edita un riesgo existente -- típicamente para actualizar su mitigación o cerrarlo (status: "closed") cuando deja de aplicar.', {
+    title: z.string().optional(),
+    description: z.string().optional(),
+    probability: z.enum(RISK_LEVELS).optional(),
+    impact: z.enum(RISK_LEVELS).optional(),
+    mitigation: z.string().optional(),
+    status: z.enum(RISK_STATUSES).optional(),
+    ownerUid: z.string().optional(),
+    moduleId: z.string().optional(),
+  })
+
   registerRead('list_content', '/v1/content',
     'Lista las publicaciones de contenido (posts programados/publicados) de un proyecto.',
     {}, (args, projectId) => ({ projectId }))