orquestra-mcp 1.50.0 → 1.51.0

package/bin/orquestra-mcp.mjs

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer, createSetupNeededServer } from '../src/server.mjs'
 import { runSetup } from '../src/setup.mjs'
 import { runVaultSync } from '../src/vaultSync.mjs'
+import { startUpdateCheck } from '../src/updateCheck.mjs'
 
 const HELP_TEXT = `orquestra-mcp -- Servidor MCP de Orquestra (132 tools)
 
@@ -10,6 +11,9 @@ Uso:
   npx orquestra-mcp            Inicia el servidor MCP por stdio -- lo usa tu cliente
                                 MCP (Claude Code, Claude Desktop, etc.), no se corre a mano
   npx orquestra-mcp setup      Login por navegador + conecta esta carpeta a un proyecto
+  npx orquestra-mcp setup --agent codex
+                                Lo mismo para una herramienta puntual (claude-code, codex,
+                                cursor, gemini-cli...): cada una firma con su propio agente
   npx orquestra-mcp vault sync <carpeta> [--apply]
                                 Sincroniza la base de conocimiento del workspace con una
                                 carpeta de tu vault de Obsidian (la 1ra vez solo muestra el plan)
@@ -17,7 +21,8 @@ Uso:
 
 Config (la deja lista "setup"): ~/.orquestra/mcp-config.json
 Alternativa manual (variables de entorno): ORQUESTRA_API_TOKEN, ORQUESTRA_WORKSPACE_ID,
-ORQUESTRA_DEFAULT_PROJECT_ID
+ORQUESTRA_DEFAULT_PROJECT_ID. ORQUESTRA_AGENT elige el token de una herramienta
+(ej. codex) cuando la carpeta tiene varias conectadas.
 
 Docs completas: https://orquestra.me/mcp
 `
@@ -31,7 +36,8 @@ async function main() {
   }
 
   if (cmd === 'setup') {
-    await runSetup()
+    const agentIdx = process.argv.indexOf('--agent')
+    await runSetup({ agent: agentIdx > 0 ? process.argv[agentIdx + 1] : process.env.ORQUESTRA_AGENT })
     return
   }
 
@@ -45,6 +51,9 @@ async function main() {
     return
   }
 
+  // Sin await: el aviso de versión nueva no debe atrasar el arranque.
+  startUpdateCheck()
+
   let server
   try {
     server = createServer()

package/package.json

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

@@ -1,4 +1,4 @@
-import { readConfigFile, resolveProjectForCwd, CONFIG_PATH } from './configFile.mjs'
+import { readConfigFile, resolveProjectForCwd, entryForAgent, agentKey, CONFIG_PATH } from './configFile.mjs'
 import { request } from './http.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
@@ -8,7 +8,19 @@ export function loadConfig() {
   // Todo sale de la MISMA carpeta mapeada (ver resolveProjectForCwd) --
   // apiToken/workspaceId/projectId siempre son de una sola cuenta, nunca
   // el token de una carpeta con el proyecto de otra.
-  const folderConfig = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  const folderEntry = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  // ORQUESTRA_AGENT (ORQ-415) elige el token de esa herramienta en la
+  // carpeta. Si no está conectada falla explícito: caer al token default
+  // haría que sus cambios queden firmados por otra herramienta.
+  const agent = agentKey(process.env.ORQUESTRA_AGENT)
+  const folderConfig = agent ? entryForAgent(folderEntry, agent) : folderEntry
+  if (agent && folderEntry && !folderConfig && !process.env.ORQUESTRA_API_TOKEN) {
+    throw new Error(
+      `La herramienta "${process.env.ORQUESTRA_AGENT}" (ORQUESTRA_AGENT) no está conectada en esta carpeta (${process.cwd()}), ` +
+      `solo otras. Para que sus cambios queden a su nombre y no al de otra herramienta, abre una terminal aquí, ` +
+      `corre "npx orquestra-mcp@latest setup" y elige esa herramienta; después reconecta el MCP.`
+    )
+  }
 
   const apiBase = process.env.ORQUESTRA_API_BASE || folderConfig?.apiBase || DEFAULT_API_BASE
   const apiToken = process.env.ORQUESTRA_API_TOKEN || folderConfig?.apiToken

package/src/configFile.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { homedir } from 'os'
+import { homedir, hostname } from 'os'
+import { randomBytes } from 'crypto'
 import { join, dirname, win32, posix } from 'path'
 
 export const CONFIG_PATH = join(homedir(), '.orquestra', 'mcp-config.json')
@@ -45,19 +46,104 @@ export function writeConfigFile(data) {
   writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2), { mode: 0o600 })
 }
 
+// Identidad por herramienta (ORQ-415): cada herramienta (Claude Code, Codex,
+// Cursor...) tiene su propio token -- su propio agente en Orquestra -- aunque
+// trabajen en la misma carpeta. La entrada de la carpeta guarda la conexión
+// "default" arriba (la que se usa sin ORQUESTRA_AGENT) con `agent` = su
+// herramienta, y todas en `agents[clave]`. Una entrada de antes de ORQ-415 no
+// trae `agent`: su token es el de "Claude Code", el default histórico.
+// Mismo slug que agentSlug() de bootstrap.mjs en orquestra-infra.
+export function agentKey(label) {
+  return String(label || '')
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+const LEGACY_AGENT = 'claude-code'
+const defaultAgentOf = entry => entry?.agent || (entry?.apiToken ? LEGACY_AGENT : null)
+const connectionOf = ({ apiBase, apiToken, workspaceId, projectId }) => ({ apiBase, apiToken, workspaceId, projectId })
+
+// La conexión de UNA herramienta dentro de la entrada de una carpeta, o null
+// si esa herramienta nunca se conectó ahí (nunca cae al token de otra: eso
+// es justo lo que hacía firmar a Codex como Claude Code).
+export function entryForAgent(entry, key) {
+  if (!entry || !key) return entry
+  if (entry.agents?.[key]) return entry.agents[key]
+  return defaultAgentOf(entry) === key ? connectionOf(entry) : null
+}
+
 // Guarda/actualiza la cuenta+proyecto de UNA carpeta sin pisar las demás --
 // setup se puede correr varias veces, una por cada carpeta contenedora de
 // repos (ver resolveProjectForCwd), y cada corrida solo debe tocar su
 // propia entrada -- incluida la cuenta (apiToken/workspaceId), para poder
 // tener una carpeta en una cuenta de Orquestra y otra carpeta en otra
-// cuenta distinta al mismo tiempo.
-export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId }) {
+// cuenta distinta al mismo tiempo. Con `agent` solo toca la conexión de esa
+// herramienta: la default de la carpeta cambia únicamente si era la misma
+// herramienta (o la carpeta no tenía ninguna).
+export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId, agent }) {
   const existing = readConfigFile() || { projects: {} }
   const projects = { ...(existing.projects || {}) }
-  projects[folderPath] = { apiBase, apiToken, workspaceId, projectId }
+  const conn = { apiBase, apiToken, workspaceId, projectId }
+  if (!agent) {
+    projects[folderPath] = conn
+  } else {
+    const prev = projects[folderPath]
+    const agents = { ...(prev?.agents || {}), [agent]: conn }
+    const keepDefault = prev && defaultAgentOf(prev) && defaultAgentOf(prev) !== agent
+    projects[folderPath] = keepDefault
+      ? { ...connectionOf(prev), agent: defaultAgentOf(prev), agents }
+      : { ...conn, agent, agents }
+  }
   writeConfigFile({ projects })
 }
 
+// El setup de una herramienta ya conocida en esta máquina revoca su token
+// anterior (bootstrap en orquestra-infra): hay que ponerle el nuevo a TODAS
+// las carpetas donde esa herramienta usa el mismo workspace, no solo a la del
+// setup, o las demás quedarían con un token muerto. Devuelve las carpetas.
+export function replaceAgentToken({ workspaceId, agent, apiToken }) {
+  const existing = readConfigFile()
+  if (!existing?.projects) return []
+  const updated = []
+  for (const [folderPath, entry] of Object.entries(existing.projects)) {
+    let touched = false
+    if (defaultAgentOf(entry) === agent && entry.workspaceId === workspaceId) { entry.apiToken = apiToken; touched = true }
+    const own = entry.agents?.[agent]
+    if (own && own.workspaceId === workspaceId) { own.apiToken = apiToken; touched = true }
+    if (touched) updated.push(folderPath)
+  }
+  if (updated.length) writeConfigFile(existing)
+  return updated
+}
+
+// Herramientas ya conectadas en esta máquina (en cualquier carpeta).
+export function connectedAgents() {
+  const keys = new Set()
+  for (const entry of Object.values(readConfigFile()?.projects || {})) {
+    if (defaultAgentOf(entry)) keys.add(defaultAgentOf(entry))
+    for (const key of Object.keys(entry.agents || {})) keys.add(key)
+  }
+  return keys
+}
+
+// Identidad de la máquina (ORQ-415): un id aleatorio, no el serial ni la MAC
+// -- solo distingue esta instalación ("Codex · MacBook-Pro" vs "Codex ·
+// Mac-mini"). Se crea una vez y se reusa en cada setup.
+export const MACHINE_PATH = join(homedir(), '.orquestra', 'machine.json')
+
+export function readOrCreateMachine() {
+  try {
+    const saved = JSON.parse(readFileSync(MACHINE_PATH, 'utf8'))
+    if (/^[a-f0-9]{16,64}$/.test(saved.id)) return { id: saved.id, name: saved.name || hostname().replace(/\.local$/, '') }
+  } catch {}
+  const machine = { id: randomBytes(8).toString('hex'), name: hostname().replace(/\.local$/, '') }
+  mkdirSync(dirname(MACHINE_PATH), { recursive: true })
+  writeFileSync(MACHINE_PATH, JSON.stringify(machine, null, 2), { mode: 0o600 })
+  return machine
+}
+
 // Busca, subiendo desde cwd hacia la raíz, la carpeta mapeada más específica
 // -- mismo criterio que .editorconfig/.gitconfig: el ancestro más cercano
 // gana, así que un repo individual con su propio mapeo (y su propia cuenta)

package/src/server.mjs

@@ -5,6 +5,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import { loadConfig, apiGet, apiPost, apiPatch, apiPatchPath, apiDelete, apiDeletePath, putToPresignedUrl, ApiError } from './api.mjs'
 import { cancelContext } from './http.mjs'
+import { updateNotice } from './updateCheck.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 import { PLATFORM_PLAYBOOKS, TRACKING_TOOLS } from './platformPlaybooks.mjs'
@@ -104,7 +105,7 @@ const SETUP_GUIDE = {
 // preguntar en vez de adivinar.
 const SERVER_INSTRUCTIONS = `Este server conecta con Orquestra, la app de gestión de proyectos del usuario -- úsalo para mantener su proyecto sincronizado con el trabajo real, sin que tenga que pedírtelo cada vez.
 
-Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje.
+Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje. Si trae orquestraMcpUpdate, avísale al usuario UNA sola vez en la sesión que hay una versión nueva de este MCP y cómo actualizar (usa su campo message), sin interrumpir lo que estaba pidiendo.
 
 Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es la primera vez que se usa este MCP aquí -- pero "vacío en Orquestra" NO significa "recién empezado en la realidad". Antes de ofrecer nada, pregúntale al usuario: ¿este proyecto es una idea nueva, o ya existe y solo lo estás conectando por primera vez? Según la respuesta:
 - Si es una idea nueva: llama a get_setup_guide y ofrece un playbook de etapa "pre" (get_stage_playbook + apply_stage_playbook) -- ahí sí basta con eso, el proyecto de verdad no tiene nada más que sincronizar todavía.
@@ -175,7 +176,10 @@ export function createSetupNeededServer(reason) {
   server.registerTool('diagnostico_conexion', {
     description: 'Explica por qué Orquestra no está conectado en esta carpeta y cómo arreglarlo.',
     inputSchema: {},
-  }, async () => ({ content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}` }] }))
+  }, async () => {
+    const update = updateNotice(PKG_VERSION)
+    return { content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}${update ? `\n\n${update.message}` : ''}` }] }
+  })
   return server
 }
 
@@ -205,14 +209,14 @@ export function createServer() {
     return projectId
   }
 
-  function registerRead(name, path, description, extraSchema, buildParams) {
+  function registerRead(name, path, description, extraSchema, buildParams, decorate = data => data) {
     server.registerTool(
       name,
       { description, inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), ...extraSchema } },
       async (args) => {
         try {
           const data = await apiGet(config, path, buildParams(args, resolveProjectId(args.projectId)))
-          return textResult(data)
+          return textResult(decorate(data))
         } catch (err) {
           return errorResult(err)
         }
@@ -264,7 +268,11 @@ export function createServer() {
     '/v1/context',
     'Resumen compacto del estado de un proyecto de Orquestra: fase, plataformas, tareas abiertas/vencidas/bloqueadas, módulos, ideas y changelog reciente.',
     {},
-    (args, projectId) => ({ projectId })
+    (args, projectId) => ({ projectId }),
+    data => {
+      const update = updateNotice(PKG_VERSION)
+      return update ? { ...data, orquestraMcpUpdate: update } : data
+    }
   )
 
   registerRead(
@@ -295,10 +303,10 @@ 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") 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.',
+    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas, docs, riesgos, módulos, contenido y distribuciones de un proyecto de Orquestra -- en los mismos campos que pueden tener [[wikilinks]] (descripción, mitigación, criterios de cierre, puntos, verificaciones...). 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.'),
+      types: z.array(z.enum(['task', 'activity', 'note', 'idea', 'doc', 'knowledge', 'risk', 'module', 'content', 'distribution'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
     },
     (args, projectId) => ({ projectId, q: args.q, types: args.types?.join(',') })
   )

package/src/setup.mjs

@@ -4,7 +4,7 @@ import { exec } from 'child_process'
 import { createInterface } from 'readline'
 import { homedir } from 'os'
 import { resolve } from 'path'
-import { upsertProjectMapping, CONFIG_PATH } from './configFile.mjs'
+import { upsertProjectMapping, replaceAgentToken, connectedAgents, readOrCreateMachine, agentKey, CONFIG_PATH } from './configFile.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
 const DEFAULT_WEB_URL = 'https://app.orquestra.me'
@@ -15,12 +15,16 @@ function openBrowser(url) {
   exec(`${cmd} "${url}"`, () => {})
 }
 
+// Herramientas conocidas (ORQ-415): cada una queda como su propio agente en
+// Orquestra ("Codex · MacBook-Pro") y con su propio token en la carpeta.
+const TOOLS = ['Claude Code', 'Codex', 'Cursor', 'Gemini CLI', 'Claude Desktop']
+
 function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer) }))
 }
 
-export async function runSetup() {
+export async function runSetup({ agent: presetAgent } = {}) {
   const apiBase = process.env.ORQUESTRA_API_BASE || DEFAULT_API_BASE
   const webUrl = process.env.ORQUESTRA_WEB_URL || DEFAULT_WEB_URL
   const state = randomBytes(16).toString('hex')
@@ -75,8 +79,9 @@ export async function runSetup() {
   const idToken = await idTokenPromise
   console.log('Login recibido, configurando...')
 
-  const agentLabelAnswer = await prompt('¿Cómo se llama este agente/herramienta? [Claude Code]: ')
-  const agentLabel = agentLabelAnswer.trim() || 'Claude Code'
+  const machine = readOrCreateMachine()
+  const agentLabel = await chooseTool(presetAgent, machine)
+  const agent = agentKey(agentLabel)
 
   // askIfMissing: si no hay workspace la API no crea nada solo -- avisa
   // (needsWorkspace) y aquí se le pide el nombre al usuario.
@@ -84,7 +89,7 @@ export async function runSetup() {
     const res = await fetch(`${apiBase}/v1/bootstrap`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${idToken}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ agentLabel, askIfMissing: true, ...extra }),
+      body: JSON.stringify({ agentLabel, machineId: machine.id, machineName: machine.name, askIfMissing: true, ...extra }),
     })
     const body = await res.json()
     if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
@@ -123,6 +128,14 @@ export async function runSetup() {
   }
 
   const { workspaceId, token, projects } = body
+  // La API anterior a ORQ-415 no manda `agent`.
+  // El token anterior ya quedó revocado en el servidor: se reemplaza en todas
+  // las carpetas de esta herramienta AHORA, antes de las preguntas, para que
+  // cancelar el setup a la mitad no deje carpetas con un token muerto.
+  const renewedFolders = body.agent?.known ? replaceAgentToken({ workspaceId, agent, apiToken: token }) : []
+  if (body.agent?.known) console.log(`\nYa te conocía: "${body.agent.name}". Renové su token (el anterior quedó revocado).`)
+  else if (body.agent?.adopted) console.log(`\nTu agente "${agentLabel}" de antes quedó ligado a esta máquina como "${body.agent.name}".`)
+  else if (body.agent) console.log(`\nNuevo agente en tu equipo de Orquestra: "${body.agent.name}".`)
   // La API de producción anterior a ORQ-388 no manda workspaceName.
   const wsLabel = body.workspaceName ? ` del workspace "${body.workspaceName}"` : ''
   let defaultProjectId
@@ -173,20 +186,64 @@ export async function runSetup() {
     : folderAnswer.trim()
   const folderPath = expanded ? resolve(expanded) : process.cwd()
 
-  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId })
-  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto -- guardado en ${CONFIG_PATH}.`)
-  // En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
-  // Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
-  // versión vieja de su caché.
-  const isWindows = process.platform === 'win32'
-  console.log('\nSiguiente paso -- conéctalo a tu agente de IA:\n')
-  console.log('  Claude Code:')
-  console.log(`    claude mcp add orquestra -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest`)
-  if (isWindows) console.log('    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)')
-  console.log('    Después reinicia Claude Code o reconéctalo con /mcp.\n')
-  console.log(`  Claude Desktop -- agrega esto a ${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json:`)
-  console.log('    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"] } } }\n')
-  console.log('  ¿Usas Cursor, ChatGPT/Codex o Gemini CLI? La config de cada uno está en:')
-  console.log('    https://www.orquestra.me/mcp#instalacion\n')
+  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId, agent })
+  const others = renewedFolders.filter(f => f !== folderPath)
+  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto con ${agentLabel} -- guardado en ${CONFIG_PATH}.`)
+  if (others.length) console.log(`También actualicé el token de ${agentLabel} en: ${others.join(', ')}.`)
+  console.log('\nSiguiente paso -- conéctalo a tu herramienta (si ya estaba conectada, solo reconecta el MCP):\n')
+  console.log(connectionHelp(agent, agentLabel))
+  console.log('\n¿Otra herramienta en esta misma carpeta? Corre de nuevo "npx orquestra-mcp@latest setup" y elígela:')
+  console.log('cada una firma con su propio agente.')
   console.log('Docs completas y todas las tools disponibles: https://www.orquestra.me/mcp')
 }
+
+// Sin preguntar "¿cómo se llama?" cada vez: se elige de la lista (o viene con
+// --agent) y se marca lo que ya está conectado en esta máquina.
+async function chooseTool(preset, machine) {
+  if (preset?.trim()) return TOOLS.find(t => agentKey(t) === agentKey(preset)) || preset.trim()
+  const connected = connectedAgents()
+  const already = TOOLS.filter(t => connected.has(agentKey(t)))
+  console.log(`\nEsta máquina: ${machine.name}${already.length ? ` (ya conectadas: ${already.join(', ')})` : ''}`)
+  console.log('¿Para qué herramienta es esta conexión?')
+  TOOLS.forEach((t, i) => console.log(`  ${i + 1}. ${t}${connected.has(agentKey(t)) ? ' (ya conectada: renueva su token)' : ''}`))
+  console.log(`  ${TOOLS.length + 1}. Otra`)
+  for (;;) {
+    const answer = (await prompt('Número [Enter para Claude Code]: ')).trim()
+    const idx = answer === '' ? 1 : parseInt(answer, 10)
+    if (idx >= 1 && idx <= TOOLS.length) return TOOLS[idx - 1]
+    if (idx === TOOLS.length + 1) {
+      const name = (await prompt('Nombre de la herramienta: ')).trim()
+      if (name) return name
+    }
+    console.log('Selección inválida.')
+  }
+}
+
+// La config de cada herramienta lleva ORQUESTRA_AGENT para que use SU token
+// (sin eso usaría el default de la carpeta y firmaría como otra).
+// En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
+// Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
+// versión vieja de su caché.
+function connectionHelp(agent, agentLabel) {
+  const isWindows = process.platform === 'win32'
+  const json = file => `  ${agentLabel} -- agrega esto a ${file}:\n` +
+    `    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"], "env": { "ORQUESTRA_AGENT": "${agent}" } } } }`
+  if (agent === 'claude-code') {
+    return '  Claude Code:\n' +
+      `    claude mcp add orquestra -e ORQUESTRA_AGENT=${agent} -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest\n` +
+      (isWindows ? '    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)\n' : '') +
+      '    (si ya estaba agregado: claude mcp remove orquestra y vuelve a agregarlo)\n' +
+      '    Después reinicia Claude Code o reconéctalo con /mcp.'
+  }
+  if (agent === 'codex') {
+    return '  Codex -- en ~/.codex/config.toml:\n' +
+      '    [mcp_servers.orquestra]\n' +
+      '    command = "npx"\n' +
+      '    args = ["-y", "orquestra-mcp@latest"]\n' +
+      `    env = { ORQUESTRA_AGENT = "${agent}" }`
+  }
+  if (agent === 'cursor') return json('~/.cursor/mcp.json')
+  if (agent === 'gemini-cli') return json('~/.gemini/settings.json')
+  if (agent === 'claude-desktop') return json(`${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json`)
+  return json('la config de MCP de tu herramienta') + '\n  Guía por herramienta: https://www.orquestra.me/mcp#instalacion'
+}

package/src/updateCheck.mjs

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+// Aviso de versión nueva (ORQ-415): al arrancar, el server pregunta a npm cuál
+// es la última versión publicada (caché de 12 h en ~/.orquestra, así casi
+// ningún arranque sale a la red) y get_project_context la devuelve en
+// `orquestraMcpUpdate` para que el agente le diga al usuario cómo actualizar.
+// Nunca bloquea el arranque ni falla: sin red simplemente no hay aviso.
+const CACHE_PATH = join(homedir(), '.orquestra', 'update-check.json')
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000
+const REGISTRY_URL = 'https://registry.npmjs.org/orquestra-mcp/latest'
+
+let latestKnown = null
+
+export function isNewer(latest, current) {
+  const parts = v => String(v).split('-')[0].split('.').map(n => parseInt(n, 10) || 0)
+  const [a, b] = [parts(latest), parts(current)]
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) > (b[i] || 0)
+  }
+  return false
+}
+
+export async function startUpdateCheck({ fetchImpl = fetch, now = Date.now() } = {}) {
+  if (process.env.ORQUESTRA_NO_UPDATE_CHECK) return null
+  try {
+    const cached = JSON.parse(readFileSync(CACHE_PATH, 'utf8'))
+    if (cached.latest && now - cached.checkedAt < CACHE_TTL_MS) return (latestKnown = cached.latest)
+  } catch {}
+  try {
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const { version } = await res.json()
+    if (!version) return null
+    latestKnown = version
+    mkdirSync(dirname(CACHE_PATH), { recursive: true })
+    writeFileSync(CACHE_PATH, JSON.stringify({ latest: version, checkedAt: now }))
+    return version
+  } catch {
+    return null
+  }
+}
+
+export function updateNotice(current) {
+  if (!latestKnown || !isNewer(latestKnown, current)) return null
+  return {
+    current,
+    latest: latestKnown,
+    message:
+      `Hay una versión nueva de orquestra-mcp (${latestKnown}; esta sesión usa ${current}). ` +
+      `Para actualizar, reinicia tu herramienta o reconecta el MCP (en Claude Code: /mcp → orquestra → Reconnect). ` +
+      `Si sigue la versión vieja, en la config del MCP cambia "orquestra-mcp" por "orquestra-mcp@latest" ` +
+      `(sin @latest, npx reusa la versión que tiene en caché). Novedades: https://www.orquestra.me/mcp`,
+  }
+}