orquestra-mcp 1.44.0 → 1.46.1

package/README.md

@@ -12,25 +12,34 @@ configurar/sincronizar un proyecto completo sin crear duplicados.
 Ver `CLAUDE.md` para contexto de desarrollo. Ver la memoria del proyecto
 `orquestra-mcp-api-plan` para las 8 fases del plan MCP/API completo.
 
-## Setup rápido (recomendado)
+## Empezar (macOS, Linux y Windows)
+
+Necesitas una cuenta en [app.orquestra.me](https://app.orquestra.me) y Node 18+.
+
+**1. Conecta tu cuenta y tu proyecto** — desde la carpeta de tu proyecto:
 
 ```bash
-npm install
-node bin/orquestra-mcp.mjs setup
+npx orquestra-mcp@latest setup
 ```
 
-Esto abre tu navegador en `https://app.orquestra.me/cli-auth` para
-confirmar tu sesión (Google o email/password, lo que ya uses) y:
+Abre el navegador para confirmar tu sesión (Google o email/password) y luego:
+
+- Si **no tienes workspace**, te pide su nombre y después el de tu primer proyecto.
+- Si **perteneces a varios workspaces**, te deja elegir en cuál trabajar (elegir aquí
+  no cambia el que tienes abierto en la web).
+- Eliges un proyecto de ese workspace o creas uno nuevo.
+
+La conexión se guarda **por carpeta** en `~/.orquestra/mcp-config.json`: puedes tener
+distintos proyectos (o cuentas) en distintas carpetas. Para conectar otra carpeta o
+cambiar de proyecto, vuelve a correr el setup ahí.
 
-- Si **no tienes** workspace/proyecto todavía: te crea uno default
-  ("Mi primer proyecto", con los 6 estatus base) — puedes renombrarlo o
-  cambiarlo cuando quieras desde `orquestra-web`.
-- Si **ya tienes** uno o varios: te deja elegir cuál usar por default
-  desde la misma terminal.
+**2. Regístralo en tu agente** (ver abajo: Claude Code, Claude Desktop, Cursor, Codex,
+Gemini CLI). Usa `orquestra-mcp@latest` para que `npx` no se quede con una versión vieja
+de su caché.
 
-Guarda todo (`apiToken`, `workspaceId`, `defaultProjectId`) en
-`~/.orquestra/mcp-config.json` — después de esto, `node bin/orquestra-mcp.mjs`
-(sin más flags ni env vars) ya funciona.
+**Ver la versión / actualizar:** `npm view orquestra-mcp version` muestra la última
+publicada. Con `@latest` cada arranque la usa; el servidor que ya está corriendo conserva
+la suya hasta que reconectas (en Claude Code: `/mcp` → reconectar).
 
 Variable opcional `ORQUESTRA_WEB_URL` para apuntar el login a otro lugar
 (ej. `http://localhost:5173` mientras desarrollas `orquestra-web` local en
@@ -71,35 +80,57 @@ Variables de entorno (todas opcionales si ya corriste `setup` — se leen de
 
 ### Claude Code
 
-Si ya corriste `setup`, alcanza con:
+macOS / Linux:
 
 ```bash
-claude mcp add orquestra -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs
+claude mcp add orquestra -- npx -y orquestra-mcp@latest
 ```
 
-O manual, sin `setup`:
+Windows (PowerShell) — `npx` necesita `cmd /c` delante:
 
-```bash
-claude mcp add orquestra \
-  -e ORQUESTRA_API_TOKEN=orq_... \
-  -e ORQUESTRA_WORKSPACE_ID=... \
-  -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs
+```powershell
+claude mcp add orquestra -- cmd /c npx -y orquestra-mcp@latest
 ```
 
+Agrega `--scope user` después de `add` para tenerlo en todos tus proyectos. Si PowerShell
+dice que `claude` no se reconoce, falta instalar Claude Code:
+`npm install -g @anthropic-ai/claude-code` (y vuelve a abrir la terminal). Si ya lo habías
+agregado sin `@latest`, primero `claude mcp remove orquestra`.
+
 ### Claude Desktop (`claude_desktop_config.json`)
 
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
     "orquestra": {
-      "command": "node",
-      "args": ["/ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs"]
+      "command": "npx",
+      "args": ["-y", "orquestra-mcp@latest"]
     }
   }
 }
 ```
 
-(sin `env` si ya corriste `setup`; si no, agrega `ORQUESTRA_API_TOKEN`/`ORQUESTRA_WORKSPACE_ID` igual que en Claude Code.)
+Cierra la app por completo (en Windows también desde el ícono junto al reloj) y vuelve a
+abrirla.
+
+### Cursor, Codex CLI, Gemini CLI
+
+Mismo comando (`npx -y orquestra-mcp@latest`), cambia el archivo — ver
+[orquestra.me/mcp#instalacion](https://www.orquestra.me/mcp#instalacion). En Windows, si
+el agente no encuentra `npx`, usa `"command": "cmd"` con
+`"args": ["/c", "npx", "-y", "orquestra-mcp@latest"]`.
+
+### Sin `setup` (variables de entorno)
+
+```bash
+claude mcp add orquestra \
+  -e ORQUESTRA_API_TOKEN=orq_... \
+  -e ORQUESTRA_WORKSPACE_ID=... \
+  -- npx -y orquestra-mcp@latest
+```
 
 ## Tools
 

package/bin/orquestra-mcp.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { createServer } from '../src/server.mjs'
+import { createServer, createSetupNeededServer } from '../src/server.mjs'
 import { runSetup } from '../src/setup.mjs'
 import { runVaultSync } from '../src/vaultSync.mjs'
 
@@ -9,7 +9,7 @@ const HELP_TEXT = `orquestra-mcp -- Servidor MCP de Orquestra (132 tools)
 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 + configura tu proyecto default
+  npx orquestra-mcp setup      Login por navegador + conecta esta carpeta a un proyecto
   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)
@@ -50,7 +50,7 @@ async function main() {
     server = createServer()
   } catch (err) {
     console.error(`[orquestra-mcp] ${err.message}`)
-    process.exit(1)
+    server = createSetupNeededServer(err.message)
   }
 
   const transport = new StdioServerTransport()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.44.0",
+  "version": "1.46.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": {
@@ -15,7 +15,7 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://orquestra.me/mcp",
+  "homepage": "https://www.orquestra.me/mcp",
   "keywords": [
     "mcp",
     "model-context-protocol",

package/src/api.mjs

@@ -27,12 +27,15 @@ export function loadConfig() {
   if (!apiToken) missing.push('ORQUESTRA_API_TOKEN')
   if (!workspaceId) missing.push('ORQUESTRA_WORKSPACE_ID')
   if (missing.length) {
+    const folders = Object.keys(fileConfig?.projects || {})
     throw new Error(
-      `Faltan variables de entorno requeridas: ${missing.join(', ')} (y no hay config en ${CONFIG_PATH}). ` +
-      `Corre "npx orquestra-mcp setup" para conectarlo con tu cuenta -- crea un workspace/proyecto ` +
-      `default si no tienes uno, o te deja elegir uno existente. Alternativa manual: 1) cuenta+workspace ` +
-      `ya creados en orquestra-web, 2) generar un token con POST ${apiBase}/v1/tokens con tu ID token ` +
-      `de Firebase, y 3) pasar ese token + el workspaceId acá.`
+      `Esta carpeta (${process.cwd()}) no está conectada a Orquestra. ` +
+      (folders.length
+        ? `Carpetas conectadas en ${CONFIG_PATH}: ${folders.join(' | ')}. `
+        : `No hay ninguna carpeta conectada (${CONFIG_PATH} no existe o está vacío). `) +
+      `Solución: abre una terminal en esta carpeta y corre "npx orquestra-mcp@latest setup" ` +
+      `(o ábrela desde una carpeta que ya esté conectada), y después reconecta el MCP. ` +
+      `Alternativa sin setup: variables de entorno ${missing.join(' y ')}.`
     )
   }
 

package/src/configFile.mjs

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
-import { join, dirname, sep } from 'path'
+import { join, dirname, win32, posix } from 'path'
 
 export const CONFIG_PATH = join(homedir(), '.orquestra', 'mcp-config.json')
 
@@ -63,13 +63,27 @@ export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPat
 // gana, así que un repo individual con su propio mapeo (y su propia cuenta)
 // puede sobreescribir el de la carpeta contenedora que lo engloba. Devuelve
 // el objeto {apiBase, apiToken, workspaceId, projectId} de esa carpeta.
-export function resolveProjectForCwd(projects, cwd) {
+// En Windows las rutas no distinguen mayúsculas, y VS Code arranca el
+// servidor con la unidad en minúscula ("c:\Users\...") aunque setup haya
+// guardado "C:\Users\..." (o con "/" en vez de "\"). Comparar exacto hacía
+// que no encontrara la carpeta y el servidor se cerrara al arrancar
+// ("Connection closed" en Claude Code, 21 oct 2026). `platform` es para tests.
+export function folderKey(folderPath, platform = process.platform) {
+  const isWin = platform === 'win32'
+  const resolved = (isWin ? win32 : posix).resolve(folderPath)
+  const trimmed = resolved.length > 1 && !/^[a-z]:\\$/i.test(resolved) ? resolved.replace(/[\\/]+$/, '') : resolved
+  return isWin ? trimmed.toLowerCase() : trimmed
+}
+
+export function resolveProjectForCwd(projects, cwd, platform = process.platform) {
   if (!projects) return undefined
+  const sep = platform === 'win32' ? '\\' : '/'
+  const target = folderKey(cwd, platform)
   let best = null
   for (const folderPath of Object.keys(projects)) {
-    const normalized = folderPath.endsWith(sep) ? folderPath.slice(0, -1) : folderPath
-    if (cwd !== normalized && !cwd.startsWith(normalized + sep)) continue
-    if (!best || normalized.length > best.length) best = normalized
+    const key = folderKey(folderPath, platform)
+    if (target !== key && !target.startsWith(key.endsWith(sep) ? key : key + sep)) continue
+    if (!best || key.length > best.key.length) best = { key, folderPath }
   }
-  return best ? projects[best] : undefined
+  return best ? projects[best.folderPath] : undefined
 }

package/src/platformPlaybooks.mjs

@@ -526,7 +526,7 @@ export const PLATFORM_PLAYBOOKS = {
       {
         title:       'Medir y corregir Core Web Vitals en PageSpeed Insights (móvil)',
         description: 'Correr PageSpeed Insights sobre la home y las páginas clave. Objetivo: LCP < 2.5s, CLS < 0.1, INP < 200ms. Atacar primero imágenes sin comprimir, fuentes bloqueantes y JS sin dividir.',
-        type: 'tech', priority: 'medium', tags: ['seo', 'web', 'performance'], offsetDays: 5,
+        type: 'tech', priority: 'medium', tags: ['seo', 'web', 'performance'], offsetDays: 5, checkKey: 'core_web_vitals',
       },
       {
         title:       'Fijar dominio canónico y redirecciones 301 (www / http → https)',

package/src/server.mjs

@@ -161,6 +161,22 @@ const SCOPE_EVIDENCE = {
   notApplicableReason: z.string().optional().describe('Motivo de "no aplica" (obligatorio si notApplicable es true)'),
 }
 
+// Sin conexión para la carpeta (loadConfig falló): antes el proceso se cerraba
+// y el cliente solo mostraba "Connection closed", sin el motivo. Ahora arranca
+// con una sola tool que explica qué pasa y cómo arreglarlo, para que el agente
+// se lo diga al usuario.
+export function createSetupNeededServer(reason) {
+  const server = new McpServer(
+    { name: 'orquestra-mcp', version: PKG_VERSION },
+    { instructions: `Orquestra no está conectado en esta carpeta, así que sus herramientas no están disponibles. Si el usuario pide algo de Orquestra, llama a diagnostico_conexion y explícale cómo arreglarlo. Motivo: ${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}` }] }))
+  return server
+}
+
 export function createServer() {
   const config = loadConfig()
   const server = new McpServer({ name: 'orquestra-mcp', version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS })
@@ -337,6 +353,26 @@ export function createServer() {
     {}
   )
 
+  // PageSpeed Insights por distribución web (ORQ-377). La última medición
+  // también viene en list_distributions (campo `pagespeed` de cada una).
+  registerRead(
+    'get_pagespeed',
+    '/v1/pagespeed',
+    'Historial de mediciones de PageSpeed Insights (móvil) de una distribución web, más reciente primero: scores de Performance/Accesibilidad/Buenas prácticas/SEO, métricas de laboratorio (LCP, CLS, TBT), Core Web Vitals de usuarios reales (CrUX: LCP, INP, CLS con categoría FAST/AVERAGE/SLOW; null si el sitio no tiene tráfico suficiente), oportunidades con ahorro estimado y auditorías que fallan. Se mide solo cada lunes; para una medición nueva usa measure_pagespeed.',
+    {
+      distributionId: z.string().describe('Distribución type="web" con domain configurado (ver list_distributions)'),
+      limit: z.number().int().min(1).max(100).optional().describe('Cuántas mediciones traer (default 20)'),
+    },
+    (args, projectId) => ({ projectId, distributionId: args.distributionId, limit: args.limit })
+  )
+
+  registerCreate(
+    'measure_pagespeed',
+    '/v1/pagespeed',
+    'Pide una medición nueva de PageSpeed Insights (móvil) para una distribución web con dominio. Corre en segundo plano (10-40 s): responde de inmediato con status "running"; el resultado aparece después en el campo `pagespeed` de la distribución (list_distributions) y en get_pagespeed. 409 si ya hay una en curso.',
+    { distributionId: z.string().describe('Distribución type="web" con domain configurado') }
+  )
+
   registerRead(
     'get_infra_status',
     '/v1/infra',
@@ -2637,12 +2673,12 @@ 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)') },
+    { kind: z.enum(AGENT_KINDS).optional().describe('Filtra por kind: "qa" (lint/test/build/E2E), "security" (npm audit + gitleaks), "performance" (build size + Lighthouse: performance/accesibilidad/buenas prácticas/SEO + LCP/CLS/TBT) o "screenshots" (captura de pantallas para el checklist de publicación, solo ios/android)') },
     (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"'),
-    kind: z.enum(AGENT_KINDS).default('qa').describe('"qa" (lint/test/build/E2E), "security" (npm audit + gitleaks), "performance" (build size + Lighthouse) o "screenshots" (captura de pantallas para tiendas, solo stack ios/android) -- default "qa"'),
+    kind: z.enum(AGENT_KINDS).default('qa').describe('"qa" (lint/test/build/E2E), "security" (npm audit + gitleaks), "performance" (build size + Lighthouse: performance/accesibilidad/buenas prácticas/SEO + LCP/CLS/TBT) o "screenshots" (captura de pantallas para tiendas, solo stack ios/android) -- default "qa"'),
     runnerId: z.string().describe('ID de la máquina emparejada -- ver list_agents o Workspace → Máquinas'),
     stack: z.enum(AGENT_STACKS).optional().describe('Requerido para los 4 kinds. security/performance solo tienen lógica real para "web" hoy; screenshots solo para "ios"/"android"'),
     localPath: z.string().optional().describe('Requerido para los 4 kinds -- ruta absoluta del checkout en esa máquina'),
@@ -2657,7 +2693,14 @@ export function createServer() {
     plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- recordatorio manual de "próxima corrida planeada". Ningún kind tiene scheduling real (todo trigger es manual/push): esto NO dispara ninguna corrida sola, solo alimenta el calendario global.'),
     perfUrl: z.string().optional().describe('Requerido si kind="performance" -- URL viva (ej. staging/prod) contra la que corre Lighthouse'),
     maxBundleSizeKb: z.number().optional().describe('Específico de kind="performance" -- umbral en KB para el paso de tamaño de build (default 5000)'),
-    minPerfScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de Lighthouse (0-100) para pasar (default 50)'),
+    minPerfScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de Lighthouse en Performance (0-100) para pasar (default 50)'),
+    perfUrls: z.array(z.string()).optional().describe('Específico de kind="performance" -- URLs ADICIONALES a perfUrl (ej. /precios, /blog): Lighthouse corre un paso por cada una'),
+    minAccessibilityScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de Accesibilidad (0-100, default 90)'),
+    minBestPracticesScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de Buenas prácticas (0-100, default 90)'),
+    minSeoScore: z.number().optional().describe('Específico de kind="performance" -- score mínimo de SEO (0-100, default 90)'),
+    maxLcpMs: z.number().optional().describe('Específico de kind="performance" -- LCP máximo en ms (default 2500, umbral "bueno" de Google)'),
+    maxCls: z.number().optional().describe('Específico de kind="performance" -- CLS máximo (default 0.1)'),
+    maxTbtMs: z.number().optional().describe('Específico de kind="performance" -- TBT máximo en ms (default 200, proxy de laboratorio de INP)'),
   })
 
   registerUpdate('update_agent', '/v1/agents', 'Edita un agente existente.', {
@@ -2678,6 +2721,13 @@ export function createServer() {
     perfUrl: z.string().optional().describe('Ver create_agent -- específico de kind="performance"'),
     maxBundleSizeKb: z.number().optional(),
     minPerfScore: z.number().optional(),
+    perfUrls: z.array(z.string()).optional().describe('Ver create_agent -- reemplaza la lista completa, [] la vacía'),
+    minAccessibilityScore: z.number().optional(),
+    minBestPracticesScore: z.number().optional(),
+    minSeoScore: z.number().optional(),
+    maxLcpMs: z.number().optional(),
+    maxCls: z.number().optional(),
+    maxTbtMs: z.number().optional(),
   })
 
   registerCreate('create_agent_run', '/v1/agent-runs', 'Dispara una corrida de agente (qa: lint/tests/build/E2E; security: npm audit + gitleaks; performance: build size + Lighthouse; screenshots: captura de pantallas para el checklist de publicación) en la rama indicada. Necesita al menos un agente activo para el stack (o falla explícito -- ver list_agents/create_agent). La corrida queda "queued" -- nunca asumas que pasó, confirma con get_agent_run.', {

package/src/setup.mjs

@@ -78,22 +78,72 @@ export async function runSetup() {
   const agentLabelAnswer = await prompt('¿Cómo se llama este agente/herramienta? [Claude Code]: ')
   const agentLabel = agentLabelAnswer.trim() || 'Claude Code'
 
-  const res = await fetch(`${apiBase}/v1/bootstrap`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${idToken}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify({ agentLabel }),
-  })
-  const body = await res.json()
-  if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
+  // askIfMissing: si no hay workspace la API no crea nada solo -- avisa
+  // (needsWorkspace) y aquí se le pide el nombre al usuario.
+  const callBootstrap = async (extra = {}) => {
+    const res = await fetch(`${apiBase}/v1/bootstrap`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${idToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentLabel, askIfMissing: true, ...extra }),
+    })
+    const body = await res.json()
+    if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
+    return body
+  }
+  const askName = async (question) => {
+    for (;;) {
+      const name = (await prompt(question)).trim()
+      if (name) return name
+      console.log('El nombre no puede estar vacío.')
+    }
+  }
+
+  let body = await callBootstrap()
+  if (body.needsWorkspaceChoice) {
+    // Miembro de varios workspaces: elegir aquí no cambia el workspace
+    // actual de la web, solo a cuál queda conectada esta carpeta.
+    const { workspaces, currentWorkspaceId } = body
+    console.log('\nPerteneces a varios workspaces. ¿En cuál quieres trabajar desde esta carpeta?')
+    workspaces.forEach((w, i) => console.log(`  ${i + 1}. ${w.name}${w.id === currentWorkspaceId ? ' (el que tienes abierto en la web)' : ''}`))
+    const currentIdx = workspaces.findIndex(w => w.id === currentWorkspaceId) + 1
+    let idx
+    for (;;) {
+      const answer = (await prompt(currentIdx ? `Número [Enter para usar "${workspaces[currentIdx - 1].name}"]: ` : 'Número: ')).trim()
+      idx = answer === '' && currentIdx ? currentIdx : parseInt(answer, 10)
+      if (idx >= 1 && idx <= workspaces.length) break
+      console.log('Selección inválida.')
+    }
+    body = await callBootstrap({ workspaceId: workspaces[idx - 1].id })
+  } else if (body.needsWorkspace) {
+    console.log('\nTodavía no tienes un workspace en Orquestra. Primero vamos a crearlo')
+    console.log('(agrupa todos tus proyectos: tu empresa, tu equipo o tu nombre si trabajas solo).')
+    const workspaceName = await askName('Nombre del workspace: ')
+    body = await callBootstrap({ workspaceName })
+    console.log(`Workspace "${workspaceName}" creado.`)
+  }
 
-  const { workspaceId, token, created, projects } = body
+  const { workspaceId, token, projects } = body
+  // La API de producción anterior a ORQ-388 no manda workspaceName.
+  const wsLabel = body.workspaceName ? ` del workspace "${body.workspaceName}"` : ''
   let defaultProjectId
 
-  if (created) {
-    defaultProjectId = body.projectId
-    console.log(`Se creó un workspace y un proyecto default para ti ("${projects[0].name}") -- puedes renombrarlos cuando quieras desde orquestra-web.`)
+  const createProject = async (name) => {
+    const res2 = await fetch(`${apiBase}/v1/projects?workspaceId=${workspaceId}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name }),
+    })
+    const newProject = await res2.json()
+    if (!res2.ok) throw new Error(newProject?.error || `HTTP ${res2.status}`)
+    console.log(`Proyecto "${newProject.name}"${wsLabel} creado y configurado como default.`)
+    return newProject.id
+  }
+
+  if (projects.length === 0) {
+    console.log(`\nAhora crea el proyecto${wsLabel} que este MCP va a usar (puedes agregar más después).`)
+    defaultProjectId = await createProject(await askName('Nombre del proyecto: '))
   } else {
-    console.log('\nElige el proyecto que este MCP va a usar por default:')
+    console.log(`\nElige el proyecto${wsLabel} que este MCP va a usar por default:`)
     console.log('  0. (crear un proyecto nuevo)')
     projects.forEach((p, i) => console.log(`  ${i + 1}. ${p.name}`))
     const singleDefaultIdx = projects.length === 1 ? 1 : null
@@ -105,20 +155,10 @@ export async function runSetup() {
     if (Number.isNaN(idx) || idx < 0 || idx > projects.length) throw new Error('Selección inválida')
 
     if (idx === 0) {
-      const name = await prompt('Nombre del proyecto nuevo: ')
-      if (!name.trim()) throw new Error('El nombre no puede estar vacío')
-      const res2 = await fetch(`${apiBase}/v1/projects?workspaceId=${workspaceId}`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ name: name.trim() }),
-      })
-      const newProject = await res2.json()
-      if (!res2.ok) throw new Error(newProject?.error || `HTTP ${res2.status}`)
-      defaultProjectId = newProject.id
-      console.log(`Proyecto "${newProject.name}" creado y configurado como default.`)
+      defaultProjectId = await createProject(await askName('Nombre del proyecto nuevo: '))
     } else {
       defaultProjectId = projects[idx - 1].id
-      console.log(`Usando tu proyecto "${projects[idx - 1].name}" como default.`)
+      console.log(`Usando tu proyecto "${projects[idx - 1].name}"${wsLabel} como default.`)
     }
   }
 
@@ -135,12 +175,18 @@ export async function runSetup() {
 
   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 -- npx orquestra-mcp\n')
-  console.log('  Claude Desktop -- agrega esto a tu claude_desktop_config.json:')
-  console.log('    { "mcpServers": { "orquestra": { "command": "npx", "args": ["orquestra-mcp"] } } }\n')
+  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://orquestra.me/mcp#instalacion\n')
-  console.log('Docs completas y las 35 tools disponibles: https://orquestra.me/mcp')
+  console.log('    https://www.orquestra.me/mcp#instalacion\n')
+  console.log('Docs completas y todas las tools disponibles: https://www.orquestra.me/mcp')
 }