orquestra-mcp 1.27.0 → 1.31.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.27.0",
-  "description": "Servidor MCP de Orquestra -- 112 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
+  "version": "1.31.0",
+  "description": "Servidor MCP de Orquestra -- 115 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"
@@ -26,6 +26,6 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
+    "zod": "^4.6.5"
   }
 }

package/src/server.mjs

@@ -46,13 +46,15 @@ const PLATFORM_TYPES = ['android', 'ios', 'web', 'desktop-mac', 'desktop-win', '
 const INFRA_STATUSES = ['operational', 'degraded', 'down']
 const STAGE_IDS = STAGES.map(s => s.id)
 
-// Adjuntos -- entityType en la tool es singular (task/note/idea/doc, más
-// natural para el modelo), la API usa el plural de la colección de
-// Firestore (tasks/notes/ideas/docs) -- este mapa traduce entre los dos.
-const ATTACHMENT_ENTITY_PATH = { task: 'tasks', note: 'notes', idea: 'ideas', doc: 'docs' }
+// Adjuntos -- entityType en la tool es singular (task/note/idea/doc/content,
+// más natural para el modelo), la API usa el plural de la colección de
+// Firestore (tasks/notes/ideas/docs/content) -- este mapa traduce entre los dos.
+const ATTACHMENT_ENTITY_PATH = { task: 'tasks', note: 'notes', idea: 'ideas', doc: 'docs', content: 'content' }
 const ATTACHMENT_ENTITY_TYPES = Object.keys(ATTACHMENT_ENTITY_PATH)
 const ATTACHMENT_IMAGE_MIME_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' }
+const ATTACHMENT_VIDEO_MIME_BY_EXT = { mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm' }
 const MAX_ATTACHMENT_IMAGE_BYTES = 15 * 1024 * 1024
+const MAX_ATTACHMENT_VIDEO_BYTES = 500 * 1024 * 1024
 const MAX_ATTACHMENT_CODE_CHARS = 200_000
 
 const SETUP_GUIDE = {
@@ -299,9 +301,9 @@ export function createServer() {
   registerRead(
     'get_parity_summary',
     '/v1/parity',
-    'Desfases de paridad multiplataforma: tareas y módulos cuyo scope avanza en una distribución pero sigue pendiente en otra HERMANA (mismo productKey -- ver productGroups en la respuesta; si configured=false, el proyecto nunca marcó qué plataformas son el mismo producto y todas se comparan entre sí: sugiérele al usuario configurarlo con update_distribution/productKey). singleDoneItems trae las candidatas a portar con missingDistIds concretos.',
+    'Desfases de paridad multiplataforma: tareas y módulos cuyo scope avanza en una distribución pero sigue pendiente en otra HERMANA (mismo productKey -- ver productGroups en la respuesta; si configured=false, el proyecto nunca marcó qué plataformas son el mismo producto y todas se comparan entre sí: sugiérele al usuario configurarlo con update_distribution/productKey). singleDoneItems trae las candidatas a portar con missingDistIds concretos. Solo cuentan tareas de producto: se excluyen bugs, tareas fusionadas, canceladas/archivadas y las marcadas parityExempt; las candidatas a portar son solo feature/improvement/design (nunca módulos). Un gap es una señal, no un veredicto: el done por plataforma es un flag manual y el trabajo móvil suele existir ya bajo otra tarea -- verifica en el código real de esa plataforma antes de decir que falta algo o de crear una tarea. La respuesta viene compacta: el detalle de gapItems/singleDoneItems está en combined; tasks y modules solo traen totales.',
     {},
-    (args, projectId) => ({ projectId })
+    (args, projectId) => ({ projectId, compact: '1' })
   )
 
   registerRead(
@@ -750,6 +752,84 @@ export function createServer() {
     }
   )
 
+  // Crear rama + abrir PR borrador desde una tarea (ORQ-204, 10 oct 2026):
+  // requiere que la GitHub App de ese repo tenga permisos de escritura en
+  // Contents/Pull requests -- si no, el servidor responde 502/403 con el
+  // detalle de GitHub. "Crear rama" guarda el nombre en task.branch (lo que
+  // ya lee sync_task_from_github); "Abrir PR" exige que la tarea ya tenga
+  // branch (de este tool o puesto a mano).
+  server.registerTool(
+    'create_task_branch',
+    {
+      description: 'Crea una rama en GitHub para esta tarea (ej. "ORQ-123-arregla-el-login") desde la rama base de la integración, y la guarda en task.branch. Idempotente: si la rama ya existe, no falla. Si el proyecto tiene varios repos conectados, pasa integrationId (list_github_integrations).',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('ID de la tarea'),
+        integrationId: z.string().optional().describe('Integración (repo) concreta; opcional si solo hay una'),
+        branchName: z.string().optional().describe('Nombre de rama explícito; por default "<shortCode>-<slug del título>"'),
+      },
+    },
+    async ({ projectId, taskId, integrationId, branchName }) => {
+      try {
+        return textResult(await apiPost(config, `/v1/tasks/${taskId}/github-branch`, { projectId: resolveProjectId(projectId), ...(integrationId ? { integrationId } : {}), ...(branchName ? { branchName } : {}) }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'open_task_pr',
+    {
+      description: 'Abre un PR borrador en GitHub desde task.branch hacia la rama base de la integración, con el shortCode y el link a la tarea en el título/cuerpo, y guarda prNumber/prUrl en la tarea. Requiere que la tarea ya tenga branch (create_task_branch primero, o uno puesto a mano). Idempotente: si ya hay un PR abierto para esa rama, devuelve ESE en vez de fallar.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('ID de la tarea'),
+        integrationId: z.string().optional().describe('Integración (repo) concreta; opcional si solo hay una'),
+      },
+    },
+    async ({ projectId, taskId, integrationId }) => {
+      try {
+        return textResult(await apiPost(config, `/v1/tasks/${taskId}/github-pr`, { projectId: resolveProjectId(projectId), ...(integrationId ? { integrationId } : {}) }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // Sync de Issues de GitHub <-> tareas (ORQ-203, 10 oct 2026): opt-in POR
+  // INTEGRACIÓN (apagado por default). Prenderlo exige issuesModuleId (a
+  // qué módulo van las tareas que crea un issue nuevo) -- sin eso, create_task
+  // no puede cumplir con "toda tarea requiere módulo". Una vez prendido:
+  // issues.opened crea una tarea tipo bug con el link del issue; cerrar la
+  // tarea cierra el issue y cerrar el issue cierra la tarea (sin bucles,
+  // ambos lados son idempotentes). mirrorComments (opcional, aparte) espeja
+  // comentarios nuevos del issue como comentario de sistema en la tarea --
+  // solo en ese sentido, comentar en Orquestra no escribe de vuelta en GitHub.
+  server.registerTool(
+    'update_github_issues_sync',
+    {
+      description: 'Prende/apaga el sync de Issues<->tareas de un repo conectado (opt-in por integración). issuesSync:true exige issuesModuleId (módulo donde caen las tareas que crea un issue nuevo). mirrorComments es opcional y aparte: espeja comentarios nuevos del issue como comentario de sistema en la tarea (solo en ese sentido).',
+      inputSchema: {
+        integrationId: z.string().describe('Integración (repo conectado) a configurar -- list_github_integrations'),
+        issuesSync: z.boolean().optional().describe('Prender/apagar la creación automática de tareas desde issues y el cierre cruzado'),
+        issuesModuleId: z.string().optional().describe('Módulo donde crear las tareas que originan los issues -- obligatorio para prender issuesSync'),
+        mirrorComments: z.boolean().optional().describe('Espejar comentarios nuevos del issue como comentario de sistema en la tarea (GitHub -> Orquestra, no al revés)'),
+      },
+    },
+    async ({ integrationId, issuesSync, issuesModuleId, mirrorComments }) => {
+      try {
+        return textResult(await apiPatchPath(config, `/v1/github-integrations/${integrationId}/github-issues`, {
+          ...(issuesSync !== undefined ? { issuesSync } : {}),
+          ...(issuesModuleId !== undefined ? { issuesModuleId } : {}),
+          ...(mirrorComments !== undefined ? { mirrorComments } : {}),
+        }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   server.registerTool(
     'run_closure_scan',
     {
@@ -1116,11 +1196,11 @@ export function createServer() {
   server.registerTool(
     'list_attachments',
     {
-      description: 'Lista los adjuntos (imágenes + código) de una task/note/idea/doc de Orquestra.',
+      description: 'Lista los adjuntos (imágenes + video + código) de una task/note/idea/doc/content de Orquestra.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad dueña de los adjuntos'),
-        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc/content)'),
       },
     },
     async ({ projectId, entityType, entityId }) => {
@@ -1144,12 +1224,12 @@ export function createServer() {
   server.registerTool(
     'add_attachment',
     {
-      description: 'Adjunta evidencia (una imagen o un pedazo de código) a una task/note/idea/doc de Orquestra. Manda EXACTAMENTE uno de filePath (ruta local -- una imagen png/jpg/jpeg/gif/webp se sube a S3, cualquier otra extensión se lee como texto/código) o content (texto/código directo, sin tocar el filesystem). Nunca mandes bytes de imagen en base64 dentro de content -- usa filePath para que este server los suba él mismo.',
+      description: 'Adjunta evidencia (una imagen, un video o un pedazo de código) a una task/note/idea/doc/content de Orquestra. OJO: en una pieza de Contenido esto NO la deja como media (no se ve ni se publica) -- para eso usa add_content_media. Manda EXACTAMENTE uno de filePath (ruta local -- una imagen png/jpg/jpeg/gif/webp o un video mp4/mov/webm se sube a S3, cualquier otra extensión se lee como texto/código) o content (texto/código directo, sin tocar el filesystem). Nunca mandes bytes de imagen/video en base64 dentro de content -- usa filePath para que este server los suba él mismo.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad a la que se adjunta'),
-        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
-        filePath: z.string().optional().describe('Ruta local a un archivo -- imagen (png/jpg/jpeg/gif/webp) o código/texto.'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc/content)'),
+        filePath: z.string().optional().describe('Ruta local a un archivo -- imagen (png/jpg/jpeg/gif/webp), video (mp4/mov/webm) o código/texto.'),
         content: z.string().optional().describe('Texto/código a adjuntar directo, sin leer un archivo.'),
         language: z.string().optional().describe('Label libre del lenguaje del snippet (ej. "python", "diff") -- solo informativo, no tokeniza (Orquestra no resalta sintaxis).'),
         fileName: z.string().optional().describe('Nombre a mostrar -- si no se manda, sale de filePath o de un default genérico.'),
@@ -1172,11 +1252,15 @@ export function createServer() {
         } else {
           const stat = statSync(filePath)
           const ext = path.extname(filePath).slice(1).toLowerCase()
-          const mime = ATTACHMENT_IMAGE_MIME_BY_EXT[ext]
+          const imageMime = ATTACHMENT_IMAGE_MIME_BY_EXT[ext]
+          const videoMime = ATTACHMENT_VIDEO_MIME_BY_EXT[ext]
+          const mime = imageMime || videoMime
+          const kind = imageMime ? 'image' : videoMime ? 'video' : null
           const resolvedFileName = fileName || path.basename(filePath)
           if (mime) {
-            if (stat.size > MAX_ATTACHMENT_IMAGE_BYTES) {
-              throw new Error(`La imagen supera el máximo de ${MAX_ATTACHMENT_IMAGE_BYTES / 1024 / 1024}MB`)
+            const maxBytes = kind === 'video' ? MAX_ATTACHMENT_VIDEO_BYTES : MAX_ATTACHMENT_IMAGE_BYTES
+            if (stat.size > maxBytes) {
+              throw new Error(`El archivo supera el máximo de ${maxBytes / 1024 / 1024}MB`)
             }
             const buffer = readFileSync(filePath)
             const { uploadUrl, key } = await apiPost(config, '/v1/attachments/upload-url', {
@@ -1184,7 +1268,7 @@ export function createServer() {
               fileName: resolvedFileName, fileType: mime, fileSize: stat.size,
             })
             await putToPresignedUrl(uploadUrl, buffer, mime)
-            body = { kind: 'image', key, fileName: resolvedFileName, fileType: mime, fileSize: stat.size, caption }
+            body = { kind, key, fileName: resolvedFileName, fileType: mime, fileSize: stat.size, caption }
           } else {
             const text = readFileSync(filePath, 'utf8')
             if (text.length > MAX_ATTACHMENT_CODE_CHARS) {
@@ -1202,6 +1286,45 @@ export function createServer() {
     }
   )
 
+  // Media de una pieza de Contenido (ORQ-283) -- distinto de add_attachment:
+  // un adjunto es evidencia privada, esto es el mediaFiles que Contenido
+  // muestra y Postproxy publica. Mismo criterio de bytes: este server lee el
+  // archivo y lo sube él mismo, nunca base64 por el input.
+  server.registerTool(
+    'add_content_media',
+    {
+      description: 'Pone una imagen o video como MEDIA de una pieza de Contenido (lo que se ve en la pieza y lo que se publica en redes) -- usa esto y NO add_attachment para contenido; add_attachment solo guarda evidencia privada que Contenido no muestra. Sube el archivo local (png/jpg/jpeg/gif/webp/mp4/mov/webm) y lo agrega al mediaFiles sin pisar el que ya haya. Sin channelId lo agrega a todos los canales de la pieza; con channelId solo a esa variante.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        contentId: z.string().describe('ID de la pieza (list_content)'),
+        filePath: z.string().describe('Ruta local a la imagen o video'),
+        channelId: z.string().optional().describe('Solo si quieres el archivo en un canal específico de una pieza multi-canal'),
+        fileName: z.string().optional().describe('Nombre a mostrar -- default: el del archivo'),
+      },
+    },
+    async ({ projectId, contentId, filePath, channelId, fileName }) => {
+      try {
+        const resolvedProjectId = resolveProjectId(projectId)
+        const stat = statSync(filePath)
+        const ext = path.extname(filePath).slice(1).toLowerCase()
+        const mime = ATTACHMENT_IMAGE_MIME_BY_EXT[ext] || ATTACHMENT_VIDEO_MIME_BY_EXT[ext]
+        if (!mime) throw new Error('Solo imágenes (png/jpg/jpeg/gif/webp) o videos (mp4/mov/webm)')
+        if (stat.size > MAX_ATTACHMENT_VIDEO_BYTES) throw new Error(`El archivo supera el máximo de ${MAX_ATTACHMENT_VIDEO_BYTES / 1024 / 1024}MB`)
+        const name = fileName || path.basename(filePath)
+        const { uploadUrl, key } = await apiPost(config, '/v1/content/media-upload-url', {
+          projectId: resolvedProjectId, fileName: name, fileType: mime, fileSize: stat.size,
+        })
+        await putToPresignedUrl(uploadUrl, readFileSync(filePath), mime)
+        const data = await apiPost(config, `/v1/content/${contentId}/media`, {
+          projectId: resolvedProjectId, key, name, type: mime, size: stat.size, ...(channelId ? { channelId } : {}),
+        })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   // Segunda excepción real a "creación + edición, nunca borrado" (junto a
   // delete_checklist_item, ver CLAUDE.md) -- decisión consciente de José:
   // un agente puede subir evidencia equivocada (screenshot que no era,
@@ -1211,11 +1334,11 @@ export function createServer() {
   server.registerTool(
     'delete_attachment',
     {
-      description: 'Borra un adjunto (imagen o código) de una task/note/idea/doc de Orquestra -- limpia también el objeto en S3 si era una imagen. Segunda excepción a "nunca borrado" (junto a delete_checklist_item) -- usalo para limpiar evidencia subida por error, no como reemplazo de mantener historial.',
+      description: 'Borra un adjunto (imagen, video o código) de una task/note/idea/doc/content de Orquestra -- limpia también el objeto en S3 si era imagen o video. Segunda excepción a "nunca borrado" (junto a delete_checklist_item) -- usalo para limpiar evidencia subida por error, no como reemplazo de mantener historial.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         entityType: z.enum(ATTACHMENT_ENTITY_TYPES).describe('Tipo de entidad dueña del adjunto'),
-        entityId: z.string().describe('ID de la entidad (task/note/idea/doc)'),
+        entityId: z.string().describe('ID de la entidad (task/note/idea/doc/content)'),
         attachmentId: z.string().describe('ID del adjunto a borrar (ver list_attachments)'),
       },
     },