orquestra-mcp 1.47.0 → 1.49.0

package/README.md

@@ -1,6 +1,7 @@
 # orquestra-mcp
 
-Servidor MCP (Model Context Protocol) para Orquestra. Expone **135 tools**
+Servidor MCP (Model Context Protocol) para Orquestra. Expone **144 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/
 notas/docs/módulos/flujo/categorías/infra/proyectos, y corridas de QA —
@@ -47,7 +48,7 @@ vez de contra producción).
 
 ## Setup manual (alternativa, sin el flujo de navegador)
 
-Si preferís generar el token vos mismo en vez de usar `setup`:
+Si prefieres generar el token tú mismo en vez de usar `setup`:
 
 1. **Cuenta + workspace en `orquestra-web`**: entra a la app, si no tienes
    `workspaceId` te manda al wizard de onboarding.
@@ -75,7 +76,7 @@ Variables de entorno (todas opcionales si ya corriste `setup` — se leen de
 | `ORQUESTRA_API_TOKEN` | sí | — |
 | `ORQUESTRA_WORKSPACE_ID` | sí | — |
 | `ORQUESTRA_DEFAULT_PROJECT_ID` | no | — |
-| `ORQUESTRA_API_BASE` | no | `ApiBaseUrl` de producción |
+| `ORQUESTRA_API_BASE` | no | `https://api.orquestra.me` |
 | `ORQUESTRA_WEB_URL` (solo `setup`) | no | `https://app.orquestra.me` |
 
 ### Claude Code
@@ -152,23 +153,24 @@ Lectura de contexto:
 | `get_platform_playbook` | `platform` | Guía de referencia + checklist de publicación en tienda (`ios`\|`android`) — sin red |
 | `get_skills_catalog` | — | Catálogo de Claude Skills de terceros recomendadas — sin red |
 | `preview_skill` | `key?` / `sourceRepo?`+`sourcePath?` | Trae el SKILL.md real de una skill de terceros, sin instalar nada |
-| `install_skill` | `key?` / `sourceRepo?`+`sourcePath?`, `scope`, `confirmed` | Descarga e instala una skill en `.claude/skills/` — solo después de `preview_skill` + confirmación del usuario; además registra la instalación en Orquestra (best-effort) |
+| `install_skill` | `key?` / `sourceRepo?`+`sourcePath?`, `scope`, `confirmed` | Descarga e instala una skill en `.claude/skills/{key}/` de la carpeta actual (`scope:'project'`) o en `~/.claude/skills/{key}/` (`scope:'global'`) — solo después de `preview_skill` + confirmación del usuario; además registra la instalación en Orquestra (best-effort) |
 | `list_installed_skills` | `projectId?` | Registros reales de skills instaladas en el proyecto (colección `skills`, no el catálogo) |
 | `create_skill_install` / `update_skill_install` | ver server.mjs | Self-report manual de una skill instalada a mano, fuera del flujo de `install_skill` |
 | `get_setup_guide` | — | Orden recomendado (flujo→categorías→infra→módulos→tareas→ideas→notas→changelog→docs) para configurar/sincronizar sin duplicar — sin red |
 | `list_modules` / `list_statuses` / `list_categories` / `list_services` / `list_environments` / `list_distributions` | `projectId?` | Lista completa de cada entidad — revísalos antes de `create_*` para no duplicar (patrón upsert) |
 
 Creación (`create_*`) y edición (`update_*`) — mismo patrón en todos, solo
-crear/editar, sin `delete_*`:
+crear/editar (los únicos borrados acotados están en "Estado", abajo). Tabla
+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` |
-| Ideas | `create_idea` | |
-| Changelog | `create_changelog_entry` | Estilo Keep a Changelog |
-| Notas | `create_note` | |
-| Docs | `create_doc` | |
+| 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` | |
+| Docs | `create_doc`, `get_doc`, `update_doc` | |
 | Módulos | `create_module`, `update_module` | `scope` también editable |
 | Flujo (estatus) | `create_status`, `update_status` | `nextIds` define las transiciones válidas |
 | Categorías | `create_category`, `update_category` | |
@@ -181,7 +183,7 @@ Compuestas:
 | Tool | Args | Descripción |
 |---|---|---|
 | `init_project` | `name`, `description?`, `phase?`, `projectType?`, `distributions?`, `categories?` | Crea un proyecto nuevo en el workspace — categorías+distribuciones+flujo conectado en un paso |
-| `apply_stage_playbook` | `stageId`, `moduleName?`, `includeDates?` | Crea el módulo + todas las tareas de la plantilla de una etapa |
+| `apply_stage_playbook` | `stageId`, `moduleName?` | Crea el módulo + todas las tareas de la plantilla de una etapa |
 
 Los campos enum (`type`, `priority`, `status`, etc.) están fijos y
 documentados en el `inputSchema` de cada tool — el modelo los ve sin
@@ -227,7 +229,7 @@ create/update sigue siendo criterio del agente y del humano.
 
 ## Estado
 
-135 tools: lectura (contexto, dashboard, workspace, infra, paridad, standup,
+144 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,
@@ -236,6 +238,8 @@ infraestructura, proyecto, contenido (canales, campañas, contenido,
 Postproxy), agentes, skills, sugerencias y vínculos entre ítems
 (`link_items`/`unlink_items`/`list_relations`) + compuestas (init_project,
 apply_stage_playbook, apply_platform_playbook, install_skill). Sin
-`delete_*` salvo adjuntos, ítems de checklist, verificaciones y vínculos
-(`unlink_items`). Publicado en npm como
+`delete_*` salvo adjuntos, ítems de checklist, verificaciones, vínculos
+(`unlink_items`) y el link del portal del cliente (`revoke_client_portal_link`).
+Comando extra de CLI (no tool): `npx orquestra-mcp vault sync <carpeta> [--apply]`
+(base de conocimiento ↔ vault de Obsidian). Publicado en npm como
 `orquestra-mcp` (unscoped) -- `npx orquestra-mcp setup`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.47.0",
+  "version": "1.49.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",
   "type": "module",
   "bin": {

package/src/server.mjs

@@ -89,7 +89,7 @@ const SETUP_GUIDE = {
     { 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' },
+    { step: 9, section: 'Docs', check: 'search', createOrUpdate: 'create_doc / update_doc (get_doc para leer el texto completo)', matchBy: 'title' },
   ],
 }
 
@@ -293,7 +293,7 @@ export function createServer() {
   registerRead(
     'search',
     '/v1/search',
-    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas y docs de un proyecto de Orquestra. También por folio ("ORQ-123", la exacta sale primero) y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
+    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas y docs de un proyecto de Orquestra. También por folio ("ORQ-123") o por clave de módulo ("AUTH-3") -- la exacta sale primero -- y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: 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', 'activity', 'note', 'idea', 'doc', 'knowledge'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
@@ -768,6 +768,7 @@ export function createServer() {
       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.'),
       parityExempt: z.boolean().optional().describe('true = este trabajo es de UNA sola plataforma y no cuenta en get_parity_summary (se pone solo cuando skipParity va con scope de una sola dist). false para volver a contarla.'),
       parityOf: z.string().optional().describe('Folio: id de la tarea ORIGEN de la que esta es la hermana para otra plataforma (ej. la versión iOS de una tarea de Android). En paridad cuentan como UN item y al cerrar esta, su plataforma queda hecha en el origen. El origen no puede ser hermana de otra. "" lo quita.'),
+      moduleCode: z.string().max(40).optional().describe('Clave de la tarea dentro de su módulo (ej. "AUTH-3"), ADEMÁS del folio ORQ-N. NO la mandes normalmente: si el módulo tiene clave (key), el server la asigna sola. Solo para conservar la clave que ya traía de otro sistema al importar (ej. "PROJ-128" de Jira/Linear).'),
       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.'),
@@ -813,6 +814,7 @@ export function createServer() {
         .describe('Alcance por distribución -- usa get_parity_summary para ver el scope actual antes de editarlo'),
       parityExempt: z.boolean().optional().describe('true = este trabajo es de UNA sola plataforma y no cuenta en get_parity_summary; false para volver a contarla.'),
       parityOf: z.string().optional().describe('Folio: id de la tarea ORIGEN de la que esta es la hermana para otra plataforma (ej. la versión iOS de una tarea de Android). En paridad cuentan como UN item y al cerrar esta, su plataforma queda hecha en el origen. El origen no puede ser hermana de otra. "" lo quita.'),
+      moduleCode: z.string().max(40).optional().describe('Clave de la tarea dentro de su módulo (ej. "AUTH-3"), texto libre editable a mano. "" la quita. Mover la tarea a otro módulo (moduleId) NO la cambia: la clave es estable.'),
       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.'),
@@ -2333,10 +2335,41 @@ export function createServer() {
     }
   )
 
+  // Editar docs (ORQ-409): get_doc trae el texto completo (search solo da fragmentos) para que
+  // update_doc no pise el contenido con una versión recortada.
+  server.registerTool(
+    'get_doc',
+    {
+      description: 'Lee un documento completo del proyecto (contenido, tipo, carpeta, módulo, visibilidad). Úsala antes de update_doc: content se reemplaza entero, así que parte del texto actual. El id sale de search (types=["doc"]).',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), id: z.string() },
+    },
+    async ({ projectId, id }) => {
+      try { return textResult(await apiGet(config, `/v1/docs/${id}`, { projectId: resolveProjectId(projectId) })) } catch (err) { return errorResult(err) }
+    }
+  )
+
+  registerUpdate('update_doc', '/v1/docs',
+    'Edita un documento existente. Solo se cambian los campos que mandes; content REEMPLAZA el texto entero (lee primero con get_doc y manda el documento completo, no solo el cambio). La versión anterior queda en el historial del doc ("Versiones"). Si cambias el título, los [[Título viejo]] de todo el proyecto se reescriben solos.',
+    {
+      title: z.string().optional(),
+      content: z.string().optional().describe('Markdown completo del doc. [[Título]] enlaza otra nota, doc, tarea o idea.'),
+      type: z.enum(DOC_TYPES).optional(),
+      adrStatus: z.enum(ADR_STATUSES).optional().describe('Solo para type=\'adr\'.'),
+      adrContext: z.string().optional().describe('Solo para type=\'adr\'.'),
+      adrConsequences: z.string().optional().describe('Solo para type=\'adr\'.'),
+      moduleId: z.string().optional(),
+      folder: z.enum(DOC_FOLDERS).optional(),
+      visibility: z.enum(DOC_VISIBILITY).optional().describe('"team" | "workspace" | "public" (expone el doc sin sesión).'),
+      reviewOwnerUid: z.string().optional(),
+      reviewIntervalDays: z.number().optional(),
+    }
+  )
+
   // ═══ ESCRITURA (nivel B -- módulos, flujo, categorías, infra) ═══════════════
 
   const SCOPE_SCHEMA = z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean().optional(), ...SCOPE_EVIDENCE })).optional()
 
+  const MODULE_KEY = z.string().optional().describe('Clave del módulo (ej. "AUTH", "PAGOS"): 2-10 letras/números, empieza con letra, única en el proyecto. Numera sus tareas (AUTH-1, AUTH-2...) en moduleCode, además del folio ORQ-N. Solo si el usuario la pidió o el proyecto ya usa claves -- no la inventes.')
   registerCreate('create_module', '/v1/modules', 'Crea un módulo en un proyecto de Orquestra.', {
     name: z.string().describe('Nombre del módulo'),
     description: z.string().optional(),
@@ -2349,6 +2382,7 @@ export function createServer() {
     ownerUid: z.string().optional().describe('uid del miembro responsable del avance del módulo'),
     dependsOnModuleIds: z.array(z.string()).optional().describe('IDs de módulos de los que este depende (dependencia planeada, manual)'),
     closureCriteria: z.string().optional().describe('Texto libre: cuándo se considera verdaderamente cerrado'),
+    key: MODULE_KEY,
   })
   registerUpdate('update_module', '/v1/modules', 'Edita un módulo existente (incluido su scope multiplataforma).', {
     name: z.string().optional(),
@@ -2362,6 +2396,7 @@ export function createServer() {
     ownerUid: z.string().optional().describe('uid del miembro responsable del avance del módulo'),
     dependsOnModuleIds: z.array(z.string()).optional().describe('IDs de módulos de los que este depende (dependencia planeada, manual)'),
     closureCriteria: z.string().optional().describe('Texto libre: cuándo se considera verdaderamente cerrado'),
+    key: MODULE_KEY.describe(`${MODULE_KEY.description} Poner o cambiar la clave numera las tareas del módulo que todavía no tienen una (por orden de creación; la respuesta trae assignedCodes). "" la quita: las tareas conservan la suya.`),
   })
 
   registerCreate('create_status', '/v1/statuses', 'Crea un estatus (columna del flujo de tareas) en un proyecto.', {