orquestra-mcp 1.40.0 → 1.43.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.40.0",
+  "version": "1.43.1",
   "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/api.mjs

@@ -1,4 +1,5 @@
 import { readConfigFile, resolveProjectForCwd, CONFIG_PATH } from './configFile.mjs'
+import { request } from './http.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
 
@@ -38,12 +39,7 @@ export function loadConfig() {
   return { apiBase, apiToken, workspaceId, defaultProjectId }
 }
 
-export class ApiError extends Error {
-  constructor(status, message) {
-    super(message)
-    this.status = status
-  }
-}
+export { ApiError } from './http.mjs'
 
 function buildUrl(config, path, params) {
   const url = new URL(path, config.apiBase)
@@ -54,57 +50,29 @@ function buildUrl(config, path, params) {
   return url
 }
 
-async function parseResponse(res) {
-  const text = await res.text()
-  let body
-  try { body = text ? JSON.parse(text) : null } catch { body = text }
-
-  if (!res.ok) {
-    const message = (body && body.error) || (typeof body === 'string' ? body : `HTTP ${res.status}`)
-    throw new ApiError(res.status, message)
-  }
-  return body
-}
+// Todas pasan por request() (http.mjs, ORQ-343): plazo por intento, cancelación de la tool y
+// reintentos acotados -- las lecturas ante fallas transitorias, las escrituras solo ante el
+// throttling del API Gateway (no llegó a la Lambda, no puede duplicar nada).
+const auth = config => ({ Authorization: `Bearer ${config.apiToken}` })
+const jsonHeaders = config => ({ ...auth(config), 'Content-Type': 'application/json' })
 
 export async function apiGet(config, path, params = {}) {
-  const url = buildUrl(config, path, params)
-  const res = await fetch(url, {
-    headers: { Authorization: `Bearer ${config.apiToken}` },
-  })
-  return parseResponse(res)
+  return request(buildUrl(config, path, params), { headers: auth(config) })
 }
 
 export async function apiPost(config, path, { projectId, ...body }) {
-  const url = buildUrl(config, path, { projectId })
-  const res = await fetch(url, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${config.apiToken}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  })
-  return parseResponse(res)
+  return request(buildUrl(config, path, { projectId }), { method: 'POST', headers: jsonHeaders(config), body: JSON.stringify(body) })
 }
 
 export async function apiPatch(config, path, { projectId, id, ...body }) {
-  const url = buildUrl(config, `${path}/${id}`, { projectId })
-  const res = await fetch(url, {
-    method: 'PATCH',
-    headers: { Authorization: `Bearer ${config.apiToken}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  })
-  return parseResponse(res)
+  return request(buildUrl(config, `${path}/${id}`, { projectId }), { method: 'PATCH', headers: jsonHeaders(config), body: JSON.stringify(body) })
 }
 
 // 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)
+  return request(buildUrl(config, path, { projectId }), { method: 'PATCH', headers: jsonHeaders(config), body: JSON.stringify(body) })
 }
 
 // Único método DELETE del cliente (21 ago 2026, para delete_checklist_item
@@ -112,23 +80,25 @@ export async function apiPatchPath(config, path, { projectId, ...body }) {
 // apiPatch (arma la URL como `${path}/${id}`), sin body -- ningún delete de
 // esta API necesita mandar datos, solo identificar el recurso.
 export async function apiDelete(config, path, { projectId, id }) {
-  const url = buildUrl(config, `${path}/${id}`, { projectId })
-  const res = await fetch(url, {
-    method: 'DELETE',
-    headers: { Authorization: `Bearer ${config.apiToken}` },
-  })
-  return parseResponse(res)
+  return request(buildUrl(config, `${path}/${id}`, { projectId }), { method: 'DELETE', headers: auth(config) })
+}
+
+// DELETE sobre un recurso singleton SIN id en la ruta (ej. /v1/client-portal,
+// ORQ-332) -- mismo criterio que apiPatchPath.
+export async function apiDeletePath(config, path, { projectId }) {
+  return request(buildUrl(config, path, { projectId }), { method: 'DELETE', headers: auth(config) })
 }
 
 // PUT crudo a una presigned URL de S3 (createAttachmentUploadUrl en
 // orquestra-infra) -- a diferencia de apiGet/apiPost/etc, este request NO
 // va contra config.apiBase ni lleva el Bearer del MCP: la URL firmada YA
-// es la autorización completa.
+// es la autorización completa. Plazo más largo (sube bytes); un PUT a la
+// misma key es idempotente, pero igual no se reintenta para no duplicar
+// tiempos largos de subida.
 export async function putToPresignedUrl(uploadUrl, buffer, contentType) {
-  const res = await fetch(uploadUrl, {
-    method: 'PUT',
-    headers: { 'Content-Type': contentType },
-    body: buffer,
-  })
-  if (!res.ok) throw new Error(`Falló la subida a S3: HTTP ${res.status}`)
+  try {
+    await request(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: buffer }, { timeoutMs: 120_000, retries: 0 })
+  } catch (err) {
+    throw new Error(`Falló la subida a S3: ${err.status ? `HTTP ${err.status}` : err.message}`)
+  }
 }

package/src/http.mjs

@@ -0,0 +1,102 @@
+// fetch con plazo, cancelación y reintentos acotados (ORQ-343). Antes cada llamada era un fetch
+// sin signal: una API colgada dejaba la tool esperando para siempre y un 503 pasajero se le
+// devolvía al agente como error definitivo.
+//
+// Reglas de reintento (máx. RETRIES extra, espera progresiva con jitter, respeta Retry-After):
+// - Lecturas (GET): error de red, plazo vencido, 429 de throttling, 502/503/504.
+// - Escrituras (POST/PATCH/DELETE): SOLO el 429 de throttling del API Gateway, que garantiza que
+//   la petición no llegó a la Lambda. Un plazo vencido o un 5xx en una escritura NO se reintenta:
+//   la entidad pudo crearse y reintentar la duplicaría (la API no tiene idempotencia general).
+// - El 429 de la propia API (créditos agotados, tope de regeneraciones...) trae `error` en el
+//   body y es definitivo: no se reintenta.
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export const TIMEOUT_MS = 30_000
+export const RETRIES = 2
+const BASE_DELAY_MS = 500
+const MAX_DELAY_MS = 5_000
+const RETRY_STATUS_READ = new Set([502, 503, 504])
+
+// Signal de cancelación de la tool en curso (lo pone server.mjs por llamada) -- así no hay que
+// pasarlo a mano por las ~140 tools.
+export const cancelContext = new AsyncLocalStorage()
+
+export class ApiError extends Error {
+  constructor(status, message, { code } = {}) {
+    super(message)
+    this.status = status
+    if (code) this.code = code
+  }
+}
+
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) return reject(signal.reason)
+  const t = setTimeout(resolve, ms)
+  signal?.addEventListener('abort', () => { clearTimeout(t); reject(signal.reason) }, { once: true })
+})
+
+// AbortSignal.any no existe en Node 18 (engines >=18).
+function anySignal(signals) {
+  const ctrl = new AbortController()
+  for (const s of signals.filter(Boolean)) {
+    if (s.aborted) { ctrl.abort(s.reason); break }
+    s.addEventListener('abort', () => ctrl.abort(s.reason), { once: true })
+  }
+  return ctrl.signal
+}
+
+function backoff(attempt, retryAfter) {
+  const secs = Number(retryAfter)
+  if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1000, MAX_DELAY_MS)
+  return Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS) * (0.75 + Math.random() * 0.5)
+}
+
+async function readBody(res) {
+  const text = await res.text()
+  try { return text ? JSON.parse(text) : null } catch { return text }
+}
+
+const isGatewayThrottle = (status, body) => status === 429 && !(body && typeof body === 'object' && body.error)
+
+/**
+ * Hace la petición y devuelve el body parseado (o lanza ApiError). `timeoutMs` es por intento.
+ * `signal` (opcional) se suma al de la tool en curso.
+ */
+export async function request(url, init = {}, { timeoutMs = TIMEOUT_MS, retries = RETRIES, signal } = {}) {
+  const method = (init.method || 'GET').toUpperCase()
+  const isRead = method === 'GET' || method === 'HEAD'
+  const cancel = anySignal([signal, cancelContext.getStore()?.signal])
+
+  for (let attempt = 0; ; attempt++) {
+    const last = attempt >= retries
+    let res
+    try {
+      res = await fetch(url, { ...init, signal: anySignal([cancel, AbortSignal.timeout(timeoutMs)]) })
+    } catch (err) {
+      if (cancel.aborted) throw new ApiError(0, 'Cancelado', { code: 'cancelled' })
+      const timedOut = err?.name === 'TimeoutError' || err?.name === 'AbortError'
+      if (isRead && !last) { await sleep(backoff(attempt), cancel); continue }
+      if (timedOut) {
+        throw new ApiError(0, isRead
+          ? `La API no respondió en ${timeoutMs / 1000} s (${retries + 1} intentos)`
+          : `La API no respondió en ${timeoutMs / 1000} s. La escritura pudo haberse aplicado: revisa con la tool list_*/get_* correspondiente antes de reintentar, para no duplicarla.`,
+          { code: 'timeout' })
+      }
+      throw new ApiError(0, isRead
+        ? `No se pudo conectar con la API: ${err?.cause?.code || err?.message}`
+        : `Se perdió la conexión con la API (${err?.cause?.code || err?.message}). La escritura pudo haberse aplicado: revisa antes de reintentar.`,
+        { code: 'network' })
+    }
+
+    const body = await readBody(res)
+    if (res.ok) return body
+
+    const retryable = isGatewayThrottle(res.status, body) || (isRead && RETRY_STATUS_READ.has(res.status))
+    if (retryable && !last) {
+      await sleep(backoff(attempt, res.headers.get('retry-after')), cancel)
+      continue
+    }
+    const message = (body && body.error) || (body && body.message) || (typeof body === 'string' && body) || `HTTP ${res.status}`
+    throw new ApiError(res.status, message)
+  }
+}

package/src/server.mjs

@@ -3,7 +3,8 @@ 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, apiPatchPath, apiDelete, putToPresignedUrl, ApiError } from './api.mjs'
+import { loadConfig, apiGet, apiPost, apiPatch, apiPatchPath, apiDelete, apiDeletePath, putToPresignedUrl, ApiError } from './api.mjs'
+import { cancelContext } from './http.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 import { PLATFORM_PLAYBOOKS, TRACKING_TOOLS } from './platformPlaybooks.mjs'
@@ -31,8 +32,14 @@ const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'de
 const ACTIVITY_TYPES = ['meeting', 'call', 'followup']
 const ACTIVITY_STATUSES = ['scheduled', 'done', 'cancelled']
 const TASK_PRIORITIES = ['high', 'medium', 'low']
-// Relaciones (ORQ-326) -- misma lista que orquestra-infra/schema/enums/RelationItemType.json.
-const RELATION_TYPES = ['task', 'activity', 'note', 'doc', 'idea']
+// Relaciones (ORQ-326, ORQ-347) -- misma lista que orquestra-infra/schema/enums/RelationItemType.json.
+const RELATION_TYPES = ['task', 'activity', 'note', 'doc', 'idea', 'risk', 'content', 'changelog', 'distribution', 'service']
+// `relatedTo` en los create_* (ORQ-347): de dónde sale lo que se crea. El server valida el destino
+// antes de crear y deja el vínculo hecho (lo ve list_relations desde los dos lados).
+const RELATED_TO = z.object({
+  type: z.enum(RELATION_TYPES).describe('"task" o "activity" (reunión/llamada/seguimiento) normalmente'),
+  id: z.string().describe('id del ítem de origen'),
+}).optional().describe('De dónde sale esto (ej. el riesgo/nota/reunión/idea que surgió trabajando en una tarea: {type:"task", id}). Queda vinculado en "Relacionado" de los dos lados -- úsalo en vez de escribir "sale de ORQ-123" en el texto.')
 // Verificaciones por plataforma de una tarea (ORQ-319) -- ver
 // orquestra-infra/functions/api/lib/verifications.mjs para las reglas reales.
 const VERIFICATION_PLATFORMS = ['web', 'ios', 'android', 'api', 'other']
@@ -115,7 +122,8 @@ Durante el trabajo normal de código, sin que el usuario te lo pida explícitame
 - 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).
 - Conocimiento que sirve más allá de un proyecto (guías, procesos, decisiones transversales) va en la base del workspace: revisa list_knowledge antes de documentarlo de nuevo, créalo con create_knowledge o súbelo con promote_to_knowledge; lo de un solo proyecto sigue en notas/docs.
 - Reuniones, llamadas y seguimientos NO son tareas: son actividades (no se entregan, se programan y se registran). Usa log_activity para agendarlas o registrarlas, update_activity para marcarlas hechas con su resultado (outcome) y siguiente paso (nextStep), y list_activities para ver la agenda/bitácora -- nunca create_task con esos tipos. Si del siguiente paso sale trabajo real, eso sí es una tarea (create_task normal, con módulo y fecha).
-- Para dejar constancia de que una nota, doc, idea o tarea es DE una reunión/llamada (o de otra cosa del proyecto) -- "esta nota es de la reunión X", "esta tarea sale de este doc" --, vincúlalas con link_items en vez de meter la referencia como texto en la descripción/cuerpo; list_relations muestra todo lo relacionado de un ítem.
+- Para dejar constancia de que una nota, doc, idea, tarea, riesgo, pieza de contenido, entrada de changelog, distribución o servicio es DE otra cosa del proyecto -- "esta nota es de la reunión X", "esta tarea sale de este doc" --, vincúlalas con link_items en vez de meter la referencia como texto en la descripción/cuerpo; list_relations muestra todo lo relacionado de un ítem.
+- Si mientras trabajas en una tarea creas algo que sale de ella (un riesgo que detectaste, una reunión, una nota, una idea, una entrada de changelog...), manda relatedTo: {type:"task", id} en el create_* para que quede ligado desde el principio. Si un paso del checklist depende de otra cosa (otra tarea, un doc, un riesgo), vincúlalo desde ese ítem con link_items + checklistItemId; un folio suelto en el texto del ítem ("requiere ORQ-75") el server lo vincula solo.
 - 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.
@@ -149,12 +157,23 @@ const SCOPE_EVIDENCE = {
   doneSource: z.enum(['manual', 'github', 'sibling']).optional(),
   commitSha: z.string().optional().describe('commit que respalda que ya está hecho en esa plataforma'),
   commitUrl: z.string().optional(),
+  notApplicable: z.boolean().optional().describe('true = esta plataforma NO aplica para la tarea (cuenta como resuelta en paridad). Solo con el motivo y cuando el usuario lo decidió -- nunca para tapar trabajo pendiente.'),
+  notApplicableReason: z.string().optional().describe('Motivo de "no aplica" (obligatorio si notApplicable es true)'),
 }
 
 export function createServer() {
   const config = loadConfig()
   const server = new McpServer({ name: 'orquestra-mcp', version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS })
 
+  // Cancelación (ORQ-343): el SDK pasa `extra.signal` (último argumento del handler) y lo aborta
+  // si el cliente cancela la tool. Se publica en cancelContext para que request() lo use sin
+  // tener que pasarlo a mano por cada tool.
+  const registerTool = server.registerTool.bind(server)
+  server.registerTool = (name, def, handler) => registerTool(name, def, (...args) => {
+    const extra = args[args.length - 1]
+    return cancelContext.run({ signal: extra?.signal }, () => handler(...args))
+  })
+
   function resolveProjectId(projectId) {
     if (config.defaultProjectId) return config.defaultProjectId
     if (!projectId) {
@@ -258,7 +277,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. 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.',
+    '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.',
     {
       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.'),
@@ -625,6 +644,7 @@ export function createServer() {
     '/v1/tasks',
     'Crea una tarea en un proyecto de Orquestra. moduleId y dueDate son OBLIGATORIOS -- revisa list_modules primero (si ninguno aplica, creá uno con create_module antes de crear la tarea, nunca la dejes sin agrupar); dueDate se calcula con criterio real (prioridad/tamaño del trabajo), nunca un valor arbitrario. Una reunión, llamada o seguimiento NO es tarea: usa log_activity (type "business" sí es tarea: entregable no-código).',
     {
+      relatedTo: RELATED_TO,
       title: z.string().describe('Título de la tarea'),
       description: z.string().optional(),
       type: z.enum(TASK_TYPES).optional().describe('Default: feature'),
@@ -742,6 +762,7 @@ export function createServer() {
         time: z.string().regex(/^\d{2}:\d{2}$/, 'Formato esperado: HH:MM').optional().describe('Hora local (HH:MM, 24 h), si se sabe.'),
         activityStatus: z.enum(ACTIVITY_STATUSES).optional().describe('Default "scheduled" (programada). "done" para registrar una que ya pasó.'),
         ...ACTIVITY_FIELDS_SCHEMA,
+        relatedTo: RELATED_TO,
       },
     },
     async ({ projectId, date, time, ...body }) => {
@@ -904,7 +925,7 @@ export function createServer() {
   registerRead(
     'list_relations',
     '/v1/relations',
-    'Sección "Relacionado" de una tarea, actividad (reunión/llamada/seguimiento), nota, doc o idea: junta los vínculos manuales (link_items, source "manual", con relationId para unlink_items) Y los que ya salen de campos existentes (nota de la tarea/minuta de la reunión, nota relacionada, ADR publicado, tarea que proviene de una nota, siguiente paso de una reunión, tareas ligadas a una idea -- source = esa etiqueta, relationId null, no se pueden quitar desde acá). Sin duplicados (el manual gana) y sin extremos borrados. No incluye menciones [[...]] -- esas van en get_backlinks.',
+    'Sección "Relacionado" de una tarea, actividad (reunión/llamada/seguimiento), nota, doc, idea, riesgo, contenido, entrada de changelog, distribución o servicio: junta los vínculos manuales (link_items, source "manual", con relationId para unlink_items; source "checklist" + checklistItemId si sale de un ítem del checklist de la tarea) Y los que ya salen de campos existentes (nota de la tarea/minuta de la reunión, nota relacionada, ADR publicado, tarea que proviene de una nota, siguiente paso de una reunión, tareas ligadas a una idea -- source = esa etiqueta, relationId null, no se pueden quitar desde acá). Sin duplicados (el manual gana) y sin extremos borrados. No incluye menciones [[...]] -- esas van en get_backlinks.',
     {
       type: z.enum(RELATION_TYPES).describe('"activity" para reunión/llamada/seguimiento, "task" para cualquier otra tarea -- el server rechaza el tipo equivocado'),
       id: z.string().describe('id del ítem (de list_tasks/list_activities/list_notes/list_docs/list_ideas)'),
@@ -915,12 +936,14 @@ export function createServer() {
   registerCreate(
     'link_items',
     '/v1/relations',
-    'Vincula a mano dos cosas del mismo proyecto (tarea, actividad, nota, doc o idea) -- ej. "esta nota es de la reunión X", "esta tarea sale de este doc", "este doc documenta esa idea". El vínculo no tiene dirección (el orden a/b da igual, el server lo ordena) y es idempotente: vincular dos veces lo mismo no duplica (responde alreadyLinked). Saca los ids de list_tasks, list_activities, list_notes, list_docs y list_ideas; una reunión/llamada/seguimiento es "activity", no "task" (el server valida el tipo real y que ambos existan). No se puede vincular algo consigo mismo. Úsalo en vez de escribir "ver reunión X" en el texto.',
+    'Vincula a mano dos cosas del mismo proyecto (tarea, actividad, nota, doc, idea, riesgo, contenido, entrada de changelog, distribución o servicio) -- ej. "esta nota es de la reunión X", "esta tarea sale de este doc", "este riesgo es del backend de prod". Con checklistItemId + taskId el vínculo sale de un ÍTEM del checklist de esa tarea (ej. "este paso requiere ORQ-75"): se ve bajo el ítem y se borra con él. El vínculo no tiene dirección (el orden a/b da igual, el server lo ordena) y es idempotente: vincular dos veces lo mismo no duplica (responde alreadyLinked). Saca los ids de list_tasks, list_activities, list_notes, list_docs, list_ideas, list_risks, list_content, list_changelog, list_distributions y list_services; una reunión/llamada/seguimiento es "activity", no "task" (el server valida el tipo real y que ambos existan). No se puede vincular algo consigo mismo. Úsalo en vez de escribir "ver reunión X" en el texto.',
     {
       aType: z.enum(RELATION_TYPES).describe('Tipo del primer ítem'),
       aId: z.string().describe('id del primer ítem'),
       bType: z.enum(RELATION_TYPES).describe('Tipo del segundo ítem'),
       bId: z.string().describe('id del segundo ítem'),
+      checklistItemId: z.string().optional().describe('id del ítem del checklist (list_checklist_items) del que sale el vínculo -- requiere taskId'),
+      taskId: z.string().optional().describe('Con checklistItemId: la tarea dueña del ítem, que tiene que ser uno de los dos extremos (aType "task")'),
     }
   )
 
@@ -942,6 +965,54 @@ export function createServer() {
     }
   )
 
+  // Portal del cliente (ORQ-332, 17 oct 2026): UN link por proyecto, sin cuenta,
+  // que junta avance, aprobaciones de Contenido, docs públicos y novedades. Ver
+  // orquestra-infra/functions/api/lib/clientPortal.mjs. Ruta singleton sin id.
+  server.registerTool(
+    'get_client_portal_link',
+    {
+      description: 'Devuelve el link del portal del cliente del proyecto (una página pública, sin cuenta, para el cliente de un freelancer: avance, piezas de Contenido en revisión para aprobar o pedir cambios, lo ya aprobado, docs con visibilidad pública y novedades). `link: null` si no hay uno activo. El link es una credencial: compártelo solo con el cliente del proyecto.',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC) },
+    },
+    async ({ projectId }) => {
+      try {
+        return textResult(await apiGet(config, '/v1/client-portal', { projectId: resolveProjectId(projectId) }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'create_client_portal_link',
+    {
+      description: 'Genera el link del portal del cliente. Si ya había uno, lo REEMPLAZA: el anterior deja de funcionar para quien lo tenga -- confirma con el usuario antes de regenerar uno existente (revisa get_client_portal_link). Qué ve el cliente: avance, Contenido en estatus "review" (puede aprobar o pedir cambios), últimas 10 aprobadas, docs con visibility "public" y novedades del changelog. Nunca tareas, miembros ni notas.',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC) },
+    },
+    async ({ projectId }) => {
+      try {
+        return textResult(await apiPost(config, '/v1/client-portal', { projectId: resolveProjectId(projectId) }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'revoke_client_portal_link',
+    {
+      description: 'Revoca el link del portal del cliente: el cliente deja de poder abrirlo (por ejemplo, al terminar el proyecto o si el link se filtró). No borra nada del proyecto. Para dar acceso de nuevo, create_client_portal_link genera uno distinto.',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC) },
+    },
+    async ({ projectId }) => {
+      try {
+        return textResult(await apiDeletePath(config, '/v1/client-portal', { projectId: resolveProjectId(projectId) }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   // Fusionar tareas (20 ago 2026) -- registradas directo con
   // server.registerTool (no registerCreate/registerUpdate) porque son
   // POST a `${path}/${id}/merge|unmerge`, no un CRUD estándar. Fusión
@@ -1809,6 +1880,7 @@ export function createServer() {
     '/v1/ideas',
     'Crea una idea en un proyecto de Orquestra.',
     {
+      relatedTo: RELATED_TO,
       title: z.string().describe('Título de la idea'),
       description: z.string().optional(),
       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).'),
@@ -2007,6 +2079,7 @@ export function createServer() {
     '/v1/changelog',
     'Crea una entrada de changelog en un proyecto de Orquestra (estilo Keep a Changelog).',
     {
+      relatedTo: RELATED_TO,
       section: z.enum(CHANGELOG_SECTIONS).describe('Sección del changelog'),
       text: z.string().describe('Descripción de la entrada'),
       version: z.string().optional(),
@@ -2057,6 +2130,7 @@ export function createServer() {
     '/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.',
     {
+      relatedTo: RELATED_TO,
       title: z.string().describe('Título de la nota'),
       body: z.string().optional(),
       pinned: z.boolean().optional(),
@@ -2132,6 +2206,7 @@ export function createServer() {
     '/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.',
     {
+      relatedTo: RELATED_TO,
       type: z.enum(DOC_TYPES).optional().describe('Tipo de documento -- obligatorio salvo que mandes templateId (la plantilla trae su tipo)'),
       title: z.string().describe('Título del documento'),
       content: z.string().optional(),
@@ -2252,6 +2327,7 @@ export function createServer() {
   }
 
   registerCreate('create_service', '/v1/services', 'Crea un servicio compartido de infraestructura (backend, base de datos, auth, etc.) en un proyecto. Además de status/notes, acepta los campos específicos de cada tipo (ej. apiUrl/region para backend, engine/provider para database) -- manda solo los que apliquen a `type`.', {
+    relatedTo: RELATED_TO,
     type: z.enum(SERVICE_TYPES).describe('Tipo de servicio'),
     name: z.string().describe('Nombre del servicio'),
     status: z.enum(INFRA_STATUSES).optional().describe('Default: operational'),
@@ -2317,6 +2393,7 @@ export function createServer() {
   })
 
   registerCreate('create_distribution', '/v1/distributions', 'Crea una distribución/plataforma (iOS, Android, Web, etc.) en un proyecto.', {
+    relatedTo: RELATED_TO,
     type: z.enum(PLATFORM_TYPES).describe('Tipo de plataforma'),
     label: z.string().describe('Nombre a mostrar por default'),
     name: z.string().optional().describe('Nombre editable -- si no se manda, la UI usa label'),
@@ -2454,6 +2531,7 @@ export function createServer() {
     {}, (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).', {
+    relatedTo: RELATED_TO,
     title: z.string(),
     description: z.string().optional(),
     probability: z.enum(RISK_LEVELS).optional().describe('Default: medium'),
@@ -2480,6 +2558,7 @@ export function createServer() {
     {}, (args, projectId) => ({ projectId }))
 
   registerCreate('create_content', '/v1/content', 'Crea una pieza de contenido. Dos formas: (1) channelId suelto -- 1 canal, shape simple, seguí usándolo si solo publicás en un lado. (2) channels[] -- una pieza multi-canal con una variante por canal (cada una con su propio caption/status/fecha/desempeño), reemplaza tener que llamar esto varias veces para la "misma" publicación en distintos canales.', {
+    relatedTo: RELATED_TO,
     channelId: z.string().optional().describe('Canal donde se publica -- ver list_channels. Usalo para una pieza de 1 solo canal; si vas a publicar en varios, mandá channels[] en vez de esto.'),
     channels: z.array(CONTENT_VARIANT_SCHEMA).optional().describe('Pieza multi-canal -- una entrada por canal. No mandes channelId si usás esto.'),
     title: z.string().describe('Referencia interna, no es lo que se publica -- compartida entre todos los canales si es multi-canal'),
@@ -2557,7 +2636,7 @@ export function createServer() {
   registerRead('list_agents', '/v1/agents',
     'Lista los agentes (kind+máquina+stack+ruta local) configurados en un proyecto. Úsala antes de create_agent o de create_agent_run con stack, para saber si ya existe uno.',
     { kind: z.enum(AGENT_KINDS).optional().describe('Filtra por kind: "qa" (lint/test/build/E2E), "security" (npm audit + gitleaks), "performance" (build size + Lighthouse) o "screenshots" (captura de pantallas para el checklist de publicación, solo ios/android)') },
-    (args, projectId) => ({ projectId }))
+    (args, projectId) => ({ projectId, ...(args.kind ? { kind: args.kind } : {}) }))
 
   registerCreate('create_agent', '/v1/agents', 'Crea un agente: asocia un kind ("qa" | "security" | "performance" | "screenshots") a una máquina (runner, ver Workspace → Máquinas), un stack de este proyecto y una ruta de checkout en ESA máquina. kind="performance" además necesita perfUrl.', {
     name: z.string().describe('Nombre a mostrar, ej. "Agente web"'),