nexusflex-mcp 3.1.0 → 3.6.0

package/docs.mjs

@@ -0,0 +1,322 @@
+// ============================================================================
+//  Documentación integrada del MCP de Nexus Flex — fuente de verdad de la ayuda
+//  por herramienta (tool `ayuda`). Cada tool trae: qué hace, cómo usarlo (params),
+//  un ejemplo resuelto y qué NO hace (para no inferir comportamiento inexistente).
+//
+//  ⚠️ ESPEJO: este archivo está DUPLICADO en `backend/src/services/mcp-docs.ts`
+//  (el conector remoto se deploya sin la carpeta mcp/). Si editás uno, editá el
+//  otro — igual que MCP_VERSION/NOVEDADES. Mantené el contenido idéntico.
+// ============================================================================
+
+// Tópicos transversales (no son tools) — se consultan con `ayuda tema:<clave>`.
+export const TOPICS = {
+  facturacion_marketplace: [
+    "FACTURACIÓN DEL MARKETPLACE DE RUTAS PÚBLICAS",
+    "",
+    "Adjudicar una ruta (ruta_adjudicar) es OPERATIVO: cierra la subasta, marca el",
+    "nodo ganador (nodoToma) y deja registrada la OBLIGACIÓN al precio de la oferta",
+    "(precioAcordado). NO crea ningún asiento automático de facturación semanal, ni",
+    "en rendiciones, ni en comisiones de afiliado, ni en el clearing entre nodos.",
+    "El marketplace NO mueve dinero.",
+    "",
+    "Es decir: adjudicar ≠ colecta. Una colecta entre nodos sí genera un ítem de",
+    "clearing; una ruta adjudicada, NO. El pago entre el nodo que publica y el que",
+    "toma se acuerda y se salda MANUALMENTE (efectivo con el cadete, o descontándolo",
+    "de lo que un nodo ya le debe al otro por otros conceptos).",
+    "",
+    "Cómo verificarlo desde el MCP:",
+    "  • mis_rutas → estado 'adjudicada', nodoToma y precioAcordado de cada ruta tuya.",
+    "  • rendiciones / comisiones_afiliado_ver → NO listarán la ruta adjudicada.",
+    "",
+    "Qué falta (roadmap, todavía NO implementado): un settlement automático que,",
+    "al adjudicar, cargue el precioAcordado en la cuenta corriente entre los dos",
+    "nodos. Mientras no exista, tratá el pago como manual y avisáselo al usuario.",
+  ].join("\n"),
+
+  dinero: [
+    "DINERO — QUÉ NO HACE NUNCA EL MCP",
+    "",
+    "El MCP nunca mueve plata: no registra pagos de vendedores, no factura, no",
+    "concilia caja, no imputa cobros/haberes en cuentas corrientes. Hay una denylist",
+    "de dinero (mcpMoneyGuard) heredada del backend. Las únicas escrituras 'con",
+    "olor a plata' son configuraciones de TARIFA (colecta_configurar, precio_",
+    "actualizar, afiliacion_crear) o el REGISTRO de una obligación (comision_liquidar",
+    "marca comisiones ya devengadas como pagadas; ruta_adjudicar deja el precio",
+    "acordado). Ver tema facturacion_marketplace.",
+  ].join("\n"),
+
+  aislamiento: [
+    "AISLAMIENTO ENTRE NODOS",
+    "",
+    "Cada token de MCP pertenece a un usuario. Todos los tools llaman a la API REST",
+    "del backend con ese token, así que heredan el MISMO gateo que la web:",
+    "requireAuth + requirePermiso + scope por nodo/idCliente. Un vendedor solo ve",
+    "SUS envíos/stock; un operador solo su nodo; el admin global ve la red. Ningún",
+    "tool puede leer ni escribir datos de otro nodo (salvo lo que es público por",
+    "diseño, como el marketplace de rutas abiertas). Si un tool devuelve 403 es el",
+    "aislamiento del backend, no un bug.",
+  ].join("\n"),
+};
+
+// Guías de arranque por rol (onboarding). Se muestran al conectar (server
+// `instructions`) y con el tool `guia`. Metodología para empezar a usar el sistema
+// rápido y bien, con las herramientas concretas de cada paso.
+export const GUIAS = {
+  mensajero: [
+    "GUÍA DEL MENSAJERO — registrar lo que colectás, en el momento",
+    "",
+    "La idea: cuando pasás a colectar a un cliente, en vez de anotar a mano, me",
+    "mandás las FOTOS y yo cargo los envíos por vos. Paso a paso:",
+    "",
+    "1) Sacá una FOTO de cada paquete que agarrás: la etiqueta (Flex/Mercado Libre",
+    "   o la que sea) y, si tiene QR, que se vea. Si el paquete NO tiene etiqueta,",
+    "   sacá foto igual (datos del paquete: a quién va, dirección, teléfono).",
+    "2) Mandámelas todas juntas (un grupo de fotos). Yo leo cada una y registro el",
+    "   envío del cliente que estás colectando:",
+    "   • Con etiqueta ML / QR  → lo registro con `envio_desde_etiqueta_ml`",
+    "     (guardo el QR real, la etiqueta queda reimprimible).",
+    "   • Sin etiqueta, con datos → lo registro con `envio_cargar` como pedido",
+    "     manual y se le puede generar una etiqueta NUEVA para pegar.",
+    "3) IMPORTANTE (aislamiento): SOLO podés registrar envíos de clientes de TU",
+    "   nodo, o de un cliente que tengas COLECTADO (incluye colectas tomadas del",
+    "   marketplace de colectas). De otros clientes, no.",
+    "4) Cada envío queda 'A retirar', atribuido a vos, con un LINK de etiqueta",
+    "   imprimible. El vendedor lo ve al toque en su cuenta.",
+    "5) Al llegar al nodo, el centro procesa los envíos; a los que cargaste sin",
+    "   etiqueta se les pega una y salen normal. Después se escanean, aparecen en",
+    "   el mapa y se te suma la tarifa como cualquier reparto.",
+    "",
+    "Tips: si una etiqueta se rompió o no se lee, cargá el envío con `envio_cargar`",
+    "y generás una nueva. Consultá el estado de un envío con `envio_consultar`, tu",
+    "ruta con `mi_ruta` y tus colectas con `mis_colectas`.",
+    "(Próximamente: aviso en la app para imprimir de una todas las etiquetas que",
+    "cargaste por acá.)",
+  ].join("\n"),
+
+  cliente: [
+    "GUÍA DEL VENDEDOR — cargá tus ventas y seguí tu operación desde acá",
+    "",
+    "1) Cargar una venta/envío: `envio_cargar` con destinatario, teléfono,",
+    "   dirección y localidad (montoCobro si cobrás contra entrega). Te devuelvo",
+    "   el tracking + un link de etiqueta para imprimir + un link para subir una",
+    "   foto del paquete.",
+    "2) ¿Vendés por Mercado Libre? Mandame la foto de la etiqueta y la registro",
+    "   con `envio_desde_etiqueta_ml` (queda con el QR real).",
+    "3) Colecta (que te retiren): `mi_colecta` para ver cómo estás, `colecta_auto`",
+    "   para prender/apagar la automática, `colecta_solicitar` para una por única vez.",
+    "4) Tu negocio: `mi_stock` / `mi_disponible` (para no sobrevender), ",
+    "   `mi_rentabilidad`, `mis_top_productos`, `mis_kpis`. Sucursales de retiro con",
+    "   `mis_sucursales` / `sucursal_guardar`.",
+    "",
+    "Todo lo tuyo es solo tuyo (aislamiento). Nunca toco dinero por acá.",
+  ].join("\n"),
+
+  nodo: [
+    "GUÍA DEL NODO (operador/admin) — implementar y operar Nexus Flex rápido",
+    "",
+    "Puesta a punto:",
+    "  • Vendedores: `cliente_crear` / `cliente_editar` (asigná su lista de precio).",
+    "  • Choferes: `chofer_crear` (te devuelvo una clave temporal para pasarle).",
+    "  • Colecta: `colecta_configurar` (pago del nodo/mensajero, cobro por vendedor).",
+    "  • Zonas: `asignar_mensajero_zona` (mensajero↔metazona), `asignar_nodo_zona`",
+    "    (un nodo de tu grupo cubre una localidad).",
+    "",
+    "El día a día:",
+    "  • `colecta_pendientes` (hoy + mañana) y `colecta_asignar` (que Fulano levante",
+    "    a tal cliente).",
+    "  • Envíos: los cadetes pueden cargar lo que colectan por MCP (foto→envío); vos",
+    "    los ves 'A retirar'. Consultá con `envio_consultar`, corregí con",
+    "    `cobro_corregir` / `envio_reasignar_cliente`.",
+    "  • Rendiciones: `rendiciones` (qué falta recuperar/rendir).",
+    "",
+    "Clearing entre nodos (eficiente):",
+    "  • Metazonas + grupos logísticos rutean los envíos al nodo que cubre la zona.",
+    "    Recibís lo que te rutean con `envios_por_zona` → `procesar_zona` (aceptar) o",
+    "    `rechazar_zona`. El clearing sale de la config de tarifas por grupo.",
+    "  • Marketplace de rutas (`rutas_publicas`, `ruta_publicar`/`ofertar`/`adjudicar`):",
+    "    subasta abierta entre nodos. OJO: adjudicar NO factura automático — el pago",
+    "    entre nodos se salda a mano (ver `ayuda tema:facturacion_marketplace`).",
+    "  • Números: `kpi_nodo` (P&L, top clientes), `metricas_por_tipo`.",
+    "",
+    "Aislamiento: todo lo que ves/hacés es de TU nodo (o tu grupo cuando corresponde).",
+  ].join("\n"),
+};
+
+// Devuelve la guía de arranque para un rol (mensajero/cliente/operador/admin).
+export function guiaOnboarding(rol) {
+  if (rol === "mensajero") return GUIAS.mensajero;
+  if (rol === "cliente") return GUIAS.cliente;
+  if (rol === "operador" || rol === "admin") return GUIAS.nodo;
+  return [GUIAS.cliente, "", "— — —", "", GUIAS.nodo].join("\n");
+}
+
+// Orden y agrupación para el índice (solo se muestran los que el usuario tiene).
+export const GROUPS = [
+  { titulo: "General", tools: ["mis_datos", "guia", "ayuda", "mcp_version", "sugerencia_crear"] },
+  { titulo: "Vendedor — mi operación", tools: ["mis_envios", "envio_consultar", "mis_sucursales", "sucursal_guardar", "mi_colecta", "colecta_solicitar", "colecta_auto"] },
+  { titulo: "Vendedor — mi stock y números", tools: ["mi_stock", "mi_disponible", "mi_rentabilidad", "mis_productos", "mis_top_productos", "mis_kpis"] },
+  { titulo: "Mensajero", tools: ["mi_ruta", "mis_colectas"] },
+  { titulo: "Envíos (staff)", tools: ["envio_cargar", "envio_desde_etiqueta_ml", "envio_reasignar_cliente", "cobro_corregir"] },
+  { titulo: "Colecta y zonas (staff)", tools: ["colecta_ver", "colecta_pendientes", "colecta_configurar", "colecta_asignar", "colecta_desasignar", "zonas_reparto", "asignar_mensajero_zona", "asignar_nodo_zona", "envios_por_zona", "procesar_zona", "rechazar_zona"] },
+  { titulo: "Rendiciones y reclamos", tools: ["rendiciones", "rendicion_revertir", "reclamos_listar"] },
+  { titulo: "Marketplace de rutas", tools: ["rutas_publicas", "mis_rutas", "ruta_ofertas", "ruta_publicar", "ruta_ofertar", "ruta_adjudicar"] },
+  { titulo: "Afiliados", tools: ["afiliacion_listar", "comisiones_afiliado_ver", "afiliado_crear", "afiliacion_crear", "afiliacion_editar", "comision_liquidar"] },
+  { titulo: "Métricas / KPIs", tools: ["kpi_nodo", "kpi_red", "metricas_por_tipo", "top_productos"] },
+  { titulo: "WMS del nodo", tools: ["stock_nodo", "productos_nodo", "producto_crear"] },
+  { titulo: "Gestión del nodo", tools: ["clientes_del_nodo", "cliente_crear", "cliente_editar", "precios_ver", "precio_actualizar", "cuentas_vinculadas", "generar_enlace_vinculacion"] },
+  { titulo: "Usuarios / choferes", tools: ["chofer_listar", "chofer_crear", "chofer_editar", "usuario_habilitar_reparto"] },
+  { titulo: "Administración (red)", tools: ["nodos_listar", "nodo_crear", "sugerencias_listar"] },
+];
+
+// Doc por herramienta: que=qué hace, uso=cómo/params, ej=ejemplo resuelto, no=qué NO hace.
+export const TOOL_DOCS = {
+  ayuda: { que: "Devuelve esta documentación: índice de herramientas o la ficha completa de una (qué hace, params, ejemplo, qué NO hace) y tópicos transversales.", uso: "Sin argumentos = índice. `tool:<nombre>` = ficha de esa herramienta. `tema:<clave>` = tópico (facturacion_marketplace, dinero, aislamiento).", ej: "ayuda tool:ruta_adjudicar → te explica cómo adjudicar y aclara que no mueve dinero.", no: "No ejecuta nada ni consulta datos; es solo lectura de documentación estática." },
+  guia: { que: "Guía de ARRANQUE para tu rol: la metodología para empezar a usar Nexus Flex rápido, con las herramientas de cada paso (mensajero: foto→envío al colectar; vendedor: cargar ventas; nodo: implementar + operar + clearing).", uso: "Sin argumentos = tu guía según tu rol. `rol:<mensajero|cliente|nodo>` para ver otra.", ej: "Recién conectás como mensajero → guia → te explico cómo registrar lo que colectás sacando fotos.", no: "No ejecuta acciones; es la metodología. Para el detalle de una herramienta usá `ayuda tool:<x>`." },
+  mis_datos: { que: "Tu usuario, rol y nodo/cliente: define tu ALCANCE (qué podés ver/hacer).", uso: "Sin parámetros.", ej: "Antes de operar, mis_datos → confirmás que sos operador del nodo 6 y qué permisos tenés.", no: "No lista otros usuarios ni cambia nada." },
+  mcp_version: { que: "Versión del MCP corriendo, por qué vía (remoto/npx) y las novedades recientes.", uso: "Sin parámetros.", ej: "El usuario pregunta 'tengo lo último' → mcp_version.", no: "No actualiza el MCP." },
+  sugerencia_crear: { que: "Registra una sugerencia/mejora/bug del usuario (queda para el equipo).", uso: "mensaje (obligatorio); categoria opcional (funcionalidad|mejora|bug|otro). Se adjunta tu usuario/rol/nodo solo.", ej: "sugerencia_crear mensaje:'Sumar recordatorio de colecta' categoria:mejora.", no: "No abre tickets externos ni notifica por mail." },
+
+  mis_envios: { que: "Tus envíos/paquetes (solo los tuyos).", uso: "estado opcional (filtra por estado).", ej: "mis_envios estado:'En camino' → los que están en reparto.", no: "No muestra envíos de otros vendedores; no los edita." },
+  envio_consultar: { que: "Busca UN envío por tracking/código y devuelve estado, historial, destino y datos de cobro/cambio.", uso: "codigo (tracking o código). Vendedor: entre SUS envíos; staff: dentro de su nodo. Si hay varios matches, pasá el tracking completo.", ej: "El vendedor pregunta '¿dónde está 44000...?' → envio_consultar codigo:'44000123'.", no: "No cambia el estado del envío; no busca fuera de tu alcance." },
+  mis_sucursales: { que: "Tus sucursales / puntos de retiro (la principal = tu dirección de retiro), con horario de corte y ventanas.", uso: "Sin parámetros.", ej: "mis_sucursales → confirmás desde dónde te colectan.", no: "No las edita (para eso, sucursal_guardar)." },
+  sucursal_guardar: { que: "Crea o edita una sucursal tuya (punto de retiro). Geocodifica la dirección sola.", uso: "id vacío = nueva; nombre obligatorio; principal:true la vuelve tu dirección de retiro; horarioCorte HH:MM y ventanas opcionales.", ej: "Cambiar tu retiro: sucursal_guardar id:<principal> direccion:'Av. Rivadavia 5000, CABA' principal:true.", no: "No mueve dinero; el detalle de piso/depto/timbre va aparte, no al geocoder." },
+  mi_colecta: { que: "Estado de tu colecta (retiro): si la automática está prendida, si pediste una por única vez y el aviso de costo.", uso: "Sin parámetros.", ej: "mi_colecta → ver si mañana te pasan a buscar.", no: "No la prende/apaga (colecta_auto) ni la solicita (colecta_solicitar)." },
+  colecta_solicitar: { que: "Pedís que te retiren los envíos POR ÚNICA VEZ, aunque tengas la automática apagada.", uso: "Sin parámetros. Devuelve el aviso de costo si aplica.", ej: "colecta_solicitar → aparecés en el panel de colecta del nodo.", no: "No prende la colecta automática permanente; no mueve dinero." },
+  colecta_auto: { que: "Prende (true) o apaga (false) tu colecta AUTOMÁTICA.", uso: "activa (bool).", ej: "colecta_auto activa:false → dejás de que te retiren; llevás vos al depósito.", no: "No agenda una colecta puntual (para eso colecta_solicitar)." },
+
+  mi_stock: { que: "Tu stock físico (solo tus productos).", uso: "Sin parámetros.", ej: "mi_stock → ver unidades por SKU.", no: "No muestra disponible-para-vender (usá mi_disponible)." },
+  mi_disponible: { que: "Disponible por SKU = físico − comprometido; marca ⚠️ si está bajo el mínimo.", uso: "Sin parámetros.", ej: "mi_disponible → cuántas unidades podés seguir vendiendo sin sobrevender.", no: "No repone stock." },
+  mi_rentabilidad: { que: "Margen por SKU (precio − flete real − COGS).", uso: "desde/hasta YYYY-MM-DD (default: mes en curso).", ej: "mi_rentabilidad desde:2026-08-01 → margen del mes.", no: "No incluye gastos fijos del negocio; es por SKU." },
+  mis_productos: { que: "Tu catálogo de productos.", uso: "Sin parámetros.", ej: "mis_productos → ver SKUs cargados.", no: "No da de alta (producto_crear, si el nodo tiene WMS)." },
+  mis_top_productos: { que: "Ranking de tus productos más despachados.", uso: "desde/hasta YYYY-MM-DD (default: mes).", ej: "mis_top_productos → qué se vende más.", no: "No muestra rentabilidad (usá mi_rentabilidad)." },
+  mis_kpis: { que: "Tus métricas + benchmark anónimo de tu nodo.", uso: "desde/hasta opcionales.", ej: "mis_kpis → tu tasa de entrega vs. el promedio del nodo.", no: "No revela datos de otros vendedores (el benchmark es anónimo)." },
+
+  mi_ruta: { que: "Tus entregas asignadas: las paradas de tu ruta del día.", uso: "Sin parámetros.", ej: "mi_ruta → orden de reparto de hoy.", no: "No marca entregas (eso se hace escaneando en la app)." },
+  mis_colectas: { que: "Las colectas/retiros que tenés asignados.", uso: "Sin parámetros.", ej: "mis_colectas → a qué vendedores tenés que ir a buscar.", no: "No las completa/confirma desde acá." },
+
+  envio_cargar: { que: "Registra un envío nuevo (queda 'A retirar') y devuelve tracking + link de etiqueta + link para subir foto.", uso: "Obligatorios: destinatario, telefono, direccion, localidad. Staff pasa `cliente` (nombre del vendedor de su nodo); el vendedor no. montoCobro = cobro contra entrega (opcional).", ej: "Staff: envio_cargar cliente:'Distri Sur' destinatario:'Ana' telefono:'11...' direccion:'Belgrano 100' localidad:'Lanús' montoCobro:15000.", no: "No mueve dinero (montoCobro es el cobro a destino, no un asiento); no imprime, devuelve el link." },
+  envio_desde_etiqueta_ml: { que: "Registra un envío a partir de lo que VOS (Claude) leíste de la foto de una etiqueta de Mercado Libre.", uso: "Leé la etiqueta: mlShipmentId + (si podés) mlQr crudo, mlSenderId del vendedor y el destino. El vendedor se mapea por mlSenderId (cuenta vinculada) o `cliente` por nombre. Una llamada por etiqueta.", ej: "envio_desde_etiqueta_ml mlSenderId:'123456' mlShipmentId:'44000...' destinatario:'Juan' direccion:'...' localidad:'Avellaneda'.", no: "No mueve dinero; si no reconoce el vendedor por mlSenderId tenés que pasar `cliente`." },
+  envio_reasignar_cliente: { que: "Mueve UN envío (por tracking) a otro cliente/vendedor de tu nodo cuando se cargó mal.", uso: "tracking + cliente (nombre o id destino, de tu nodo). Queda en el historial.", ej: "envio_reasignar_cliente tracking:'44000...' cliente:'Comercial Norte'.", no: "No cruza nodos; no cambia el estado del envío." },
+  cobro_corregir: { que: "Ajusta el monto a cobrar contra entrega de un envío (se cobró de más/de menos), guardando el original en el historial.", uso: "envioId + monto nuevo; motivo opcional.", ej: "cobro_corregir envioId:987 monto:12000 motivo:'lista vieja'.", no: "No mueve dinero en cuentas: corrige el DATO del envío." },
+
+  colecta_ver: { que: "Resumen de valores de colecta del nodo: pago default, cobros por cliente y pagos pactados por cliente+mensajero.", uso: "Sin parámetros.", ej: "colecta_ver → cuánto se paga/cobra por colecta.", no: "No cambia tarifas (colecta_configurar)." },
+  colecta_pendientes: { que: "Panel de colectas del nodo: `items` = a retirar HOY (por cliente, con corte y mensajero asignado); `itemsManana` = clientes cuyos envíos entraron después del corte → van a mañana.", uso: "Sin parámetros. Trae el colectaId para desasignar.", ej: "'¿Quién levanta a Distri Sur?' → colecta_pendientes y mirás items.", no: "No asigna (colecta_asignar) ni configura tarifas." },
+  colecta_configurar: { que: "Setea un valor de colecta según alcance.", uso: "alcance: 'nodo' (pago default por colecta), 'mensajero' (default de ese cadete), 'cliente' (cuánto se le COBRA a ese vendedor; idCliente + valor, minEnvios opcional), 'par' (pago pactado a un mensajero por un cliente puntual; idCliente + mensajero + valor). Scopeado a tu nodo.", ej: "colecta_configurar alcance:cliente idCliente:'130' valor:2500 minEnvios:5 → gratis desde 5 envíos, sino $2500.", no: "No mueve dinero: es config de tarifa (el cobro se aplica al liquidar)." },
+  colecta_asignar: { que: "Asigna la colecta de un cliente a un mensajero (ambos por nombre de tu nodo) y avisa al cadete.", uso: "cliente + mensajero (nombres). Si el corte venció, la programa para el próximo día hábil.", ej: "colecta_asignar cliente:'Distri Sur' mensajero:'Maxi'.", no: "No mueve dinero; no cruza nodos." },
+  colecta_desasignar: { que: "Quita la asignación de una colecta (los envíos vuelven a 'sin colecta').", uso: "colectaId (lo devuelve colecta_pendientes).", ej: "colecta_desasignar colectaId:44.", no: "No borra los envíos; no mueve dinero." },
+  zonas_reparto: { que: "Zonas de reparto del nodo con sus metazonas y qué mensajeros tiene cada una.", uso: "Sin parámetros.", ej: "zonas_reparto → ver quién cubre Palermo.", no: "No asigna (asignar_mensajero_zona / asignar_nodo_zona)." },
+  asignar_mensajero_zona: { que: "Asigna un mensajero de tu nodo a una metazona; si la zona existe le suma el cadete, si no la crea.", uso: "mensajero + metazona; nombre opcional.", ej: "asignar_mensajero_zona mensajero:'Maxi' metazona:'Palermo'.", no: "No cruza nodos." },
+  asignar_nodo_zona: { que: "Asigna un NODO COMPLETO (de tu grupo logístico) a una metazona, cuando ese nodo cubre toda la localidad.", uso: "nodo (nombre, debe compartir grupo logístico) + metazona; nombre opcional.", ej: "asignar_nodo_zona nodo:'RL' metazona:'Portela'.", no: "No suma nodos fuera de tu grupo logístico." },
+  envios_por_zona: { que: "Envíos que OTROS nodos te rutearon por zona de reparto, agrupados por zona (para aceptar/rechazar).", uso: "Sin parámetros. Cada envío trae su id (para procesar_zona/rechazar_zona).", ej: "envios_por_zona → ver qué te mandaron por la zona Sur.", no: "No los acepta solo: usá procesar_zona o rechazar_zona." },
+  procesar_zona: { que: "ACEPTA (recibe en tu nodo) envíos ruteados por zona.", uso: "envioIds (de envios_por_zona); mensajeroId opcional para asignarlos.", ej: "procesar_zona envioIds:[101,102] mensajeroId:7.", no: "No mueve dinero (el clearing es config)." },
+  rechazar_zona: { que: "RECHAZA envíos ruteados por zona: dejan de aparecerte y quedan para origen u otros nodos de la zona.", uso: "envioIds (de envios_por_zona); motivo opcional.", ej: "rechazar_zona envioIds:[103] motivo:'fuera de mi cobertura'.", no: "No cambia el estado del envío." },
+
+  rendiciones: { que: "Estado de rendiciones: cobros/cambios/devoluciones a recuperar o rendir, con totales y quién tiene cada uno.", uso: "Sin parámetros. Scopeado a tu alcance (vendedor: lo tuyo; nodo: tu nodo; mensajero: lo suyo).", ej: "rendiciones → cuánto falta que rinda cada cadete.", no: "No confirma ni revierte (rendicion_revertir); NO incluye rutas de marketplace adjudicadas (ver ayuda tema:facturacion_marketplace)." },
+  rendicion_revertir: { que: "Revierte un cobro/cambio marcado como 'rendido' por error → vuelve a 'a rendir'.", uso: "envioId + tipo (cobro|cambio); motivo opcional. Deja registro.", ej: "rendicion_revertir envioId:987 tipo:cobro motivo:'se marcó sin recibir'.", no: "No mueve dinero en cuentas; corrige el estado de la rendición." },
+  reclamos_listar: { que: "Reclamos abiertos de clientes ligados a liquidaciones/rendiciones (tipo, estado, trackings en disputa).", uso: "estado opcional (abierto|resuelto). Vendedor: lo suyo; operador: su nodo.", ej: "reclamos_listar estado:abierto → qué cobros están en disputa.", no: "No resuelve reclamos desde acá." },
+
+  rutas_publicas: { que: "Publicaciones ABIERTAS de toda la red que tu nodo puede tomar (con cuántas ofertas tiene cada una). Marca las tuyas con esMia.", uso: "Sin parámetros.", ej: "rutas_publicas → ver qué rutas hay para ofertar.", no: "No oferta (ruta_ofertar)." },
+  mis_rutas: { que: "Tus publicaciones (con estado/adjudicación: nodoToma y precioAcordado) y las ofertas que hiciste a otros.", uso: "Sin parámetros.", ej: "mis_rutas → ver si tu ruta se adjudicó y a quién.", no: "El precioAcordado es la obligación registrada, NO un asiento de facturación (ver ayuda tema:facturacion_marketplace)." },
+  ruta_ofertas: { que: "Ofertas recibidas en una publicación TUYA, de la más barata a la más cara. Solo el que publicó.", uso: "publicacionId. Los ids de oferta sirven para adjudicar.", ej: "ruta_ofertas publicacionId:12 → elegís la mejor y su ofertaId.", no: "No adjudica (ruta_adjudicar)." },
+  ruta_publicar: { que: "Publicás una ruta/colecta/viaje para que cualquier nodo la tome (subasta abierta). VOS le pagás al que la toma.", uso: "titulo (obligatorio); tipo (ruta|colecta|viaje), descripcion, zona, precioMax (tope que ofrecés pagar) opcionales.", ej: "ruta_publicar titulo:'Reparto zona Oeste 40 paquetes' tipo:ruta precioMax:20000.", no: "No mueve dinero: la obligación recién se registra al adjudicar; el pago es manual." },
+  ruta_ofertar: { que: "Ofertás por una publicación de OTRO nodo. precio = lo que cobrás por hacerla (más barato = mejor para el que publica).", uso: "publicacionId + precio; nota opcional. Si ya ofertaste, la actualiza.", ej: "ruta_ofertar publicacionId:12 precio:18000 nota:'salgo 8am'.", no: "No podés ofertar en tu propia publicación." },
+  ruta_adjudicar: { que: "Elegís la oferta ganadora de una publicación TUYA y cerrás la subasta: el nodo ganador la toma a su precio y queda registrada la obligación.", uso: "publicacionId + ofertaId (de ruta_ofertas).", ej: "ruta_adjudicar publicacionId:12 ofertaId:34 → gana el nodo de esa oferta a $18000.", no: "NO crea asiento de facturación/rendición/comisión ni clearing automático: el pago entre nodos se salda MANUALMENTE (ver ayuda tema:facturacion_marketplace)." },
+
+  afiliacion_listar: { que: "Afiliaciones (afiliado↔entidad referida) con su comisión por envío, vigencia y estado.", uso: "afiliado y/o entidad opcionales para filtrar. Scopeado a tu nodo.", ej: "afiliacion_listar afiliado:'Nodo RL'.", no: "No muestra comisiones devengadas (comisiones_afiliado_ver)." },
+  comisiones_afiliado_ver: { que: "Comisiones devengadas por envío (pendiente/liquidada) con totales.", uso: "afiliado, desde, hasta (YYYY-MM-DD) opcionales. Scopeado a tu nodo.", ej: "comisiones_afiliado_ver afiliado:'Nodo RL' desde:2026-08-01.", no: "No las paga (comision_liquidar); NO incluye rutas de marketplace." },
+  afiliado_crear: { que: "Alta de un afiliado (quien trae volumen nuevo a la red).", uso: "nombre + tipo (nodo|mensajero|externo); refId = id del nodo/mensajero (null si externo).", ej: "afiliado_crear nombre:'Juan Ref' tipo:externo.", no: "No crea la afiliación/comisión (afiliacion_crear); no toca dinero." },
+  afiliacion_crear: { que: "Vincula un afiliado con una entidad referida (nodo o cliente) y su comisión RECURRENTE por envío.", uso: "afiliado + entidadTipo (nodo|cliente) + entidad + tipoComision (porcentaje|montoFijo) + valorComision; fechaExpiracion opcional. Una entidad = un afiliado activo.", ej: "afiliacion_crear afiliado:'Juan Ref' entidadTipo:cliente entidad:'Distri Sur' tipoComision:montoFijo valorComision:50.", no: "No paga (comision_liquidar); es config, no mueve dinero." },
+  afiliacion_editar: { que: "Edita una afiliación: valorComision, fechaExpiracion (renovar/extender) y/o activa.", uso: "id + los campos a cambiar.", ej: "afiliacion_editar id:5 activa:false → la das de baja.", no: "No toca dinero." },
+  comision_liquidar: { que: "Marca comisiones devengadas como LIQUIDADAS (registra el pago al afiliado).", uso: "ids = lista de comisiones (de comisiones_afiliado_ver). Requiere permiso de finanzas. Scopeado a tu nodo.", ej: "comision_liquidar ids:[10,11,12].", no: "No calcula comisiones (se devengan solas por envío); no factura." },
+
+  kpi_nodo: { que: "Tablero del nodo: P&L, top clientes, caídas.", uso: "desde/hasta opcionales; nodo solo para admin.", ej: "kpi_nodo desde:2026-08-01 → resultado del mes.", no: "No baja a un vendedor puntual; solo tu nodo (salvo admin)." },
+  kpi_red: { que: "KPIs globales de la red.", uso: "Sin parámetros. Solo admin global.", ej: "kpi_red → panorama SaaS de toda la red.", no: "No desglosa por nodo (usá kpi_nodo con nodo)." },
+  metricas_por_tipo: { que: "Métricas por TIPO de envío (flex/tienda/manual): total, entregados, tasa y % entregado antes de las 21hs. Para admin desglosa por logística.", uso: "desde/hasta YYYY-MM-DD (default 30 días); nodo solo admin.", ej: "metricas_por_tipo → ver si los Flex se entregan a tiempo.", no: "No es por cliente." },
+  top_productos: { que: "Ranking de productos más despachados del nodo (WMS).", uso: "desde/hasta y cliente opcionales.", ej: "top_productos cliente:'Distri Sur'.", no: "Requiere WMS activo en el nodo." },
+
+  stock_nodo: { que: "Stock del depósito del nodo (WMS).", uso: "cliente opcional para filtrar.", ej: "stock_nodo cliente:'Distri Sur'.", no: "Requiere WMS activo; no repone." },
+  productos_nodo: { que: "Catálogo del depósito del nodo (WMS).", uso: "cliente opcional.", ej: "productos_nodo.", no: "Requiere WMS activo." },
+  producto_crear: { que: "Alta de producto en el depósito (WMS).", uso: "nombre + sku/codigoBarra/peso/volumen opcionales; staff pasa idCliente dueño.", ej: "producto_crear nombre:'Remera M' sku:'REM-M' idCliente:'130'.", no: "No mueve dinero; requiere WMS activo." },
+
+  clientes_del_nodo: { que: "Clientes/vendedores del nodo con su lista de precio.", uso: "Sin parámetros. Scopeado a tu nodo.", ej: "clientes_del_nodo → ver a quién facturás y con qué lista.", no: "No los crea/edita (cliente_crear/editar)." },
+  cliente_crear: { que: "Alta de cliente/vendedor en tu nodo.", uso: "nombre obligatorio; telefono/dni/direccion/idLista opcionales.", ej: "cliente_crear nombre:'Nueva Distri' idLista:'ID12'.", no: "No toca dinero; no cruza nodos." },
+  cliente_editar: { que: "Edita un cliente de tu nodo (p. ej. cambiar su lista de precio).", uso: "id + nombre (obligatorio) + los campos a cambiar (idLista, etc.).", ej: "cliente_editar id:130 nombre:'Distri Sur' idLista:'ID12'.", no: "No toca dinero." },
+  precios_ver: { que: "Listas de precios por zona de tu nodo.", uso: "Sin parámetros. Requiere permiso 'precios'.", ej: "precios_ver → ver tarifas por zona.", no: "No las edita (precio_actualizar)." },
+  precio_actualizar: { que: "Cambia precios de una lista creando una VERSIÓN nueva (histórico intacto).", uso: "idLista + los tramos (cercana/media/lejana/muyLejana); referencia/vigenciaDesde opcionales. Requiere permiso 'precios' (y que el conector lo permita).", ej: "precio_actualizar idLista:'ID12' cercana:1500 media:2000 lejana:2800.", no: "No mueve dinero; puede estar deshabilitado por el conector (ALLOW_PRECIOS)." },
+  cuentas_vinculadas: { que: "Cuántas cuentas de tienda hay vinculadas, por proveedor (ML / TiendaNube / TiendaNegocio).", uso: "nodo opcional (solo admin, baja al desglose por cliente).", ej: "cuentas_vinculadas → cuántos vendedores tienen ML conectado.", no: "No vincula (generar_enlace_vinculacion)." },
+  generar_enlace_vinculacion: { que: "Genera el enlace para vincular una tienda; se lo mandás al cliente para que autorice.", uso: "proveedor (ml|tiendanube|tiendanegocio); staff pasa `cliente` (de su nodo).", ej: "generar_enlace_vinculacion proveedor:ml cliente:'Distri Sur'.", no: "No completa la vinculación (la autoriza el dueño de la tienda); no toca dinero." },
+
+  chofer_listar: { que: "Usuarios de tu nodo, incluidos los choferes (rol mensajero): id, nombre, teléfono, activo.", uso: "Sin parámetros. Requiere permiso 'usuarios'.", ej: "chofer_listar → ver tus cadetes.", no: "No crea/edita (chofer_crear/editar)." },
+  chofer_crear: { que: "Da de alta un chofer (mensajero) en tu nodo con una CLAVE TEMPORAL que devuelve el server.", uso: "nombre + telefono + email; mensajeroNombre opcional (macheo con su cta cte). Pasale la clave; la cambia al primer ingreso.", ej: "chofer_crear nombre:'Maxi' telefono:'11...' email:'maxi@...'.", no: "Claude nunca inventa la clave; el server la genera." },
+  chofer_editar: { que: "Edita un chofer de tu nodo: nombre, teléfono, mensajeroNombre y/o activo.", uso: "id + los campos a cambiar.", ej: "chofer_editar id:7 activo:false → lo desactivás.", no: "No toca credenciales/clave." },
+  usuario_habilitar_reparto: { que: "Marca a un operador/admin de tu nodo como TAMBIÉN mensajero (puede escanear, autoasignarse y entregar).", uso: "id + activo (default true).", ej: "usuario_habilitar_reparto id:4 → ese comisionista ya puede repartir.", no: "No toca credenciales." },
+
+  nodos_listar: { que: "Todas las logísticas (nodos) de la red.", uso: "Sin parámetros. Solo admin global.", ej: "nodos_listar → id/nombre de cada nodo.", no: "No los crea (nodo_crear)." },
+  nodo_crear: { que: "Alta de una logística/nodo.", uso: "nombre + telefono opcional. Solo admin global.", ej: "nodo_crear nombre:'Nodo Oeste' telefono:'11...'.", no: "No toca dinero." },
+  sugerencias_listar: { que: "Sugerencias entrantes de usuarios (funciones/mejoras/bugs) con usuario, rol, nodo, estado.", uso: "rol y/o estado opcionales. Operador: su nodo; admin: todas.", ej: "sugerencias_listar estado:nueva.", no: "No las implementa; es lectura." },
+};
+
+// Renderiza la ayuda. q = nombre de tool o clave de tema (opcional).
+// ctx = { version, disponibles: Set<string> } — disponibles filtra el índice a lo
+// que ese usuario realmente tiene (según su rol/permisos).
+export function renderAyuda(q, ctx = {}) {
+  const version = ctx.version ?? "";
+  const disponibles = ctx.disponibles instanceof Set ? ctx.disponibles : null;
+  const clave = String(q ?? "").trim().toLowerCase().replace(/[^a-z_]/g, "");
+
+  if (!clave) return indice(version, disponibles);
+
+  if (TOPICS[clave]) return TOPICS[clave] + `\n\n(Consultá una herramienta con: ayuda tool:<nombre>)`;
+
+  const d = TOOL_DOCS[clave];
+  if (d) {
+    const tiene = !disponibles || disponibles.has(clave);
+    const nota = tiene ? "" : "\n\n(⚠️ Con tu rol/permiso actual esta herramienta no está disponible.)";
+    return [
+      `🔧 ${clave}`,
+      "",
+      `Qué hace: ${d.que}`,
+      `Cómo usar: ${d.uso}`,
+      `Ejemplo: ${d.ej}`,
+      `Qué NO hace: ${d.no}`,
+    ].join("\n") + nota;
+  }
+
+  // No matcheó: sugerir por prefijo/substring.
+  const cerca = Object.keys(TOOL_DOCS).filter((n) => n.includes(clave)).slice(0, 8);
+  const temas = Object.keys(TOPICS);
+  return [
+    `No encontré una herramienta o tema llamado "${clave}".`,
+    cerca.length ? `¿Quisiste decir?: ${cerca.join(", ")}` : "",
+    `Temas disponibles: ${temas.join(", ")}`,
+    `Sin argumentos, ayuda te da el índice completo.`,
+  ].filter(Boolean).join("\n");
+}
+
+function indice(version, disponibles) {
+  const out = [
+    `AYUDA DEL MCP NEXUS FLEX${version ? ` (v${version})` : ""}`,
+    "",
+    "Pedí el detalle de una herramienta con:  ayuda tool:<nombre>",
+    "Pedí un tema transversal con:            ayuda tema:<clave>",
+    `Temas: ${Object.keys(TOPICS).join(", ")}`,
+    "",
+    "Herramientas" + (disponibles ? " disponibles para vos" : "") + ":",
+  ];
+  for (const g of GROUPS) {
+    const items = g.tools.filter((t) => TOOL_DOCS[t] && (!disponibles || disponibles.has(t)));
+    if (!items.length) continue;
+    out.push("", `▸ ${g.titulo}`);
+    for (const t of items) out.push(`  • ${t} — ${TOOL_DOCS[t].que}`);
+  }
+  // Tools registradas que no estén en ningún grupo (por si se agrega una y se olvida).
+  if (disponibles) {
+    const enGrupos = new Set(GROUPS.flatMap((g) => g.tools));
+    const sueltas = [...disponibles].filter((t) => TOOL_DOCS[t] && !enGrupos.has(t));
+    if (sueltas.length) {
+      out.push("", "▸ Otras");
+      for (const t of sueltas) out.push(`  • ${t} — ${TOOL_DOCS[t].que}`);
+    }
+  }
+  return out.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexusflex-mcp",
-  "version": "3.1.0",
+  "version": "3.6.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",
@@ -11,11 +11,30 @@
     "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"],
+  "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",
+    "docs.mjs",
+    "README.md",
+    "INSTALAR.md"
+  ],
   "scripts": {
     "start": "node server.mjs",
     "login": "node server.mjs login",
@@ -25,5 +44,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.24.1"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/server.mjs

@@ -25,6 +25,7 @@
 // ============================================================================
 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];
@@ -53,7 +54,15 @@ 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.1.0" });
+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. */
@@ -81,7 +90,8 @@ 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);
+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
@@ -115,6 +125,31 @@ tool("mis_datos", {
   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.
 // ============================================================================
@@ -164,6 +199,32 @@ if (isCliente) {
     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")));
 }
 
 // ============================================================================
@@ -248,11 +309,354 @@ if (isCliente || (isStaff && puede("gestion"))) {
   }, 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.",
@@ -325,6 +729,15 @@ if (ALLOW_PRECIOS && puede("precios")) {
   }, 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";