nexusflex-mcp 3.0.0

package/INSTALAR.md

@@ -0,0 +1,97 @@
+# MCP de Nexus Flex — Instalación (npx + autorización web)
+
+Este paquete deja que un asistente de IA (**Claude Desktop** o **Claude Code**) opere
+Nexus Flex **con tu cuenta**, en tu computadora, hablando con la API igual que la web.
+
+> **Seguridad (aislamiento en 3 capas):** el MCP no puede hacer nada que tu usuario no
+> pueda hacer desde la web. **1)** El backend gatea cada dato por rol y por nodo/cliente
+> (el token hereda tu rol/permisos frescos en cada pedido). **2)** El MCP muestra SOLO
+> los tools de tu rol. **3)** Nunca toca facturación/cobros/cuentas (bloqueado en el
+> cliente **y** en el backend). Cada usuario ve **solo lo suyo**.
+
+---
+
+## 1. Requisitos
+- **Node.js 20+** — https://nodejs.org (LTS). Verificá con `node --version`.
+- **Claude Desktop** (https://claude.ai/download) o Claude Code.
+- Una cuenta de Nexus Flex (la misma de la web). **No** hace falta tu contraseña acá:
+  autorizás desde el navegador.
+
+## 2. Autorizar (una sola vez)
+En una terminal, corré:
+
+```bash
+npx -y nexusflex-mcp@latest login
+```
+
+Se abre el navegador (o te muestra un link + un código de 8 letras). Entrás a Nexus Flex
+—si no estás logueado, iniciás sesión— y hacés click en **Autorizar**. Listo: el token
+queda guardado en tu equipo (`~/.nexusflex-mcp/token.json`).
+
+## 3. Conectarlo a Claude Desktop
+Editá el config de Claude Desktop:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Pegá esto (¡sin email ni contraseña!):
+
+```json
+{
+  "mcpServers": {
+    "nexusflex": {
+      "command": "npx",
+      "args": ["-y", "nexusflex-mcp@latest"],
+      "env": {
+        "NEXUSFLEX_MCP_ALLOW_WRITE": "true",
+        "NEXUSFLEX_MCP_ALLOW_PRECIOS": "false"
+      }
+    }
+  }
+}
+```
+
+Guardá y **reiniciá Claude Desktop**. (Si nunca corriste el paso 2, la primera vez que
+arranque el MCP te va a mostrar el link + código en sus logs para que autorices.)
+
+- `NEXUSFLEX_MCP_ALLOW_WRITE` = `"true"` habilita **altas y ediciones** (clientes,
+  productos, y nodos si sos admin global). `"false"` = solo consulta.
+- `NEXUSFLEX_MCP_ALLOW_PRECIOS` = `"true"` habilita **actualizar listas de precios**.
+
+## 4. Qué ve cada usuario (según con qué cuenta autorices)
+
+**CLIENTE (vendedor):** `mis_datos`, `mis_envios`, `mis_kpis`, `mi_stock`,
+`mi_disponible` (disponible-para-vender por SKU), `mi_rentabilidad` (margen por SKU),
+`mis_productos`, `mis_top_productos`. **No** ve datos del nodo ni de otros clientes.
+
+**STAFF del nodo:** `clientes_del_nodo`, `precios_ver`, `kpi_nodo`, `stock_nodo`,
+`productos_nodo`, `top_productos`, y —con escritura— `cliente_crear`, `cliente_editar`,
+`producto_crear`, y —con precios— `precio_actualizar`. Todo scopeado a **su** nodo.
+
+**Admin GLOBAL:** además `nodos_listar`, `kpi_red`, `nodo_crear`.
+
+## 5. Ejemplos (lenguaje natural en Claude)
+- *"¿Qué usuario y alcance tengo?"* → `mis_datos`.
+- *"¿Cuánto tengo disponible para vender del SKU ABC?"* → `mi_disponible`.
+- *"¿Qué productos me dejan más margen este mes?"* → `mi_rentabilidad`.
+- *"Dame de alta a Distribuidora López con la lista B."* → `cliente_crear`.
+- *"Actualizá la lista B: cercana 3800, media 4200."* → `precio_actualizar` (necesita ALLOW_PRECIOS).
+
+## 6. Revocar el acceso
+En la web de Nexus Flex, sección **🔌 Conexiones**, revocás cualquier asistente cuando
+quieras. Local: `npx -y nexusflex-mcp@latest logout` borra el token de tu equipo.
+
+## 7. Qué NO puede hacer — nunca
+Facturar, registrar cobros/pagos, tocar cuentas corrientes, liquidaciones ni saldos.
+Está bloqueado en el cliente **y** en el backend; aunque se lo pidas, lo rechaza.
+
+## Alternativas de credenciales (avanzado / compatibilidad)
+- `NEXUSFLEX_TOKEN` = un token ya emitido (MCP o JWT) → salta el device-flow.
+- `NEXUSFLEX_EMAIL` + `NEXUSFLEX_PASSWORD` = login legado por contraseña.
+- `NEXUSFLEX_API_URL` = base de la API (default `https://nexusflex.com.ar/api`).
+- `NEXUSFLEX_MCP_NO_AUTH_PROMPT=true` = no abrir device-flow automáticamente (falla
+  pidiendo `login` explícito).
+
+## Problemas comunes
+- *"Sesión inválida"* (401) → corré `npx nexusflex-mcp login` de nuevo (te lo pudieron revocar).
+- *"No tenés permiso"* (403) → tu usuario no tiene ese permiso (es correcto: el backend aísla).
+- No aparecen las herramientas → cerrá Claude Desktop del todo y reabrí.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Flex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# nexusflex-mcp
+
+Servidor **MCP** (Model Context Protocol) de [Nexus Flex](https://nexusflex.com.ar). Deja
+que un asistente de IA (Claude Desktop / Claude Code) opere tu nodo o tu cuenta de
+vendedor con lenguaje natural: altas de clientes, consulta de stock disponible,
+rentabilidad por SKU, KPIs y precios. **Nunca toca dinero** (facturación, cobros,
+cuentas, liquidaciones están bloqueados por diseño).
+
+## Uso rápido
+
+```bash
+# 1) Autorizá una vez (se abre el navegador):
+npx -y nexusflex-mcp@latest login
+
+# 2) En claude_desktop_config.json:
+#   "nexusflex": { "command": "npx", "args": ["-y", "nexusflex-mcp@latest"] }
+```
+
+Guía completa en español: [INSTALAR.md](./INSTALAR.md).
+
+## Cómo funciona (seguridad)
+
+- **Login por device-flow (autorización web):** el MCP pide un código, lo autorizás con un
+  click desde la web (ya logueado), y recibe un **token de vida larga, revocable** guardado
+  localmente. No se pega email/contraseña.
+- **Herencia de scope:** el token es un puntero opaco a tu usuario; el backend re-lee tu
+  rol/permisos/nodo **frescos en cada request**. El MCP no puede hacer nada que vos no
+  puedas desde la web. Revocar un permiso (o el token) en la app corta el acceso al instante.
+- **Aislamiento en 3 capas:** gating del backend (por rol + nodo/cliente) · tools por rol ·
+  denylist de dinero (en el cliente **y** en el backend).
+
+## Comandos
+
+| Comando | Qué hace |
+|---|---|
+| `npx nexusflex-mcp` | Arranca el servidor MCP (stdio). Lo usa Claude Desktop. |
+| `npx nexusflex-mcp login` | Autoriza por device-flow y guarda el token. |
+| `npx nexusflex-mcp logout` | Borra el token local. |
+
+## Variables de entorno
+
+| Var | Default | Descripción |
+|---|---|---|
+| `NEXUSFLEX_API_URL` | `https://nexusflex.com.ar/api` | Base de la API. |
+| `NEXUSFLEX_MCP_ALLOW_WRITE` | `false` | Habilita altas/ediciones (nunca dinero). |
+| `NEXUSFLEX_MCP_ALLOW_PRECIOS` | `false` | Habilita editar listas de precios. |
+| `NEXUSFLEX_TOKEN` | — | Token ya emitido (salta el device-flow). |
+| `NEXUSFLEX_EMAIL` / `NEXUSFLEX_PASSWORD` | — | Login legado por contraseña. |
+
+## Licencia
+
+MIT.

package/api.mjs

@@ -0,0 +1,135 @@
+// ============================================================================
+//  Cliente HTTP fino y autenticado contra la API REST de Nexus Flex.
+//
+//  PRINCIPIO DE SEGURIDAD (no romper): el MCP NO habla con la base de datos ni
+//  firma tokens propios. Usa un TOKEN REAL (device-flow, o el JWT del login) y
+//  TODA llamada pasa por el middleware de permisos del backend (requireAuth/
+//  requirePermiso + scope por nodo). El aislamiento entre nodos y por rol se
+//  hereda 100% del backend: el MCP no puede hacer nada que ese usuario no pueda.
+//
+//  Autenticación (en orden de preferencia):
+//    1) NEXUSFLEX_TOKEN            token explícito (MCP o JWT) por env
+//    2) token guardado             ~/.nexusflex-mcp/token.json (device-flow previo)
+//    3) NEXUSFLEX_EMAIL/PASSWORD   login legado (compatibilidad hacia atrás)
+//    4) device-flow interactivo    imprime URL + código, autorizás en el navegador
+// ============================================================================
+import { loadToken, saveToken, clearToken, runDeviceFlow } from "./device-auth.mjs";
+
+const API_URL = (process.env.NEXUSFLEX_API_URL ?? "https://nexusflex.com.ar/api").replace(/\/+$/, "");
+const EMAIL = process.env.NEXUSFLEX_EMAIL ?? "";
+const PASSWORD = process.env.NEXUSFLEX_PASSWORD ?? "";
+const NO_AUTH_PROMPT = /^(1|true|yes|si|sí)$/i.test(process.env.NEXUSFLEX_MCP_NO_AUTH_PROMPT ?? "");
+let TOKEN = process.env.NEXUSFLEX_TOKEN ?? "";
+let usandoDeviceFlow = false; // el token vino de un device-flow/guardado (no email/pass)
+
+export { API_URL };
+
+// Denylist de DEFENSA EN PROFUNDIDAD: aunque en el futuro alguien agregue un tool
+// por error, el cliente NUNCA llama a endpoints que muevan dinero o expongan datos
+// financieros. El backend además lo bloquea server-side para tokens de MCP (mcpMoneyGuard).
+const RUTAS_PROHIBIDAS = [
+  /^\/liquidaciones/i, /^\/cuentas/i, /^\/cobros/i, /^\/afip/i, /^\/personal/i,
+  /^\/balance/i, /^\/reportes/i, /^\/programacion/i, /^\/recuento/i, /^\/whatsapp/i,
+  /^\/logisticas\/[^/]*\/cargo/i, /^\/logisticas\/saldos/i, /^\/logisticas\/facturar/i,
+  /^\/logisticas\/costo/i, /\/facturacion/i,
+];
+
+/** Timeout de red por llamada (ms). Un backend colgado no debe colgar el tool. */
+const FETCH_TIMEOUT_MS = Number(process.env.NEXUSFLEX_MCP_TIMEOUT_MS) || 30000;
+
+/** SIEMPRE loguear a stderr: stdout es el canal del transporte MCP (stdio). */
+export function log(...args) {
+  console.error("[nexusflex-mcp]", ...args);
+}
+
+// Aviso si se van a mandar credenciales por HTTP sin cifrar (login legado).
+if (EMAIL && PASSWORD && !/^https:\/\//i.test(API_URL)) {
+  log("ADVERTENCIA: NEXUSFLEX_API_URL no es HTTPS y hay email/contraseña — viajarían sin cifrar.");
+}
+
+function guard(path) {
+  const clean = path.split("?")[0];
+  if (RUTAS_PROHIBIDAS.some((re) => re.test(clean))) {
+    throw new Error(`Ruta bloqueada por política del MCP (endpoints de dinero deshabilitados): ${clean}`);
+  }
+}
+
+async function login() {
+  const r = await fetch(`${API_URL}/auth/login`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!r.ok) throw new Error(`Login falló (${r.status}). Revisá email/contraseña del nodo.`);
+  const data = await r.json();
+  if (!data?.token) throw new Error("Login sin token en la respuesta.");
+  TOKEN = data.token;
+  usandoDeviceFlow = false;
+  log(`Sesión iniciada como ${data.usuario?.email} (rol ${data.usuario?.rol}, nodo ${data.usuario?.logisticaId ?? "global"}).`);
+  return TOKEN;
+}
+
+/** Corre el device-flow, guarda el token y lo deja listo para usar. */
+async function autorizarPorDeviceFlow() {
+  const token = await runDeviceFlow(API_URL, { open: true, log });
+  saveToken(token, API_URL);
+  TOKEN = token;
+  usandoDeviceFlow = true;
+  return TOKEN;
+}
+
+/** Resuelve un token válido siguiendo el orden de preferencia. */
+async function ensureToken() {
+  if (TOKEN) return TOKEN;
+  // 2) token guardado de un device-flow anterior (atado a esta API).
+  const guardado = loadToken(API_URL);
+  if (guardado) { TOKEN = guardado; usandoDeviceFlow = true; return TOKEN; }
+  // 3) login legado por email/contraseña (compatibilidad).
+  if (EMAIL && PASSWORD) return login();
+  // 4) device-flow interactivo (a menos que se deshabilite explícitamente).
+  if (NO_AUTH_PROMPT) {
+    throw new Error("No hay token. Ejecutá `npx nexusflex-mcp login` para autorizar, o definí NEXUSFLEX_TOKEN.");
+  }
+  return autorizarPorDeviceFlow();
+}
+
+/** Llamada autenticada a la API. Reintenta UNA vez si el token venció/se revocó. */
+export async function api(method, path, body) {
+  guard(path);
+  let token = await ensureToken();
+  const doFetch = (t) =>
+    fetch(`${API_URL}${path}`, {
+      method,
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${t}` },
+      body: body != null ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+
+  let r = await doFetch(token);
+  if (r.status === 401) {
+    if (EMAIL && PASSWORD && !usandoDeviceFlow) {
+      // Token JWT vencido: re-login por credenciales.
+      log("401: token vencido, reintentando login…");
+      token = await login();
+      r = await doFetch(token);
+    } else if (usandoDeviceFlow && !NO_AUTH_PROMPT) {
+      // Token de MCP inválido/revocado: limpiamos y re-autorizamos por device-flow.
+      log("401: el token de MCP no es válido (revocado/vencido). Re-autorizando…");
+      clearToken();
+      TOKEN = "";
+      token = await autorizarPorDeviceFlow();
+      r = await doFetch(token);
+    }
+  }
+
+  const text = await r.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  log(`${method} ${path.split("?")[0]} -> ${r.status}`);
+  return { ok: r.ok, status: r.status, data };
+}

package/device-auth.mjs

@@ -0,0 +1,132 @@
+// ============================================================================
+//  Device-flow del MCP (autorización web, estilo OAuth device code) + guardado
+//  local del token. El MCP NO pide email/contraseña: pide un código, el usuario
+//  lo autoriza desde el navegador (ya logueado en Nexus Flex) y el MCP recibe un
+//  token de vida larga, revocable y con el scope exacto del usuario.
+// ============================================================================
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawn, execFileSync } from "child_process";
+
+/** Ruta del token guardado. Override con NEXUSFLEX_MCP_TOKEN_FILE. */
+export function tokenFilePath() {
+  if (process.env.NEXUSFLEX_MCP_TOKEN_FILE) return process.env.NEXUSFLEX_MCP_TOKEN_FILE;
+  return path.join(os.homedir(), ".nexusflex-mcp", "token.json");
+}
+
+/** Etiqueta legible para el token (aparece en "Conexiones" de la web). */
+export function defaultClientName() {
+  return process.env.NEXUSFLEX_MCP_CLIENT_NAME || `Claude MCP (${os.hostname?.() || "equipo"})`;
+}
+
+/** Restringe el archivo del token al usuario actual (privado). En POSIX: chmod 600.
+ *  En Windows chmod es no-op → usamos icacls para dejar SOLO al usuario actual. */
+function restringirPermisos(file) {
+  if (process.platform === "win32") {
+    try {
+      const user = process.env.USERNAME || process.env.USER;
+      // Corta la herencia y elimina a todos, dejando control total solo al usuario.
+      execFileSync("icacls", [file, "/inheritance:r", "/grant:r", `${user}:F`], { stdio: "ignore" });
+    } catch {
+      console.error("[nexusflex-mcp] ADVERTENCIA: no se pudieron restringir los permisos del token en Windows. Usá una cuenta de un solo usuario.");
+    }
+    return;
+  }
+  try { fs.chmodSync(file, 0o600); } catch { /* best-effort */ }
+}
+
+/** Guarda el token junto con la API a la que pertenece (no reusar entre servidores). */
+export function saveToken(token, apiUrl) {
+  const file = tokenFilePath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ token, apiUrl, savedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  restringirPermisos(file);
+  return file;
+}
+
+/** Lee el token guardado SI corresponde a esta misma API. */
+export function loadToken(apiUrl) {
+  try {
+    const file = tokenFilePath();
+    // Aviso si en POSIX el archivo quedó legible por grupo/otros (permisos flojos).
+    if (process.platform !== "win32") {
+      try {
+        const mode = fs.statSync(file).mode;
+        if ((mode & 0o077) !== 0) console.error("[nexusflex-mcp] ADVERTENCIA: el archivo de token tiene permisos demasiado abiertos.");
+      } catch { /* ignora */ }
+    }
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (raw?.token && raw?.apiUrl === apiUrl) return raw.token;
+  } catch { /* no hay archivo o está corrupto */ }
+  return null;
+}
+
+/** Borra el token guardado (logout local). */
+export function clearToken() {
+  try { fs.rmSync(tokenFilePath()); return true; } catch { return false; }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Intenta abrir el navegador en la URL (best-effort, no falla si no puede). */
+function abrirNavegador(url) {
+  try {
+    const cmd = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref?.();
+  } catch { /* sin navegador disponible */ }
+}
+
+/**
+ * Corre el device-flow completo contra la API: pide el código, muestra la URL +
+ * user_code por stderr (y abre el navegador si `open`), poll-ea hasta que el
+ * usuario autoriza y devuelve el token. Lanza si el usuario rechaza o vence.
+ */
+export async function runDeviceFlow(apiUrl, { open = true, log = (...a) => console.error(...a), timeoutMs } = {}) {
+  const clientName = defaultClientName();
+  const startRes = await fetch(`${apiUrl}/mcp/device/start`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ client_name: clientName }),
+  });
+  if (!startRes.ok) throw new Error(`No se pudo iniciar la autorización (${startRes.status}).`);
+  const s = await startRes.json();
+  const { device_code, user_code, verification_uri, verification_uri_complete } = s;
+  let interval = Math.max(2, Number(s.interval) || 5);
+  const deadline = Date.now() + (timeoutMs ?? (Number(s.expires_in) || 600) * 1000);
+
+  log("");
+  log("┌───────────────────────────────────────────────────────────┐");
+  log("│  🔌 Conectar Nexus Flex — autorizá el acceso del asistente  │");
+  log("└───────────────────────────────────────────────────────────┘");
+  log(`   1) Abrí:   ${verification_uri}`);
+  log(`   2) Código: ${user_code}`);
+  log(`   (o directo: ${verification_uri_complete})`);
+  log("");
+  log("   Esperando tu autorización en el navegador…");
+  if (open) abrirNavegador(verification_uri_complete);
+
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    const r = await fetch(`${apiUrl}/mcp/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code }),
+    });
+    const data = await r.json().catch(() => ({}));
+    if (r.ok && data.access_token) {
+      log("   ✅ ¡Autorizado! Conexión lista.");
+      return data.access_token;
+    }
+    if (data.error === "authorization_pending") continue;
+    if (data.error === "slow_down") { interval += 2; continue; }
+    if (data.error === "access_denied") throw new Error("Rechazaste el acceso desde el navegador.");
+    if (data.error === "expired_token") throw new Error("El código venció. Volvé a intentar.");
+    // invalid_grant u otro: cortamos
+    throw new Error(`No se pudo completar la autorización (${data.error || r.status}).`);
+  }
+  throw new Error("Se agotó el tiempo de espera de la autorización.");
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "nexusflex-mcp",
+  "version": "3.0.0",
+  "description": "MCP de Nexus Flex: operá tu nodo/cuenta desde un asistente de IA (altas de clientes, stock, KPIs). Login por autorización web (device-flow). NO toca dinero.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Nexus Flex",
+  "homepage": "https://nexusflex.com.ar/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezequieldos/nexus-flex.git",
+    "directory": "mcp"
+  },
+  "bugs": { "url": "https://github.com/ezequieldos/nexus-flex/issues" },
+  "keywords": ["mcp", "modelcontextprotocol", "nexusflex", "logistica", "claude"],
+  "engines": { "node": ">=20" },
+  "bin": { "nexusflex-mcp": "server.mjs" },
+  "files": ["server.mjs", "api.mjs", "device-auth.mjs", "README.md", "INSTALAR.md"],
+  "scripts": {
+    "start": "node server.mjs",
+    "login": "node server.mjs login",
+    "logout": "node server.mjs logout"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.24.1"
+  },
+  "publishConfig": { "access": "public" }
+}

package/server.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+// ============================================================================
+//  MCP Nexus Flex v3 — servidor stdio (paquete publicable en npm).
+//
+//  INSTALACIÓN FÁCIL:  npx -y nexusflex-mcp@latest         (arranca el server)
+//                      npx -y nexusflex-mcp@latest login   (autoriza en el navegador)
+//                      npx -y nexusflex-mcp@latest logout  (borra el token local)
+//
+//  AUTENTICACIÓN por DEVICE-FLOW (autorización web): sin pegar email/contraseña.
+//  El MCP pide un código, lo autorizás con un click desde la web ya logueado, y
+//  recibe un token de vida larga, revocable y con TU scope exacto (nunca dinero).
+//  Fallback: NEXUSFLEX_TOKEN o NEXUSFLEX_EMAIL+PASSWORD (compatibilidad).
+//
+//  AISLAMIENTO EN 3 CAPAS:
+//   1) El BACKEND gatea cada endpoint (requireAuth + requirePermiso + scope por
+//      nodo / idCliente). Un token de MCP hereda el rol/permisos FRESCOS del
+//      usuario en cada request. Es la garantía real.
+//   2) Este server registra los tools SEGÚN EL ROL del usuario (leído de /auth/me).
+//   3) DENYLIST de dinero en api.mjs + guard server-side (mcpMoneyGuard): jamás
+//      liquidaciones/cobros/cuentas/facturación.
+//
+//  Escritura por flags (default OFF):
+//   NEXUSFLEX_MCP_ALLOW_WRITE   → altas (clientes, productos, nodos) y edición.
+//   NEXUSFLEX_MCP_ALLOW_PRECIOS → actualizar listas de precios (aparte, sensible).
+// ============================================================================
+import { runDeviceFlow, saveToken, clearToken, tokenFilePath } from "./device-auth.mjs";
+import { api, log, API_URL } from "./api.mjs";
+
+// --- Subcomandos de línea de comando (login/logout) antes de arrancar el server ---
+const cmd = process.argv[2];
+if (cmd === "login") {
+  try {
+    const token = await runDeviceFlow(API_URL, { open: true, log });
+    const file = saveToken(token, API_URL);
+    log(`Token guardado en ${file}. Ya podés usar el MCP en Claude Desktop.`);
+    process.exit(0);
+  } catch (e) {
+    log("No se pudo autorizar:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+}
+if (cmd === "logout") {
+  clearToken();
+  log(`Token local borrado (${tokenFilePath()}). Revocá también desde la web (🔌 Conexiones) si querés cortar el acceso ya emitido.`);
+  process.exit(0);
+}
+
+const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = await import("zod");
+
+const truthy = (v) => /^(1|true|yes|si|sí)$/i.test(v ?? "");
+const ALLOW_WRITE = truthy(process.env.NEXUSFLEX_MCP_ALLOW_WRITE);
+const ALLOW_PRECIOS = truthy(process.env.NEXUSFLEX_MCP_ALLOW_PRECIOS);
+
+const server = new McpServer({ name: "nexusflex", version: "3.0.0" });
+
+/** Formatea un ApiResult como respuesta de tool MCP, con mensajes claros y SIN
+ *  filtrar tokens ni stack traces. */
+function toResult(r) {
+  if (r.ok) return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+  const base =
+    r.status === 401 ? "Sesión inválida o vencida (autorizá de nuevo con `npx nexusflex-mcp login`)." :
+    r.status === 403 ? "Tu usuario no tiene permiso para esta operación (aislamiento del backend)." :
+    r.status === 404 ? "No encontrado." :
+    `Error ${r.status}.`;
+  const d = r.data;
+  const detalle = d?.error ? ` ${d.error}` : d?.message ? ` ${d.message}` : "";
+  return { content: [{ type: "text", text: `${base}${detalle}` }], isError: true };
+}
+
+async function run(fn) {
+  try {
+    return toResult(await fn());
+  } catch (e) {
+    return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+  }
+}
+
+const q = (params) => {
+  const s = Object.entries(params).filter(([, v]) => v != null && v !== "").map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
+  return s ? `?${s}` : "";
+};
+const tool = (name, def, handler) => server.registerTool(name, def, handler);
+
+// ============================================================================
+//  CAPA 2 — Identidad: leemos /auth/me ANTES de registrar tools. Cada usuario ve
+//  SOLO los tools de su rol. Si falla el login, se registra solo `mis_datos`.
+// ============================================================================
+let me = null;
+try {
+  const r = await api("GET", "/auth/me");
+  if (r.ok) me = r.data?.usuario ?? null;
+  else log(`/auth/me devolvió ${r.status} — revisá el token/credenciales.`);
+} catch (e) {
+  log("No se pudo contactar /auth/me:", e instanceof Error ? e.message : String(e));
+}
+
+const rol = me?.rol ?? "";
+const permisos = Array.isArray(me?.permisos) ? me.permisos : [];
+const esGlobal = rol === "admin" || me?.esSuperoperador === true;
+const esAdminNodo = me?.esAdminNodo === true;
+const isCliente = rol === "cliente";
+const isStaff = rol === "operador" || rol === "admin";
+const wmsActivo = me?.wmsActivo === true;
+// Espejo de requirePermiso del backend (solo para DECIDIR qué mostrar; el backend manda).
+const puede = (p) => esGlobal || (isStaff && (esAdminNodo || permisos.length === 0 || permisos.includes(p)));
+
+// ============================================================================
+//  SIEMPRE
+// ============================================================================
+tool("mis_datos", {
+  title: "Mis datos / alcance",
+  description: "Devuelve tu usuario, rol y nodo/cliente al que está atado este MCP. Usalo para confirmar tu alcance antes de operar.",
+  inputSchema: {},
+}, async () => run(() => api("GET", "/auth/me")));
+
+// ============================================================================
+//  ROL CLIENTE (vendedor) — SOLO lo suyo. El backend lo fuerza a su idCliente.
+// ============================================================================
+if (isCliente) {
+  tool("mis_envios", {
+    title: "Mis envíos",
+    description: "Tus envíos/paquetes (solo los tuyos). No incluye datos de otros clientes ni del nodo.",
+    inputSchema: { estado: z.string().optional().describe("Filtrar por estado (opcional)") },
+  }, async ({ estado }) => run(() => api("GET", `/portal/envios${q({ estado })}`)));
+
+  tool("mis_kpis", {
+    title: "Mis métricas",
+    description: "Tus métricas: volumen, calidad de entrega, saldo, última liquidación y un benchmark ANÓNIMO contra el promedio de tu nodo (nunca ves a quién corresponde cada número).",
+    inputSchema: { desde: z.string().optional(), hasta: z.string().optional() },
+  }, async ({ desde, hasta }) => run(() => api("GET", `/kpi/vendedor${q({ desde, hasta })}`)));
+
+  // --- Control de stock del vendedor (WMS Fase 1). Se registran SIEMPRE para
+  //     rol=cliente: el backend gatea con 403 si el vendedor no tiene depósito ni
+  //     control de stock propio. Así funciona tanto con WMS del nodo como con el
+  //     modo "soft" por vendedor (Cliente.controlStockActivo). ---
+  tool("mi_stock", {
+    title: "Mi stock",
+    description: "Tu stock físico en el depósito (solo tus productos). Requiere tener depósito o control de stock habilitado.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/wms/stock")));
+
+  tool("mi_disponible", {
+    title: "Mi disponible para vender",
+    description: "Disponible-para-vender por SKU = stock físico − comprometido en pedidos pendientes. Marca ⚠️ cuando un SKU está por debajo del mínimo. Solo tus productos.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/wms/stock/disponible")));
+
+  tool("mi_rentabilidad", {
+    title: "Mi rentabilidad por SKU",
+    description: "Margen por SKU en un rango (default: mes en curso) = precio de venta − costo de envío real − COGS opcional. Solo tus productos. Fechas YYYY-MM-DD.",
+    inputSchema: { desde: z.string().optional().describe("YYYY-MM-DD"), hasta: z.string().optional().describe("YYYY-MM-DD") },
+  }, async ({ desde, hasta }) => run(() => api("GET", `/wms/rentabilidad${q({ desde, hasta })}`)));
+
+  tool("mis_productos", {
+    title: "Mi catálogo",
+    description: "Tu catálogo de productos en el depósito.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/wms/productos")));
+
+  tool("mis_top_productos", {
+    title: "Mis productos más despachados",
+    description: "Ranking de TUS productos más despachados en un rango (default: mes en curso). Solo tus productos.",
+    inputSchema: { desde: z.string().optional().describe("YYYY-MM-DD"), hasta: z.string().optional().describe("YYYY-MM-DD") },
+  }, async ({ desde, hasta }) => run(() => api("GET", `/wms/top-productos${q({ desde, hasta })}`)));
+}
+
+// ============================================================================
+//  ROL STAFF DE NODO — datos de SU nodo (gateado por permiso; el backend fuerza el nodo).
+// ============================================================================
+if (isStaff) {
+  if (puede("gestion")) {
+    tool("clientes_del_nodo", {
+      title: "Clientes y listas del nodo",
+      description: "Clientes/vendedores del nodo con su lista de precio asignada, más las listas disponibles. Scopeado a tu nodo.",
+      inputSchema: {},
+    }, async () => run(() => api("GET", "/gestion/formularios")));
+  }
+
+  if (puede("precios")) {
+    tool("precios_ver", {
+      title: "Ver listas de precios",
+      description: "Las listas de precios (por zona: cercana/media/lejana/muy lejana) de tu nodo. Solo lectura.",
+      inputSchema: {},
+    }, async () => run(() => api("GET", "/precios/clientes")));
+  }
+
+  if (puede("reportes")) {
+    tool("kpi_nodo", {
+      title: "Métricas del nodo",
+      description: "Tablero del nodo: volumen y entregas con variación mensual, P&L real, top de clientes y clientes en caída. Solo lectura, scopeado a tu nodo.",
+      inputSchema: { desde: z.string().optional(), hasta: z.string().optional(), nodo: z.number().optional().describe("Solo para admin global: elegir nodo") },
+    }, async ({ desde, hasta, nodo }) => run(() => api("GET", `/kpi/nodo${q({ desde, hasta, nodo })}`)));
+  }
+
+  if (puede("wms") && wmsActivo) {
+    tool("stock_nodo", {
+      title: "Stock del nodo",
+      description: "Stock del depósito del nodo. Opcional: filtrar por un cliente.",
+      inputSchema: { cliente: z.string().optional().describe("idCliente para filtrar (opcional)") },
+    }, async ({ cliente }) => run(() => api("GET", `/wms/stock${q({ cliente })}`)));
+
+    tool("productos_nodo", {
+      title: "Catálogo del nodo",
+      description: "Catálogo de productos del depósito del nodo. Opcional: filtrar por cliente.",
+      inputSchema: { cliente: z.string().optional() },
+    }, async ({ cliente }) => run(() => api("GET", `/wms/productos${q({ cliente })}`)));
+
+    tool("top_productos", {
+      title: "Productos más despachados del nodo",
+      description: "Ranking de productos más despachados del nodo en un rango (default: mes en curso). Opcional: filtrar por un cliente.",
+      inputSchema: { desde: z.string().optional().describe("YYYY-MM-DD"), hasta: z.string().optional().describe("YYYY-MM-DD"), cliente: z.string().optional() },
+    }, async ({ desde, hasta, cliente }) => run(() => api("GET", `/wms/top-productos${q({ desde, hasta, cliente })}`)));
+  }
+}
+
+// ============================================================================
+//  ROL GLOBAL (superadmin / superoperador)
+// ============================================================================
+if (esGlobal) {
+  tool("nodos_listar", {
+    title: "Listar nodos",
+    description: "Lista todas las logísticas (nodos) con sus conteos. Solo admin global.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/logisticas")));
+
+  tool("kpi_red", {
+    title: "Métricas de la red (SaaS)",
+    description: "KPIs globales de toda la red de nodos (crecimiento, operacional, volumen de clearing). Solo admin global.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/kpi/saas")));
+}
+
+// ============================================================================
+//  ESCRITURA (opt-in por flag · NUNCA dinero). Además gateado por permiso en el backend.
+// ============================================================================
+if (ALLOW_WRITE) {
+  if (puede("gestion")) {
+    tool("cliente_crear", {
+      title: "Crear cliente / vendedor",
+      description: "Da de alta un cliente en TU nodo (el backend fuerza el nodo). Podés asignarle la lista de precio con idLista. No toca dinero.",
+      inputSchema: {
+        nombre: z.string().min(1).describe("Nombre del cliente"),
+        telefono: z.string().optional(),
+        dni: z.string().optional(),
+        direccion: z.string().optional(),
+        idLista: z.string().optional().describe("ID de la lista de precios a asignar (ej. 'B'). Consultá 'clientes_del_nodo'."),
+      },
+    }, async (args) => run(() => api("POST", "/gestion/clientes", args)));
+
+    tool("cliente_editar", {
+      title: "Editar cliente (incluye cambiar su lista)",
+      description: "Edita un cliente de TU nodo. Para cambiarle la lista de precio pasá idLista. El nombre es obligatorio (traelo de 'clientes_del_nodo'). No toca dinero.",
+      inputSchema: {
+        id: z.number().int().positive().describe("ID del cliente"),
+        nombre: z.string().min(1).describe("Nombre actual del cliente (obligatorio)"),
+        idLista: z.string().optional().describe("Nueva lista de precio a asignar"),
+        telefono: z.string().optional(),
+        dni: z.string().optional(),
+        direccion: z.string().optional(),
+      },
+    }, async ({ id, ...body }) => run(() => api("PUT", `/gestion/clientes/${id}`, body)));
+  }
+
+  if (puede("wms") && wmsActivo) {
+    tool("producto_crear", {
+      title: "Crear producto (WMS)",
+      description: "Alta de un producto en el catálogo del depósito. Staff puede indicar el cliente dueño con idCliente. No toca dinero.",
+      inputSchema: {
+        nombre: z.string().min(1),
+        sku: z.string().optional(),
+        codigoBarra: z.string().optional(),
+        peso: z.number().optional(),
+        volumen: z.number().optional(),
+        idCliente: z.string().optional().describe("idCliente dueño del producto"),
+      },
+    }, async (args) => run(() => api("POST", "/wms/productos", args)));
+  }
+
+  if (esGlobal) {
+    tool("nodo_crear", {
+      title: "Crear nodo (logística)",
+      description: "Da de alta un nodo/logística nuevo. Solo admin global. No toca dinero.",
+      inputSchema: {
+        nombre: z.string().min(1).describe("Nombre del nodo/logística"),
+        telefono: z.string().optional(),
+      },
+    }, async ({ nombre, telefono }) => run(() => api("POST", "/logisticas", { nombre, telefono: telefono ?? null })));
+  }
+}
+
+// ============================================================================
+//  EDICIÓN DE PRECIOS (flag aparte · sensible pero NO mueve dinero).
+// ============================================================================
+if (ALLOW_PRECIOS && puede("precios")) {
+  tool("precio_actualizar", {
+    title: "Actualizar precio de una lista (versionado)",
+    description: "Cambia los precios por zona de una lista creando una VERSIÓN nueva (histórico exacto). Requiere permiso 'precios'; el backend impide tocar listas de otro nodo. No mueve dinero.",
+    inputSchema: {
+      idLista: z.string().min(1).describe("ID de la lista (ej. 'B'). Ver 'precios_ver'."),
+      cercana: z.number().optional().describe("Precio zona cercana"),
+      media: z.number().optional().describe("Precio zona media"),
+      lejana: z.number().optional().describe("Precio zona lejana"),
+      muyLejana: z.number().optional().describe("Precio zona muy lejana"),
+      referencia: z.string().optional(),
+      vigenciaDesde: z.string().optional().describe("YYYY-MM-DD desde cuándo rige (default: hoy)"),
+    },
+  }, async (args) => run(() => api("POST", "/precios/clientes/version", args)));
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+const cap = isCliente ? "cliente" : esGlobal ? "admin global" : isStaff ? "staff de nodo" : "sin identidad";
+log(`MCP Nexus Flex v3 listo. Rol: ${cap}. Escritura: ${ALLOW_WRITE ? "ON" : "off"} · Precios: ${ALLOW_PRECIOS ? "ON" : "off"}.`);