orquestra-mcp 1.7.1 → 1.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.7.1",
+  "version": "1.7.9",
   "description": "Servidor MCP de Orquestra -- 51 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

@@ -17,8 +17,19 @@ const PROJECT_ID_DESC = 'ID del proyecto dentro del workspace configurado. Si ha
 const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'design', 'security', 'meeting', 'call', 'followup', 'business']
 const TASK_PRIORITIES = ['high', 'medium', 'low']
 const CHANGELOG_SECTIONS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
-const DOC_TYPES = ['readme', 'usecase', 'diagram', 'env', 'adr', 'runbook', 'api']
+// 'postmortem' faltaba acá (gap preexistente, encontrado 12 ago 2026) --
+// mismo fix del lado de write.mjs en orquestra-infra.
+const DOC_TYPES = ['readme', 'usecase', 'diagram', 'env', 'adr', 'runbook', 'postmortem', 'api']
 const ADR_STATUSES = ['propuesto', 'aceptado', 'deprecado', 'rechazado']
+const DOC_FOLDERS = ['arquitectura', 'api', 'operaciones', 'decisiones']
+const DOC_VISIBILITY = ['team', 'workspace', 'public']
+// 'hecha' agregado 12 ago 2026 -- ver misma nota en write.mjs de
+// orquestra-infra (convertToTask ya no borra la idea, la deja en 'hecha').
+const IDEA_STATUSES = ['nueva', 'en_estudio', 'planeada', 'hecha', 'en_espera', 'descartada']
+const IDEA_ORIGINS = ['cliente', 'soporte', 'equipo', 'ventas']
+const IDEA_IMPACT_EFFORT = ['alto', 'bajo']
+const NOTE_TYPES = ['decision', 'incidente', 'cliente', 'planificacion']
+const NOTE_VISIBILITY = ['team', 'private']
 const SERVICE_TYPES = ['backend', 'database', 'auth', 'storage', 'push', 'email', 'payments', 'analytics', 'realtime', 'search', 'maps', 'flags', 'admin', 'cdn', 'queue']
 const PLATFORM_TYPES = ['android', 'ios', 'web', 'desktop-mac', 'desktop-win', 'backend', 'extension', 'other']
 const INFRA_STATUSES = ['operational', 'degraded', 'down']
@@ -56,11 +67,14 @@ Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es
 
 Durante el trabajo normal de código, sin que el usuario te lo pida explícitamente y SIN ESPERAR a que lo mencione (si tienes esta tool disponible en la sesión, se usa por default en todo trabajo real, no solo cuando alguien dice "usa Orquestra"):
 - Si te pide una funcionalidad o arreglo real (no una pregunta rápida ni exploración de código sin cambios), revisa con list_tasks/search si ya existe una tarea relacionada; si no, créala con create_task ANTES de empezar a trabajar, en el estatus inicial del proyecto (ver list_statuses). Si no hay un proyecto default configurado para esta carpeta, no te rindas ahí -- usa get_workspace_summary para encontrar el proyecto correcto y pásalo explícito como projectId en cada llamada.
-- Mientras trabajas, mueve la tarea por los estatus reales según avanzas (no la dejes en el inicial hasta el final). Al terminar, muévela a su estatus final con update_task y registra una entrada de changelog con create_changelog_entry -- así el usuario nunca tiene que documentar esto a mano.
+- Mientras trabajas, mueve la tarea por los estatus reales según avanzas (no la dejes en el inicial hasta el final). Al terminar, muévela a su estatus final con update_task y registra una entrada de changelog con create_changelog_entry -- así el usuario nunca tiene que documentar esto a mano. Si sabes en qué repo real estás trabajando (podés correr "git remote get-url origin" o ya lo sabes por la carpeta), pásalo SIEMPRE como "repo" ("owner/name") -- encontrado real (17 ago 2026): ni el hook local ni el GitHub Action ni la reconciliación de orquestra-infra lo estaban mandando pese a que el campo existe hace rato, así que ninguna entrada automática sabía de qué repo/plataforma venía. Si además la distribución de ese repo ya está identificada (ver list_distributions), pásala en "distributions" -- sin esto el changelog no puede filtrar/agrupar por plataforma.
 - Todo cambio de statusId vía update_task valida la transición (nextIds) y queda en el historial de la tarea -- pero ese historial no dice nada por sí solo. Manda SIEMPRE el parámetro "comment" cuando cambies statusId, explicando qué hiciste o por qué -- sin esto, el usuario ve que la tarea cambió pero no sabe por qué ni qué se hizo de verdad (encontrado real: quedaba invisible, a diferencia de cuando un humano mueve la tarjeta a mano en el kanban).
 - Antes de crear un módulo/estatus/categoría/servicio/entorno/distribución, revisa con el list_* correspondiente que no exista ya uno con ese nombre.
 - Si una nota que vas a crear (create_note) es claramente sobre un módulo o una tarea específica -- por ejemplo durante un setup guiado donde acabas de crear ambos -- mándale moduleId/taskId para ligarla, en vez de dejarla suelta. No inventes la relación si no es clara.
+- create_changelog_entry SIEMPRE deja la entrada en Unreleased (nunca mandes version salvo que el usuario te haya dado un número real) -- cortar una versión es release_changelog_version, una acción DELIBERADA que solo se llama si el usuario la pide explícitamente ("cortá la versión", "hacé el release de X") o confirma un número/fecha real que vos propusiste. No la dispares solo porque terminaste una tarea o un lote de trabajo grande.
 - Si tienes acceso al repo real de una distribución (ej. puedes correr "git remote get-url origin" en ese código), llena repoUrl en create_distribution/update_distribution sin preguntar -- es solo informativo, no requiere credenciales. Esto es distinto de conectar el repo con PAT para el changelog automático (Workspace → Conexiones en orquestra-web): eso sí es un paso deliberado del usuario, con una credencial real -- nunca lo hagas tú solo ni sugieras que ya está conectado por haber llenado repoUrl.
+- Al crear o editar una tarea (o un módulo), llena TODO campo para el que tengas un dato real, no solo title/moduleId/dueDate/comment: type (no lo dejes en el default "feature" si en realidad es un bug/mejora/doc/etc.), tags, stack (tecnologías que genuinamente tocaste), scope (paridad multiplataforma, si aplica), y los campos de código (branch/prNumber/prUrl/prStatus/commitCount/resolvedCommitSha/resolvedCommitMessage/resolvedCommitUrl/resolvedCommitAt) cuando de verdad sepas esos valores (el branch en el que estás trabajando, el PR que abriste, el commit que resolvió la tarea). No dejes un campo en blanco solo porque no es obligatorio -- pero esto no es licencia para inventar: si no tenés el dato real (ej. no hay branch/PR porque el proyecto commitea directo a main), dejalo vacío en vez de rellenarlo con algo plausible pero falso -- mismo criterio que ya se pedía para resolvedCommitSha.
+- Si una tarea tiene más de una actividad o paso concreto, no los amontones como texto corrido en description -- usa el checklist (add_checklist_item, un ítem por actividad, opcionalmente con responsable) para que cada paso se pueda marcar independientemente. description queda para el contexto/propósito general de la tarea (el qué y el por qué), no como lista de pasos. Si estás editando una tarea existente cuya description ya creció así, migra esos puntos a checklist en vez de seguir agregando ahí.
 - No todas las tareas necesitan una corrida de QA -- clasifica antes de disparar una: cambios que afectan comportamiento real (features, bugs, UI, lógica de negocio, endpoints/API) sí la necesitan; cambios que no alteran comportamiento (docs, comentarios, refactors sin cambio funcional, config/tooling interno, notas/reuniones/ideas) no. Si decides que sí, revisa primero con list_qa_agents que exista un agente para el stack que tocaste (si no hay ninguno, créalo con create_qa_agent -- necesita una máquina ya emparejada, ver Workspace → QA) y llama a create_qa_run en la rama real de ese trabajo (manda taskId si el trabajo era de una tarea puntual -- si el agente tiene la revisión con IA activada, la acota a eso en vez de "revisa todo el proyecto"), dejando la tarea en "En revisión" -- NUNCA la muevas a "Listo" ni digas que "QA lo revisó" sin haber confirmado con get_qa_run un estatus terminal "passed" de verdad (las corridas son asíncronas, tardan minutos en otra máquina). Si tarda, dile al usuario que quedó en cola (con el runId) y que confirmas cuando termine -- no lo des por hecho nunca.
 
 Si el usuario pide "sincronizar"/"revisar que todo esté al día"/"verificar el proyecto" (o algo equivalente -- una auditoría manual, no el trabajo normal de arriba), hacé una "revisión de sincronización" completa, de cero, no un vistazo rápido:
@@ -432,12 +446,27 @@ export function createServer() {
     {
       title: z.string().describe('Título de la idea'),
       description: z.string().optional(),
-      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium'),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium -- se puede derivar de impact+effort si los mandas (alto+bajo→high, alto+alto o bajo+bajo→medium, bajo+alto→low).'),
       categoryId: z.string().optional(),
       dueDate: z.string().optional().describe('YYYY-MM-DD'),
+      moduleId: z.string().optional(),
+      status: z.enum(IDEA_STATUSES).optional().describe('Default: nueva. "hecha" es a dónde llega una idea convertida en tarea (ver convertToTask en la web) -- no la mandes vos al crear, no tiene sentido crear una idea ya "hecha".'),
+      origin: z.enum(IDEA_ORIGINS).optional(),
+      requestedBy: z.array(z.object({
+        name: z.string().describe('Nombre del cliente, en texto libre (no hay entidad "cliente" en Orquestra)'),
+        quote: z.string().optional().describe('Cita textual de por qué lo pidió, si la tenés'),
+      })).optional().describe('Quién pidió esta idea -- cada uno suma +1 a voteCount. `requestedAt` se estampa solo, server-side, no lo mandes.'),
+      impact: z.enum(IDEA_IMPACT_EFFORT).optional(),
+      effort: z.enum(IDEA_IMPACT_EFFORT).optional(),
+      risk: z.enum(IDEA_IMPACT_EFFORT).optional().describe('Riesgo de esta idea (alto/bajo) -- agregado 12 ago 2026, alimenta la recomendación del detalle de idea junto con impact/effort.'),
+      voteCount: z.number().optional().describe('Default: 1 + requestedBy.length'),
     }
   )
 
+  registerRead('list_changelog', '/v1/changelog',
+    'Lista TODAS las entradas de changelog de un proyecto, con todos sus campos (id, section, text, version, distributions, repo, taskId, createdAt, createdBy) -- a diferencia de get_dashboard_summary/get_project_context, que solo traen un resumen recortado (texto/título, sin repo ni distributions). Útil para auditar (ej. "¿qué entradas viejas no tienen repo?") antes de update_changelog_entry.',
+    {}, (args, projectId) => ({ projectId }))
+
   registerCreate(
     'create_changelog_entry',
     '/v1/changelog',
@@ -446,6 +475,37 @@ export function createServer() {
       section: z.enum(CHANGELOG_SECTIONS).describe('Sección del changelog'),
       text: z.string().describe('Descripción de la entrada'),
       version: z.string().optional(),
+      distributions: z.array(z.object({
+        distId: z.string(),
+        version: z.string().optional(),
+      })).optional().describe('Distribuciones a las que aplica esta entrada (ver list_distributions) -- vacío/omitido = aplica a todo el proyecto. Cada una puede tener su propia versión dentro de esta entrada.'),
+      repo: z.string().optional().describe('"owner/name" del repo de origen del commit/PR que generó esta entrada, si se sabe -- alimenta el chip de repo en la tarjeta de versión.'),
+      taskId: z.string().optional().describe('Tarea que esta entrada documenta o cierra, si se sabe (ver list_tasks) -- alimenta el chip de tarea, clicable al detalle, en la tarjeta de versión.'),
+    }
+  )
+
+  registerUpdate('update_changelog_entry', '/v1/changelog',
+    'Edita una entrada de changelog existente (section/text/version/distributions/repo/taskId) -- primera edición puntual por id que existe (antes solo había create + el bulk-update de release_changelog_version). Pensada sobre todo para backfill/corrección (ej. completar "repo" en entradas viejas que se crearon antes de que ese campo se mandara), no para reescribir historia -- si el usuario solo quiere corregir el texto de una entrada reciente por error de tipeo, esto también sirve.',
+    {
+      section: z.enum(CHANGELOG_SECTIONS).optional(),
+      text: z.string().optional(),
+      version: z.string().optional(),
+      distributions: z.array(z.object({
+        distId: z.string(),
+        version: z.string().optional(),
+      })).optional(),
+      repo: z.string().optional().describe('"owner/name" del repo de origen.'),
+      taskId: z.string().optional(),
+    }
+  )
+
+  registerCreate(
+    'release_changelog_version',
+    '/v1/changelog/release',
+    'Corta una versión del changelog: toma TODAS las entradas que están en Unreleased (o, si mandas distributionId, solo las de esa distribución) y les asigna un número de versión real, mismo efecto que el botón "+ Nueva versión" de la web -- también actualiza distribution.version de las distribuciones tocadas. NUNCA lo llames sin que el usuario lo haya pedido explícitamente (o confirmado un número/fecha de release real) -- cortar una versión es una decisión de producto, no un paso automático de "buena higiene" como sí lo es create_changelog_entry.',
+    {
+      version: z.string().optional().describe('Semver real, ej. "1.4.0". Si se omite, se sugiere solo (Removed/Security -> mayor, Added -> menor, resto -> parche) a partir de la versión conocida más alta -- decíselo al usuario ANTES de aplicar si vos elegiste el número, no lo apliques en silencio.'),
+      distributionId: z.string().optional().describe('Si se manda, solo libera las entradas de ESA distribución (ver list_distributions) -- las entradas globales/de otras distribuciones quedan en Unreleased. Sin esto, libera todo el proyecto.'),
     }
   )
 
@@ -459,6 +519,11 @@ export function createServer() {
       pinned: z.boolean().optional(),
       moduleId: z.string().optional().describe('Módulo relacionado, si la nota es sobre uno específico -- ligarla ayuda a encontrarla después (ver list_modules)'),
       taskId: z.string().optional().describe('Tarea relacionada, si la nota es sobre una específica (ver list_tasks)'),
+      type: z.enum(NOTE_TYPES).optional().describe('Default: planificacion (nota sin tipo especial). "decision" habilita alternativesConsidered/wouldRevertIf.'),
+      alternativesConsidered: z.string().optional().describe('Solo para type=\'decision\'. Qué más se evaluó y por qué no.'),
+      wouldRevertIf: z.string().optional().describe('Solo para type=\'decision\'. La condición que haría cambiar de opinión -- sin esto la decisión se vuelve dogma.'),
+      visibility: z.enum(NOTE_VISIBILITY).optional().describe('Default: team. "private" restringe la lectura a quien la creó (enforcement real en firestore.rules, no solo la UI).'),
+      relatedNoteId: z.string().optional().describe('Otra nota relacionada, si es clara la relación (ver search) -- agregado 12 ago 2026. No inventes el vínculo si no es evidente.'),
     }
   )
 
@@ -473,6 +538,11 @@ export function createServer() {
       adrStatus: z.enum(ADR_STATUSES).optional().describe('Solo para type=\'adr\'. "aceptado" es lo único que alimenta Material (Contenido) como fuente de ángulos -- ver adrContext.'),
       adrContext: z.string().optional().describe('Solo para type=\'adr\'. Qué problema/situación llevó a la decisión, en texto estructurado (no el markdown libre de content).'),
       adrConsequences: z.string().optional().describe('Solo para type=\'adr\'. Qué cambia de ahora en adelante.'),
+      moduleId: z.string().optional().describe('Módulo al que pertenece (ver list_modules) -- vincularlo es lo que permite detectar "puede estar desactualizado" cuando el módulo acumula actividad después de la última edición.'),
+      folder: z.enum(DOC_FOLDERS).optional().describe('Carpeta donde se archiva en la UI -- independiente de `type` (ej. un ADR se puede archivar en cualquier carpeta).'),
+      visibility: z.enum(DOC_VISIBILITY).optional().describe('"team" (default) | "workspace" | "public". "public" expone el doc sin sesión en una URL propia.'),
+      reviewOwnerUid: z.string().optional().describe('uid de quién recibe el aviso cuando el doc queda desactualizado.'),
+      reviewIntervalDays: z.number().optional().describe('Cada cuántos días revisar por calendario (30/90/180) -- sin esto, solo se detecta vencimiento por actividad del módulo vinculado, nunca por fecha.'),
     }
   )
 
@@ -531,10 +601,14 @@ export function createServer() {
   registerCreate('create_category', '/v1/categories', 'Crea una categoría (agrupación/audiencia) en un proyecto.', {
     name: z.string().describe('Nombre de la categoría'),
     color: z.string().optional().describe('Color hex'),
+    description: z.string().optional().describe('Para qué sirve esta categoría, en pocas palabras -- agregado 12 ago 2026.'),
+    order: z.number().optional().describe('Orden manual de aparición (más chico = más arriba) -- agregado 12 ago 2026.'),
   })
   registerUpdate('update_category', '/v1/categories', 'Edita una categoría existente.', {
     name: z.string().optional(),
     color: z.string().optional(),
+    description: z.string().optional(),
+    order: z.number().optional(),
   })
 
   // Campos específicos por tipo de servicio -- unión deduplicada de las