orquestra-mcp 1.48.0 → 1.50.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.48.0",
+  "version": "1.50.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

@@ -25,6 +25,8 @@ function textResult(data) {
 }
 
 const PROJECT_ID_DESC = 'ID del proyecto dentro del workspace configurado. Si hay un proyecto default configurado (via "setup" o ORQUESTRA_DEFAULT_PROJECT_ID), este argumento se ignora -- el server queda fijo a ese proyecto y no puede leer/escribir otro.'
+// ORQ-411: los textos largos de idea, riesgo y módulo también cuentan para [[...]] y "Mencionado en".
+const WIKILINK_DESC = 'Admite [[Título]], [[Título|texto]] o [[ORQ-123]] para enlazar otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto.'
 
 const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'design', 'security', 'meeting', 'call', 'followup', 'business']
 // Actividades (ORQ-295): reunión/llamada/seguimiento. 'business' sigue siendo tarea (entregable). Mismas listas que
@@ -89,7 +91,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' },
   ],
 }
 
@@ -1008,10 +1010,10 @@ export function createServer() {
   registerRead(
     'get_backlinks',
     '/v1/backlinks',
-    'Backlinks ("Mencionado en"): qué notas, docs, tareas e ideas enlazan con [[...]] a la entidad pedida. Útil antes de editar o cerrar algo para ver qué depende de eso.',
+    'Backlinks ("Mencionado en"): qué notas, docs, tareas, reuniones, ideas, riesgos y módulos enlazan con [[...]] a la entidad pedida (también cuentan los puntos a revisar de una reunión y las instrucciones de las verificaciones). Útil antes de editar o cerrar algo para ver qué depende de eso.',
     {
-      type: z.enum(['note', 'doc', 'task', 'idea']),
-      id: z.string().describe('id de la nota/doc/tarea/idea'),
+      type: z.enum(['note', 'doc', 'task', 'activity', 'idea', 'risk', 'module', 'content', 'distribution']).describe('"activity" para reunión/llamada/seguimiento'),
+      id: z.string().describe('id del ítem'),
     },
     (args, projectId) => ({ projectId, type: args.type, id: args.id })
   )
@@ -1993,7 +1995,7 @@ export function createServer() {
     {
       relatedTo: RELATED_TO,
       title: z.string().describe('Título de la idea'),
-      description: z.string().optional(),
+      description: z.string().optional().describe(WIKILINK_DESC),
       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'),
@@ -2014,7 +2016,7 @@ export function createServer() {
 
   registerUpdate('update_idea', '/v1/ideas', 'Edita una idea existente. Todos los campos son opcionales -- solo se cambian los que mandes.', {
     title: z.string().optional(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     priority: z.enum(TASK_PRIORITIES).optional(),
     categoryId: z.string().optional(),
     dueDate: z.string().optional().describe('YYYY-MM-DD'),
@@ -2236,14 +2238,19 @@ export function createServer() {
     'Lista TODAS las notas de un proyecto de Orquestra, con todos sus campos -- a diferencia de get_project_context/search (resumen recortado), útil para auditar o encontrar el id exacto antes de update_note.',
     {}, (args, projectId) => ({ projectId }))
 
+  // ORQ-414: puntos de la idea, mismo shape que agendaItems de las actividades.
+  const NOTE_ITEMS = z.array(z.union([z.string(), z.object({ id: z.string().optional(), text: z.string() })])).optional()
+    .describe('Puntos de la idea, debajo de la descripción (body). Lista simple, NO checklist (sin palomitas). Reemplaza la lista COMPLETA: para agregar uno, lee la actual con list_notes y manda todos (con sus id para conservarlos).')
+
   registerCreate(
     'create_note',
     '/v1/notes',
-    'Crea una nota en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea o idea del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
+    'Crea una nota en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
     {
       relatedTo: RELATED_TO,
       title: z.string().describe('Título de la nota'),
-      body: z.string().optional(),
+      body: z.string().optional().describe('Descripción de la nota.'),
+      noteItems: NOTE_ITEMS,
       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)'),
@@ -2265,6 +2272,7 @@ export function createServer() {
     {
       title: z.string().optional(),
       body: z.string().optional(),
+      noteItems: NOTE_ITEMS,
       pinned: z.boolean().optional(),
       moduleId: z.string().optional(),
       taskId: z.string().optional(),
@@ -2315,7 +2323,7 @@ export function createServer() {
   registerCreate(
     'create_doc',
     '/v1/docs',
-    'Crea un documento en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea o idea del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
+    'Crea un documento en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
     {
       relatedTo: RELATED_TO,
       type: z.enum(DOC_TYPES).optional().describe('Tipo de documento -- obligatorio salvo que mandes templateId (la plantilla trae su tipo)'),
@@ -2335,6 +2343,36 @@ 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, reunión, idea, riesgo, módulo, contenido o distribución.'),
+      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()
@@ -2342,7 +2380,7 @@ export function createServer() {
   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(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     statusId: z.string().optional(),
     categoryId: z.string().optional(),
     scope: SCOPE_SCHEMA.describe('Alcance por distribución, ej: [{distId, layer, done}]'),
@@ -2351,12 +2389,12 @@ export function createServer() {
     shippedVersion: z.string().optional().describe('Versión del changelog en la que se envió, ej: "1.4.0"'),
     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'),
+    closureCriteria: z.string().optional().describe(`Texto libre: cuándo se considera verdaderamente cerrado. ${WIKILINK_DESC}`),
     key: MODULE_KEY,
   })
   registerUpdate('update_module', '/v1/modules', 'Edita un módulo existente (incluido su scope multiplataforma).', {
     name: z.string().optional(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     statusId: z.string().optional(),
     categoryId: z.string().optional(),
     scope: SCOPE_SCHEMA,
@@ -2365,7 +2403,7 @@ export function createServer() {
     shippedVersion: z.string().optional().describe('Versión del changelog en la que se envió, ej: "1.4.0"'),
     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'),
+    closureCriteria: z.string().optional().describe(`Texto libre: cuándo se considera verdaderamente cerrado. ${WIKILINK_DESC}`),
     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.`),
   })
 
@@ -2648,10 +2686,10 @@ export function createServer() {
   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).', {
     relatedTo: RELATED_TO,
     title: z.string(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     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'),
+    mitigation: z.string().optional().describe(`Plan o texto libre de qué se hace para reducir este riesgo. ${WIKILINK_DESC}`),
     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)'),
@@ -2659,10 +2697,10 @@ export function createServer() {
 
   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(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     probability: z.enum(RISK_LEVELS).optional(),
     impact: z.enum(RISK_LEVELS).optional(),
-    mitigation: z.string().optional(),
+    mitigation: z.string().optional().describe(WIKILINK_DESC),
     status: z.enum(RISK_STATUSES).optional(),
     ownerUid: z.string().optional(),
     moduleId: z.string().optional(),