orquestra-mcp 1.46.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.46.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": {

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/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 })

package/src/setup.mjs

@@ -175,11 +175,17 @@ 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://www.orquestra.me/mcp#instalacion\n')
   console.log('Docs completas y todas las tools disponibles: https://www.orquestra.me/mcp')