nexusflex-mcp 3.0.0 → 3.6.0

package/server.mjs

@@ -1,315 +1,744 @@
-#!/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"}.`);
+#!/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";
+import { renderAyuda, guiaOnboarding } from "./docs.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 MCP_VERSION = "3.6.0"; // bumpear junto con package.json + backend/services/mcp-remote.ts
+const NOVEDADES = [
+  "3.6.0 — Guía de arranque por rol (`guia` + instrucciones al conectar): metodología para empezar rápido (mensajero: foto→envío al colectar; vendedor: cargar ventas; nodo: implementar + operar + clearing). Los MENSAJEROS ya pueden registrar envíos de lo que colectan (`envio_cargar` / `envio_desde_etiqueta_ml`), scopeado a clientes de su nodo o que hayan colectado (marketplace incluido).",
+  "3.5.0 — Ayuda integrada (`ayuda`): documentación por herramienta (qué hace, cómo usar, ejemplo, qué NO hace) + temas transversales (facturacion_marketplace, dinero, aislamiento). Aclarado que adjudicar una ruta del marketplace NO genera facturación/rendición/comisión automática (el pago entre nodos es manual).",
+  "3.4.0 — Marketplace de rutas públicas (ruta_publicar/ofertar/adjudicar); admin también reparte; registrar envío desde foto de etiqueta ML; alta/edición de choferes; mcp_version.",
+  "3.3.0 — Afiliados y comisión por envío; métricas por tipo; gestión de colectas (asignar/rechazar entre nodos); cuentas vinculadas; sucursales; colecta a pedido; metazonas flexibles.",
+];
+const INSTRUCCIONES = "MCP de Nexus Flex. Para arrancar rápido llamá al tool `guia` (metodología según tu rol: mensajero/vendedor/nodo) y `ayuda` (índice de herramientas + temas). El MCP NUNCA mueve dinero.";
+const server = new McpServer({ name: "nexusflex", version: MCP_VERSION }, { instructions: INSTRUCCIONES });
+
+/** 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 registrados = new Set(); // para que `ayuda` liste solo lo que este usuario tiene
+const tool = (name, def, handler) => { registrados.add(name); 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")));
+
+// Versión del MCP corriendo (cualquier rol). Sirve para saber si tenés lo último.
+tool("mcp_version", {
+  title: "Versión del MCP",
+  description: "Qué versión del MCP de Nexus Flex está corriendo y por qué vía. Cualquier rol lo puede consultar.",
+  inputSchema: {},
+}, async () => ({ content: [{ type: "text", text: JSON.stringify({ version: MCP_VERSION, modo: "npx (Claude Desktop)", novedades: NOVEDADES, nota: "Para tener lo último: actualizá con «npx -y nexusflex-mcp@latest» o pasate al conector remoto (siempre al día, sin instalar/actualizar)." }) }] }));
+
+// Guía de arranque por rol (metodología). Cualquier rol; read-only.
+tool("guia", {
+  title: "Guía de arranque (metodología para tu rol)",
+  description: "Cómo empezar a usar Nexus Flex rápido según tu rol: mensajero (registrar lo que colectás sacando fotos → envío), vendedor (cargar ventas), nodo (implementar + operar + clearing). Sin argumentos = tu rol; `rol` para ver otra (mensajero|cliente|nodo).",
+  inputSchema: { rol: z.string().optional().describe("mensajero | cliente | nodo (default: tu rol)") },
+}, async ({ rol: r }) => {
+  const pedido = String(r ?? "").trim().toLowerCase();
+  const target = pedido === "nodo" ? "operador" : pedido || rol;
+  return { content: [{ type: "text", text: guiaOnboarding(target) }] };
+});
+
+// Sugerencias: cualquier usuario (todos los roles) puede proponer funciones/mejoras.
+tool("sugerencia_crear", {
+  title: "Enviar una sugerencia",
+  description: "Proponé una función nueva, mejora o reportá un bug. mensaje obligatorio; categoria opcional (funcionalidad|mejora|bug|otro). Se registra tu usuario/rol/nodo automáticamente.",
+  inputSchema: { mensaje: z.string().min(1), categoria: z.enum(["funcionalidad", "mejora", "bug", "otro"]).optional() },
+}, async (args) => run(() => api("POST", "/feedback/sugerencias", args)));
+
+// ============================================================================
+//  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 })}`)));
+  tool("mis_sucursales", {
+    title: "Mis sucursales / puntos de retiro",
+    description: "Tus sucursales (puntos de retiro) con dirección, horario de corte y ventanas. La sucursal principal es tu dirección de retiro. Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/portal/sucursales")));
+  tool("mi_colecta", {
+    title: "Estado de mi colecta",
+    description: "Cómo está tu colecta (retiro): si la colecta AUTOMÁTICA está prendida, si pediste una por única vez, y el aviso de costo (si te cobran cuando llevás menos de X envíos). Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/portal/colecta")));
+}
+
+// ============================================================================
+//  ROL MENSAJERO — su ruta y colectas (para saber cuántos envíos tendrá).
+// ============================================================================
+if (rol === "mensajero") {
+  tool("mi_ruta", {
+    title: "Mi ruta del día",
+    description: "Tus entregas asignadas (paradas de la ruta del día). Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/flujo/mi-ruta")));
+  tool("mis_colectas", {
+    title: "Mis colectas (retiros)",
+    description: "Las colectas/retiros que tenés asignados. Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/colecta/mis-colectas")));
+}
+
+// ============================================================================
+//  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")));
+}
+
+// ============================================================================
+//  VINCULACIÓN DE TIENDAS — genera el enlace de autorización (OAuth) para traer las
+//  ventas de una tienda a Nexus Flex. Un vendedor genera el SUYO; el staff (permiso
+//  gestion) puede generarlo PARA un cliente de SU nodo y mandárselo. No toca dinero.
+// ============================================================================
+if (isCliente || (isStaff && puede("gestion"))) {
+  tool("generar_enlace_vinculacion", {
+    title: "Generar enlace de vinculación de tienda",
+    description: "Genera el enlace (link) para vincular una tienda —Mercado Libre, TiendaNube o Tienda Negocio— y traer sus ventas a Nexus Flex. Si sos vendedor genera el TUYO; si sos staff podés generarlo PARA un cliente de tu nodo pasando 'cliente' (idCliente de 'clientes_del_nodo') y mandarle ese enlace para que lo autorice desde su propia cuenta de la tienda. El enlace vence en 15 minutos. No toca dinero.",
+    inputSchema: {
+      proveedor: z.enum(["ml", "tiendanube", "tiendanegocio"]).describe("ml = Mercado Libre · tiendanube · tiendanegocio"),
+      cliente: z.string().optional().describe("Solo staff: idCliente del vendedor para el que generás el enlace. El backend valida que sea de TU nodo (si no, 403)."),
+    },
+  }, async ({ proveedor, cliente }) => run(() => api("GET", `/${proveedor}/auth${q({ cliente })}`)));
+}
+
+// ============================================================================
+//  RENDICIONES (lectura) + ZONAS DE REPARTO (mensajeros por zona)
+// ============================================================================
+if (isCliente || isStaff || rol === "mensajero") {
+  tool("rendiciones", {
+    title: "Rendiciones (a recuperar / a rendir)",
+    description: "Estado de rendiciones: cobros/cambios/devoluciones pendientes de recuperar o rendir, con totales y quién tiene cada uno. Scopeado a tu alcance (vendedor: lo tuyo; nodo: tu nodo). Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/flujo/rendiciones")));
+}
+
+// Reclamos de clientes ligados a liquidaciones (vendedor: lo suyo; operador: su nodo).
+if (isCliente || isStaff) {
+  tool("reclamos_listar", {
+    title: "Reclamos de clientes (liquidaciones)",
+    description: "Reclamos abiertos de clientes ligados a liquidaciones/rendiciones: tipo, estado, trackings en disputa, detalle. Sirve para ver qué cobros/rendiciones pendientes tienen reclamo. Vendedor ve lo suyo, operador su nodo. Solo lectura.",
+    inputSchema: { estado: z.string().optional().describe("abierto | resuelto") },
+  }, async ({ estado }) => run(() => api("GET", `/feedback/reclamos${q({ estado })}`)));
+}
+if (isStaff) {
+  tool("sugerencias_listar", {
+    title: "Sugerencias de usuarios (admin)",
+    description: "Sugerencias entrantes de los usuarios (funciones nuevas/mejoras/bugs) con usuario, rol, nodo, estado. Filtrá por `rol` y/o `estado`. Operador: las de su nodo; admin global: todas. Solo lectura.",
+    inputSchema: { rol: z.string().optional(), estado: z.string().optional().describe("nueva | vista | en_evaluacion | implementada | descartada") },
+  }, async ({ rol, estado }) => run(() => api("GET", `/feedback/sugerencias${q({ rol, estado })}`)));
+}
+
+// Consultar UN envío por tracking/código (cuando un vendedor pregunta "¿dónde está mi
+// envío X?"). Vendedor: solo entre SUS envíos; staff: dentro de su nodo.
+if (isCliente || isStaff) {
+  tool("envio_consultar", {
+    title: "Consultar un envío",
+    description: "Busca UN envío por tracking o código y devuelve su estado actual, el historial de estados (con fechas), destinatario, dirección y datos de cobro/cambio si tiene. Vendedor: solo entre SUS envíos; staff: dentro de su nodo. Úsalo cuando un vendedor pregunta por un pedido puntual.",
+    inputSchema: { codigo: z.string().min(1).describe("Tracking o código del envío (lo que manda el vendedor)") },
+  }, async ({ codigo }) => {
+    const code = String(codigo ?? "").trim();
+    if (!code) return { content: [{ type: "text", text: "Pasá un tracking o código de envío." }], isError: true };
+    const low = code.toLowerCase();
+    try {
+      if (isStaff) {
+        const lista = await api("GET", `/flujo/envios${q({ q: code })}`);
+        const rows = Array.isArray(lista.data) ? lista.data : [];
+        if (!rows.length) return { content: [{ type: "text", text: `No encontré un envío "${code}" en tu nodo.` }] };
+        const exact = rows.filter((e) => String(e.tracking ?? "").toLowerCase() === low);
+        const pick = exact.length ? exact : rows;
+        if (pick.length > 1)
+          return { content: [{ type: "text", text: `Varios envíos matchean "${code}". Elegí uno (pasá el tracking completo):\n${JSON.stringify(pick.slice(0, 10).map((e) => ({ id: e.id, tracking: e.tracking, estado: e.estado, cliente: e.cliente, destinatario: e.destinatario })), null, 2)}` }] };
+        return toResult(await api("GET", `/flujo/envios/${pick[0].id}`));
+      }
+      const lista = await api("GET", "/portal/envios");
+      const rows = Array.isArray(lista.data) ? lista.data : [];
+      let match = rows.filter((e) => String(e.tracking ?? "").toLowerCase() === low);
+      if (!match.length) match = rows.filter((e) => String(e.tracking ?? "").toLowerCase().includes(low));
+      if (!match.length) return { content: [{ type: "text", text: `No encontré un envío "${code}" entre tus envíos.` }] };
+      if (match.length > 1)
+        return { content: [{ type: "text", text: `Varios envíos matchean "${code}". Pasá el tracking completo:\n${JSON.stringify(match.slice(0, 10).map((e) => ({ id: e.id, tracking: e.tracking, estado: e.estado })), null, 2)}` }] };
+      return toResult(await api("GET", `/portal/envios/${match[0].id}`));
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+  });
+}
+
+// Métricas por tipo de envío (flex/tienda/manual) + % antes de 21hs + (red) por logística.
+if (isCliente || isStaff) {
+  tool("metricas_por_tipo", {
+    title: "Métricas por tipo de envío",
+    description: "Métricas por TIPO de envío (flex/tienda/manual): total, entregados, tasa de entrega y % ENTREGADO ANTES DE LAS 21hs. Admin/red desglosa por logística (qué nodo entrega mejor). Vendedor ve lo suyo, operador su nodo. Fechas YYYY-MM-DD (default: últimos 30 días).",
+    inputSchema: {
+      desde: z.string().optional().describe("YYYY-MM-DD"),
+      hasta: z.string().optional().describe("YYYY-MM-DD"),
+      nodo: z.number().optional().describe("Solo admin/superoperador: elegir nodo (si no, la red)"),
+    },
+  }, async ({ desde, hasta, nodo }) => run(() => api("GET", `/kpi/envios-por-tipo${q({ desde, hasta, nodo })}`)));
+}
+
+// Cuentas de tienda vinculadas (ML / TiendaNube / TiendaNegocio), scopeadas por rol.
+if (isCliente || isStaff) {
+  tool("cuentas_vinculadas", {
+    title: "Cuentas vinculadas (ML / TiendaNube / TiendaNegocio)",
+    description: "Cuántas cuentas de tienda hay vinculadas, con desglose por proveedor (Mercado Libre / TiendaNube / TiendaNegocio). Vendedor: las suyas; operador: las de los clientes de SU nodo (agrupadas por cliente); admin/superoperador: por nodo (o pasá `nodo` para bajar al desglose por cliente de ese nodo). Solo lectura.",
+    inputSchema: { nodo: z.number().optional().describe("Solo admin: baja al desglose por cliente de ese nodo") },
+  }, async ({ nodo }) => run(() => api("GET", `/cuentas-vinculadas${q({ nodo })}`)));
+}
+
+// Afiliados: comisión recurrente por envío (staff = admin global o admin de nodo, scopeado).
+if (isStaff) {
+  tool("afiliacion_listar", {
+    title: "Listar afiliaciones",
+    description: "Afiliaciones (afiliado↔entidad referida) con su comisión por envío, vigencia y estado. Filtrá por `afiliado` o `entidad`. Solo lectura, scopeado a tu nodo.",
+    inputSchema: { afiliado: z.string().optional(), entidad: z.string().optional() },
+  }, async ({ afiliado, entidad }) => run(() => api("GET", `/afiliados/afiliaciones${q({ afiliado, entidad })}`)));
+  tool("comisiones_afiliado_ver", {
+    title: "Comisiones de afiliados",
+    description: "Comisiones devengadas por envío (pendiente/liquidada) con totales. Filtrá por `afiliado` y rango de fechas. Solo lectura, scopeado a tu nodo.",
+    inputSchema: { afiliado: z.string().optional(), desde: z.string().optional().describe("YYYY-MM-DD"), hasta: z.string().optional().describe("YYYY-MM-DD") },
+  }, async ({ afiliado, desde, hasta }) => run(() => api("GET", `/afiliados/comisiones${q({ afiliado, desde, hasta })}`)));
+}
+
+// Choferes (mensajeros) del nodo — requiere permiso 'usuarios'.
+if (isStaff && puede("usuarios")) {
+  tool("chofer_listar", {
+    title: "Listar usuarios del nodo (choferes)",
+    description: "Usuarios de tu nodo (incluye los choferes = rol 'mensajero') con su id, nombre, teléfono, activo. Solo lectura, scopeado a tu nodo.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/usuarios")));
+}
+
+// Marketplace de rutas/colectas públicas (subasta abierta, cualquier nodo de la red).
+if (isStaff) {
+  tool("rutas_publicas", {
+    title: "Rutas/colectas públicas (marketplace)",
+    description: "Publicaciones ABIERTAS de toda la red que tu nodo puede tomar (con cuántas ofertas tiene cada una). Marca las tuyas (`esMia`). Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/rutas-publicas/publicas")));
+  tool("mis_rutas", {
+    title: "Mis publicaciones y ofertas (marketplace)",
+    description: "Tus publicaciones de rutas (con su estado/adjudicación) y las ofertas que hiciste a otros nodos. Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/rutas-publicas/mias")));
+  tool("ruta_ofertas", {
+    title: "Ver ofertas de una publicación mía",
+    description: "Ofertas recibidas en una publicación TUYA (ordenadas por precio asc). Solo el que publicó. Usá el id de oferta para adjudicar.",
+    inputSchema: { publicacionId: z.number().int().positive() },
+  }, async ({ publicacionId }) => run(() => api("GET", `/rutas-publicas/${publicacionId}/ofertas`)));
+}
+
+if (isStaff && puede("gestion")) {
+  tool("zonas_reparto", {
+    title: "Zonas de reparto (mensajeros por zona)",
+    description: "Lista las zonas de reparto de tu nodo con sus metazonas y qué mensajeros tiene asignado cada una. Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/zonificacion/zonas-reparto")));
+
+  tool("colecta_ver", {
+    title: "Ver config de colectas",
+    description: "Resumen de valores de colecta del nodo: pago default del nodo, cobros por cliente y pagos pactados por cliente+mensajero. Solo lectura.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/colecta/config")));
+
+  tool("colecta_pendientes", {
+    title: "Colectas del día y de mañana",
+    description: "Panel de colectas de tu nodo. `items` = clientes a retirar HOY (con cuántos envíos, el corte y qué colecta está asignada a qué mensajero). `itemsManana` = clientes con envíos que entraron después del corte → van a la colecta de MAÑANA. Solo lectura. Sirve para «¿quién levanta a tal cliente?» y «¿el cliente X tiene envíos para mañana?».",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/colecta/panel")));
+
+  tool("envios_por_zona", {
+    title: "Envíos que otros nodos te rutearon (por zona)",
+    description: "Envíos de OTROS nodos ruteados a tu nodo por zona de reparto, agrupados por zona (para aceptarlos o rechazarlos). Cada envío trae su id (usalo en procesar_zona/rechazar_zona). Solo lectura, tu nodo.",
+    inputSchema: {},
+  }, async () => run(() => api("GET", "/colecta/zonas-a-procesar")));
+
+  tool("asignar_mensajero_zona", {
+    title: "Asignar un mensajero a una zona",
+    description: "Asigna un mensajero (por nombre, de tu nodo) a una metazona/zona (ej. «asigná a Maxi la zona de Palermo»). Si ya existe una zona con esa metazona, le suma el mensajero; si no, la crea. No cruza nodos.",
+    inputSchema: {
+      mensajero: z.string().min(1).describe("Nombre del mensajero (de tu nodo)"),
+      metazona: z.string().min(1).describe("Metazona/zona, ej. 'Palermo' o 'CABA'"),
+      nombre: z.string().optional().describe("Nombre de la zona (opcional)"),
+    },
+  }, async (args) => run(() => api("POST", "/zonificacion/zonas-reparto/asignar-mensajero", args)));
+
+  tool("asignar_nodo_zona", {
+    title: "Asignar un NODO a una zona (grupo logístico)",
+    description: "Asigna un NODO COMPLETO (por nombre, de tu grupo logístico) a una metazona — para cuando ese nodo cubre toda una localidad (ej. «que RL cubra Portela»). Suma el nodo como opción de esa zona (nodoIds). El nodo debe compartir grupo logístico con el tuyo. No cruza fuera del grupo.",
+    inputSchema: {
+      nodo: z.string().min(1).describe("Nombre del nodo de tu grupo logístico que cubre la zona"),
+      metazona: z.string().min(1).describe("Metazona/zona, ej. 'Portela' o 'CABA'"),
+      nombre: z.string().optional().describe("Nombre de la zona (opcional)"),
+    },
+  }, async (args) => run(() => api("POST", "/zonificacion/zonas-reparto/asignar-nodo", args)));
+}
+
+// ============================================================================
+//  ESCRITURA (opt-in por flag · NUNCA dinero). Además gateado por permiso en el backend.
+// ============================================================================
+if (ALLOW_WRITE) {
+  if (isCliente) {
+    tool("sucursal_guardar", {
+      title: "Crear/editar sucursal (punto de retiro)",
+      description: "Crea o edita una sucursal tuya (punto de retiro). Para cambiar tu DIRECCIÓN DE RETIRO editá la sucursal principal (o creá una con principal=true). id vacío = nueva sucursal. Geocodifica la dirección sola. No toca dinero.",
+      inputSchema: {
+        id: z.number().optional().describe("id de la sucursal a editar; vacío = nueva"),
+        nombre: z.string().min(1),
+        direccion: z.string().optional(),
+        principal: z.boolean().optional().describe("true = pasa a ser tu dirección de retiro principal"),
+        horarioCorte: z.string().optional().describe("HH:MM"),
+        ventana1Desde: z.string().optional(), ventana1Hasta: z.string().optional(),
+        ventana2Desde: z.string().optional(), ventana2Hasta: z.string().optional(),
+      },
+    }, async (args) => run(() => api("POST", "/portal/sucursales", args)));
+    tool("colecta_solicitar", {
+      title: "Solicitar colecta (por única vez)",
+      description: "Pedís que te retiren los envíos POR ÚNICA VEZ, aunque tengas la colecta automática apagada. Aparecés en el panel de colecta de tu nodo. Devuelve el aviso de costo (si te cobran cuando llevás menos de X envíos). No mueve dinero.",
+      inputSchema: {},
+    }, async () => run(() => api("POST", "/portal/colecta/solicitar")));
+    tool("colecta_auto", {
+      title: "Prender/apagar colecta automática",
+      description: "Activás (true) o desactivás (false) tu colecta AUTOMÁTICA. Apagada = llevás los envíos al depósito y no te retiran (salvo que pidas una por única vez con colecta_solicitar). No mueve dinero.",
+      inputSchema: { activa: z.boolean() },
+    }, async ({ activa }) => run(() => api("PUT", "/portal/colecta/auto", { activa })));
+  }
+  if (isCliente || (isStaff && puede("gestion")) || rol === "mensajero") {
+    tool("envio_cargar", {
+      title: "Cargar un envío (y etiqueta)",
+      description: "Registra un envío nuevo (queda 'A retirar') y devuelve el tracking + un LINK a la etiqueta imprimible + un LINK para subir una foto del envío desde el celular. El vendedor lo carga para sí mismo; el staff pasa `cliente` (nombre, de su nodo); el MENSAJERO pasa `cliente` y SOLO puede registrar clientes de su nodo o que haya colectado (marketplace incluido). Datos obligatorios: destinatario, telefono, direccion, localidad. No toca dinero (montoCobro es el cobro contra entrega, no un movimiento).",
+      inputSchema: {
+        cliente: z.string().optional().describe("Solo staff: nombre del cliente/vendedor de tu nodo (el vendedor NO lo manda)"),
+        destinatario: z.string().min(1).describe("Nombre de quien recibe"),
+        telefono: z.string().min(1),
+        direccion: z.string().min(1),
+        localidad: z.string().min(1),
+        cp: z.string().optional(),
+        montoCobro: z.number().optional().describe("Cobro contra entrega (opcional)"),
+        esCambio: z.boolean().optional(),
+        detalleCambio: z.string().optional(),
+        comentarios: z.string().optional(),
+      },
+    }, async (args) => run(() => api("POST", "/envios/cargar-mcp", args)));
+  }
+  if (isStaff || rol === "mensajero") {
+    tool("envio_desde_etiqueta_ml", {
+      title: "Registrar envío desde una etiqueta de Mercado Libre (foto)",
+      description: "Registra un envío a partir de los datos que VOS (Claude) leíste de la foto de una etiqueta de Mercado Libre. Leé la etiqueta: sacá el CÓDIGO/QR (mlShipmentId y, si podés, el contenido crudo del QR en mlQr), el vendedor (mlSenderId si figura) y el destino (destinatario, dirección, localidad, CP). El vendedor se mapea por `mlSenderId` (cuenta ML vinculada) o pasás `cliente` por nombre; staff = de tu nodo o grupo; MENSAJERO = solo clientes de tu nodo o que hayas colectado (marketplace incluido). Crea el envío ('A retirar') y devuelve tracking + link de etiqueta PROVISORIA (con el QR de ML si mandaste mlQr, reimprimible). Si NO hay etiqueta pero tenés los datos del paquete, usá `envio_cargar`. Podés pasar varias etiquetas llamando el tool una vez por cada una. No mueve dinero.",
+      inputSchema: {
+        cliente: z.string().optional().describe("Vendedor por nombre/id (si no mandás mlSenderId)"),
+        mlSenderId: z.string().optional().describe("sender_id del vendedor en ML (mapea a su cuenta vinculada)"),
+        mlShipmentId: z.string().optional().describe("id de envío/tracking de ML leído de la etiqueta"),
+        mlQr: z.string().optional().describe("Contenido CRUDO del QR de ML (para reimprimir la etiqueta idéntica)"),
+        destinatario: z.string().optional(), telefono: z.string().optional(),
+        direccion: z.string().optional(), localidad: z.string().optional(), cp: z.string().optional(), zona: z.string().optional(), barrio: z.string().optional(),
+        montoCobro: z.number().optional(), mensajero: z.string().optional().describe("Mensajero que hizo el paquete (de tu nodo)"),
+      },
+    }, async (args) => run(() => api("POST", "/envios/desde-etiqueta", args)));
+    tool("afiliado_crear", {
+      title: "Crear afiliado",
+      description: "Alta de un afiliado (quien trae volumen nuevo a la red). tipo: nodo|mensajero|externo; refId = id del nodo/mensajero (null si externo). Admin global o admin de nodo (scopeado a tu nodo). NO toca dinero.",
+      inputSchema: { nombre: z.string().min(1), tipo: z.enum(["nodo", "mensajero", "externo"]), refId: z.number().int().optional(), telefono: z.string().optional(), email: z.string().optional() },
+    }, async (args) => run(() => api("POST", "/afiliados", args)));
+    tool("afiliacion_crear", {
+      title: "Crear afiliación (comisión por envío)",
+      description: "Vincula un afiliado con una entidad referida (nodo o cliente) y su comisión RECURRENTE por envío. tipoComision: porcentaje|montoFijo. `porcentaje` se calcula sobre el valorDeclarado del envío (MVP); `montoFijo` = monto por envío. fechaExpiracion opcional (null = no vence). Una entidad = un solo afiliado activo. NO toca dinero (es config).",
+      inputSchema: { afiliado: z.string().min(1).describe("nombre o id"), entidadTipo: z.enum(["nodo", "cliente"]), entidad: z.string().min(1).describe("nombre o id del nodo/cliente referido"), tipoComision: z.enum(["porcentaje", "montoFijo"]), valorComision: z.number(), fechaExpiracion: z.string().optional().describe("YYYY-MM-DD") },
+    }, async (args) => run(() => api("POST", "/afiliados/afiliaciones", args)));
+    tool("afiliacion_editar", {
+      title: "Editar afiliación",
+      description: "Edita una afiliación: valorComision, fechaExpiracion (renovar/extender) y/o activa (des/reactivar). NO toca dinero.",
+      inputSchema: { id: z.number().int().positive(), valorComision: z.number().optional(), fechaExpiracion: z.string().optional().describe("YYYY-MM-DD; vacío = quitar vencimiento"), activa: z.boolean().optional() },
+    }, async ({ id, ...body }) => run(() => api("PUT", `/afiliados/afiliaciones/${id}`, body)));
+    if (esGlobal || esAdminNodo || permisos.includes("finanzas")) { // igual que el gate del backend
+      tool("comision_liquidar", {
+        title: "Liquidar comisiones de afiliado (registra pago)",
+        description: "Marca comisiones devengadas como LIQUIDADAS (registra el pago al afiliado). `ids` = lista de comisiones (de comisiones_afiliado_ver). Requiere permiso de finanzas. Scopeado a tu nodo.",
+        inputSchema: { ids: z.array(z.number().int().positive()).min(1) },
+      }, async ({ ids }) => run(() => api("POST", "/afiliados/comisiones/liquidar", { ids })));
+    }
+  }
+  if (puede("usuarios")) {
+    tool("chofer_crear", {
+      title: "Alta de chofer (mensajero) con clave temporal",
+      description: "Da de alta un chofer (rol mensajero) en TU nodo. El server genera una CLAVE TEMPORAL y la devuelve (pasásela al chofer; debe cambiarla al primer ingreso). Requiere nombre, teléfono y email.",
+      inputSchema: { nombre: z.string().min(1), telefono: z.string().min(1), email: z.string().min(3), mensajeroNombre: z.string().optional().describe("Nombre para el macheo con su cta cte (default: el nombre)") },
+    }, async (args) => run(() => api("POST", "/usuarios/chofer", args)));
+    tool("chofer_editar", {
+      title: "Editar un chofer",
+      description: "Edita un chofer (mensajero) de TU nodo: nombre, teléfono, mensajeroNombre y/o activo (desactivar/activar). No toca credenciales.",
+      inputSchema: { id: z.number().int().positive(), nombre: z.string().optional(), telefono: z.string().optional(), mensajeroNombre: z.string().optional(), activo: z.boolean().optional() },
+    }, async ({ id, ...body }) => run(() => api("PUT", `/usuarios/chofer/${id}`, body)));
+    tool("usuario_habilitar_reparto", {
+      title: "Habilitar a un usuario como también mensajero",
+      description: "Marca (o desmarca con activo=false) a un operador/admin de TU nodo como TAMBIÉN mensajero: puede escanear, autoasignarse y entregar además de administrar. No toca credenciales.",
+      inputSchema: { id: z.number().int().positive(), activo: z.boolean().optional().describe("default true") },
+    }, async ({ id, activo }) => run(() => api("PUT", `/usuarios/${id}/reparto`, { activo: activo ?? true })));
+  }
+  if (isStaff) {
+    tool("ruta_publicar", {
+      title: "Publicar una ruta/colecta en el marketplace",
+      description: "Publicá una ruta/colecta/viaje para que CUALQUIER nodo de la red la tome (subasta abierta). VOS le pagás al que la toma. precioMax opcional (tope que ofrecés pagar). No mueve dinero (la obligación se registra al adjudicar).",
+      inputSchema: { titulo: z.string().min(1), tipo: z.enum(["ruta", "colecta", "viaje"]).optional(), descripcion: z.string().optional(), zona: z.string().optional(), precioMax: z.number().optional() },
+    }, async (args) => run(() => api("POST", "/rutas-publicas", args)));
+    tool("ruta_ofertar", {
+      title: "Ofertar por una ruta pública",
+      description: "Ofertá por una publicación de OTRO nodo: `precio` = lo que cobrás por hacerla (subasta: más barato es mejor para el que publica). Si ya ofertaste, actualiza tu oferta. No podés ofertar en la tuya.",
+      inputSchema: { publicacionId: z.number().int().positive(), precio: z.number(), nota: z.string().optional() },
+    }, async (args) => run(() => api("POST", `/rutas-publicas/${args.publicacionId}/ofertar`, { precio: args.precio, nota: args.nota })));
+    tool("ruta_adjudicar", {
+      title: "Adjudicar una ruta pública (elegir ganador)",
+      description: "Elegí la oferta ganadora de una publicación TUYA (los ids salen de «ruta_ofertas»). Cierra la subasta: el nodo ganador la toma al precio de su oferta (queda registrada la obligación). NO genera facturación/rendición/comisión ni clearing automático: el pago entre nodos se salda MANUALMENTE (ver «ayuda» tema:facturacion_marketplace).",
+      inputSchema: { publicacionId: z.number().int().positive(), ofertaId: z.number().int().positive() },
+    }, async ({ publicacionId, ofertaId }) => run(() => api("POST", `/rutas-publicas/${publicacionId}/adjudicar`, { ofertaId })));
+  }
+  if (isStaff) {
+    tool("envio_reasignar_cliente", {
+      title: "Reasignar un envío a otro cliente",
+      description: "Mueve UN envío (por tracking) a otro cliente/vendedor de TU nodo cuando se cargó mal. Deja registro en el historial. Igual que la función del frontend.",
+      inputSchema: { tracking: z.string().min(1), cliente: z.string().min(1).describe("nombre o id del cliente destino (de tu nodo)") },
+    }, async (args) => run(() => api("POST", "/envios/reasignar-cliente", args)));
+    tool("cobro_corregir", {
+      title: "Corregir el monto de un cobro",
+      description: "Ajusta el monto a cobrar contra entrega de un envío (cuando se cobró de más o de menos), guardando el monto ORIGINAL en el historial. envioId + monto nuevo. No mueve dinero en cuentas (corrige el dato del envío).",
+      inputSchema: { envioId: z.number().int().positive(), monto: z.number(), motivo: z.string().optional() },
+    }, async ({ envioId, monto, motivo }) => run(() => api("POST", `/envios/${envioId}/corregir-cobro`, { monto, motivo })));
+    tool("rendicion_revertir", {
+      title: "Revertir una rendición (marcada por error)",
+      description: "Revierte un cobro/cambio marcado como 'rendido' cuando en realidad NO se rindió → vuelve a 'a rendir'. Deja registro (quién/cuándo). envioId + tipo (cobro|cambio). Scopeado a tu nodo.",
+      inputSchema: { envioId: z.number().int().positive(), tipo: z.enum(["cobro", "cambio"]), motivo: z.string().optional() },
+    }, async (args) => run(() => api("POST", "/flujo/rendicion/revertir", args)));
+  }
+  if (puede("gestion")) {
+    tool("colecta_configurar", {
+      title: "Configurar valor de colecta",
+      description: "Setea un valor de colecta según alcance: 'nodo' = pago default del nodo (ej. $3000); 'mensajero' = default de ese mensajero (ej. $4000, cualquier colecta); 'cliente' = cuánto se le COBRA al vendedor (idCliente + valor, opcional minEnvios); 'par' = pago pactado a un mensajero por colectar a un cliente (idCliente + mensajero + valor). Scopeado a tu nodo. No mueve dinero (config de tarifa).",
+      inputSchema: {
+        alcance: z.enum(["nodo", "mensajero", "cliente", "par"]),
+        valor: z.number(),
+        idCliente: z.string().optional(),
+        mensajero: z.string().optional().describe("Nombre del mensajero (de tu nodo)"),
+        minEnvios: z.number().optional().describe("Solo alcance=cliente: mínimo de envíos para colecta sin cargo"),
+      },
+    }, async (args) => run(() => api("POST", "/colecta/config", args)));
+
+    tool("colecta_asignar", {
+      title: "Asignar una colecta a un mensajero",
+      description: "Asigna la colecta (retiro de mercadería) de un cliente a un mensajero, ambos por NOMBRE de tu nodo (ej. «que Maxi levante al cliente Distri Sur»). Vincula los envíos 'A retirar' de ese cliente a la colecta y avisa al mensajero. Si el corte venció, la programa para el próximo día hábil. No mueve dinero (es logística).",
+      inputSchema: {
+        cliente: z.string().min(1).describe("Nombre del cliente/vendedor a colectar"),
+        mensajero: z.string().min(1).describe("Nombre del mensajero (de tu nodo) que hace el retiro"),
+      },
+    }, async (args) => run(() => api("POST", "/colecta/asignar-por-nombre", args)));
+
+    tool("colecta_desasignar", {
+      title: "Desasignar una colecta",
+      description: "Quita la asignación de una colecta (los envíos vuelven a 'sin colecta'). El colectaId lo devuelve «colecta_pendientes». No mueve dinero.",
+      inputSchema: { colectaId: z.number().int().positive() },
+    }, async ({ colectaId }) => run(() => api("POST", "/colecta/desasignar", { colectaId })));
+
+    tool("procesar_zona", {
+      title: "Aceptar envíos ruteados por zona",
+      description: "ACEPTA (recibe en tu nodo) los envíos que otros nodos te rutearon por zona — los ids salen de «envios_por_zona». Opcional: mensajeroId para asignarlos a un mensajero puntual de esa zona. No mueve dinero (el clearing es config).",
+      inputSchema: { envioIds: z.array(z.number().int().positive()).min(1), mensajeroId: z.number().int().positive().optional() },
+    }, async (args) => run(() => api("POST", "/colecta/procesar-zona", args)));
+
+    tool("rechazar_zona", {
+      title: "Rechazar envíos ruteados por zona",
+      description: "RECHAZA (declina) envíos que te rutearon por zona: dejan de aparecerte y quedan para el nodo de origen u otros nodos de la zona. No cambia el estado del envío. Los ids salen de «envios_por_zona».",
+      inputSchema: { envioIds: z.array(z.number().int().positive()).min(1), motivo: z.string().optional() },
+    }, async (args) => run(() => api("POST", "/colecta/rechazar-zona", args)));
+
+    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)));
+}
+
+// Ayuda integrada — se registra al final para que el índice conozca TODOS los tools
+// que este usuario tiene según su rol/permisos. Solo lectura de documentación.
+tool("ayuda", {
+  title: "Ayuda / documentación de las herramientas",
+  description: "Documentación de las herramientas del MCP: sin argumentos = índice de lo que podés usar; `tool` = ficha de una herramienta (qué hace, cómo usarla, ejemplo, qué NO hace); `tema` = tópico transversal (facturacion_marketplace, dinero, aislamiento). Consultalo antes de asumir cómo funciona algo.",
+  inputSchema: { tool: z.string().optional().describe("Nombre de una herramienta, ej. ruta_adjudicar"), tema: z.string().optional().describe("facturacion_marketplace | dinero | aislamiento") },
+}, async ({ tool: t, tema }) =>
+  ({ content: [{ type: "text", text: renderAyuda(t || tema, { version: MCP_VERSION, disponibles: registrados }) }] }));
+
+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"}.`);