@zincapp/mcp-server 1.8.0 → 1.10.0

package/dist/tools/index.js

@@ -16,6 +16,8 @@ import { registerApplyAuthorization } from './apply-authorization.js';
 import { registerLinkGestorAuthorizations } from './link-gestor-authorizations.js';
 import { registerProposeNt } from './propose-nt.js';
 import { registerLookupAuthorization } from './lookup-authorization.js';
+import { registerNtFinalGestor } from './nt-final-gestor.js';
+import { registerUpsertGestor } from './upsert-gestor.js';
 export function registerAllTools(server, client) {
     registerSearchDocs(server, client);
     registerReadDoc(server, client);
@@ -35,4 +37,6 @@ export function registerAllTools(server, client) {
     registerLinkGestorAuthorizations(server, client);
     registerProposeNt(server, client);
     registerLookupAuthorization(server, client);
+    registerNtFinalGestor(server, client);
+    registerUpsertGestor(server, client);
 }

package/dist/tools/nt-final-gestor.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+/** Límite de tamaño de PDF, alineado con el importer (LapazImportEndpoint.kt:62 → 25 MB/PDF). */
+export declare const MAX_PDF_BYTES: number;
+/** Valida que los bytes son un PDF (`%PDF` magic) y no exceden el límite. Puro y exportado para test. */
+export declare function validatePdf(bytes: Buffer): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function registerNtFinalGestor(server: McpServer, client: ZincAppClient): void;

package/dist/tools/nt-final-gestor.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { resolveElevation } from './elevation.js';
+/** Límite de tamaño de PDF, alineado con el importer (LapazImportEndpoint.kt:62 → 25 MB/PDF). */
+export const MAX_PDF_BYTES = 25 * 1024 * 1024;
+/** Valida que los bytes son un PDF (`%PDF` magic) y no exceden el límite. Puro y exportado para test. */
+export function validatePdf(bytes) {
+    if (bytes.length < 5 || bytes.subarray(0, 5).toString('latin1') !== '%PDF-') {
+        return { ok: false, error: 'El fichero no es un PDF (no empieza por "%PDF-").' };
+    }
+    if (bytes.length > MAX_PDF_BYTES) {
+        return { ok: false, error: `El PDF es demasiado grande (${bytes.length} bytes; máximo ${MAX_PDF_BYTES}, 25 MB).` };
+    }
+    return { ok: true };
+}
+/** Resuelve el base64 del PDF desde EXACTAMENTE uno de pdfPath | pdfBase64. */
+function resolvePdfBase64(pdfPath, pdfBase64) {
+    const hasPath = typeof pdfPath === 'string' && pdfPath.length > 0;
+    const hasB64 = typeof pdfBase64 === 'string' && pdfBase64.length > 0;
+    if (hasPath === hasB64) {
+        return { ok: false, error: 'Aporta EXACTAMENTE uno de pdfPath o pdfBase64 (no ambos, no ninguno).' };
+    }
+    let bytes;
+    if (hasPath) {
+        try {
+            bytes = readFileSync(pdfPath);
+        }
+        catch (e) {
+            return { ok: false, error: `No pude leer el PDF en '${pdfPath}': ${e.message}` };
+        }
+    }
+    else {
+        try {
+            bytes = Buffer.from(pdfBase64, 'base64');
+        }
+        catch (e) {
+            return { ok: false, error: `pdfBase64 no es base64 válido: ${e.message}` };
+        }
+    }
+    const v = validatePdf(bytes);
+    if (!v.ok)
+        return v;
+    return { ok: true, base64: bytes.toString('base64') };
+}
+const errorContent = (text) => ({ content: [{ type: 'text', text }] });
+export function registerNtFinalGestor(server, client) {
+    server.tool('preview_nt_final_gestor', 'DRY-RUN: extrae por IA el "Gestor final para la operación Dxx" del PDF de una Notificación Previa ' +
+        '(NT), lo resuelve contra las entidades/centros de tu tenant, valida las invariantes E3L ' +
+        '(operación en Table2Type + autorización por LER del centro), y devuelve una PROPUESTA opaca ' +
+        '(con proposalId) SIN escribir nada. Aporta el PDF con pdfPath (ruta local) o pdfBase64 ' +
+        '(exactamente uno). Revisa la propuesta y, si es correcta, aplícala con apply_nt_final_gestor. ' +
+        'Corre bajo tu elevación de operador (company derivada de ella).', {
+        ntNumero: z.string().describe('El número de la NT objetivo (p.ej. "NT30280008283420220064303")'),
+        pdfPath: z.string().optional().describe('Ruta local al PDF de la NT (alternativa a pdfBase64)'),
+        pdfBase64: z.string().optional().describe('El PDF de la NT en base64 (alternativa a pdfPath)'),
+    }, async ({ ntNumero, pdfPath, pdfBase64 }) => {
+        const pdf = resolvePdfBase64(pdfPath, pdfBase64);
+        if (!pdf.ok)
+            return errorContent(`# Error\n${pdf.error}`);
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const p = await client.post('/mwm/retirada/preview-nt-final-gestor', { ntNumero, pdfBase64: pdf.base64 });
+        if (!p.resoluble) {
+            return errorContent(`# Propuesta · NT ${p.ntNumero} — NO RESOLUBLE\n\n` +
+                `**Razón:** ${p.razon ?? 'desconocida'}\n\n` +
+                `Terna actual en la NT: ${fmtTriple(p.ternaActual)}. No se ha persistido nada.`);
+        }
+        const text = `# Propuesta · NT ${p.ntNumero}\n\n` +
+            `- **proposalId:** \`${p.proposalId}\`\n` +
+            `- **Nº de NT en el documento:** ${p.ntNumeroDocumento ?? '—'}\n` +
+            `- **Gestor final propuesto:** ${fmtTriple(p.gestorFinal)}\n` +
+            `- **Terna actual en la NT:** ${fmtTriple(p.ternaActual)}\n\n` +
+            `Si es correcto, aplica con \`apply_nt_final_gestor({ proposalId: "${p.proposalId}" })\`. ` +
+            `La propuesta caduca (TTL) — aplícala pronto.`;
+        return { content: [{ type: 'text', text }] };
+    });
+    server.tool('apply_nt_final_gestor', 'Aplica una propuesta de gestor final previamente revisada (por proposalId de preview_nt_final_gestor). ' +
+        'NO re-ejecuta la IA ni re-transporta el PDF. Escribe la terna (clientId, centerId, operación) en ' +
+        'la NT bajo tu elevación de operador, por el framework (hooks + auditoría), con regla ' +
+        'complete-what\'s-missing (si la NT ya tiene un gestor final distinto → conflicto, no se ' +
+        'sobrescribe). Sólo aplica propuestas que hayas verificado.', {
+        proposalId: z.string().describe('El proposalId devuelto por preview_nt_final_gestor'),
+    }, async ({ proposalId }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const r = await client.post('/mwm/retirada/apply-nt-final-gestor', { proposalId });
+        const titulo = r.outcome === 'applied'
+            ? `# Aplicado · NT ${r.ntNumero}`
+            : `# Sin cambios · NT ${r.ntNumero}`;
+        const text = `${titulo}\n\n` +
+            `- **Resultado:** ${r.outcome}\n` +
+            `- **Gestor final:** ${fmtTriple(r.gestorFinal)}\n\n` +
+            `_Recuerda des-elevarte desde el portal web con un motivo cuando termines._`;
+        return { content: [{ type: 'text', text }] };
+    });
+}
+function fmtTriple(t) {
+    if (!t || (t.clientId == null && t.centerId == null && t.operacion == null))
+        return '(vacía)';
+    return `entidad ${t.clientId ?? '—'} / centro ${t.centerId ?? '—'} · operación ${t.operacion ?? '—'}`;
+}

package/dist/tools/upsert-gestor.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerUpsertGestor(server: McpServer, client: ZincAppClient): void;

package/dist/tools/upsert-gestor.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
+export function registerUpsertGestor(server, client) {
+    server.tool('upsert_entidad', 'Alta o completado (best-effort) de una entidad gestor/transportista por CIF, bajo la elevación del ' +
+        'operador. Idempotente: si el CIF ya existe la completa (solo los campos aportados), si no la crea. ' +
+        'No valida E3L: rellena lo disponible.', {
+        cif: z.string().describe('CIF de la entidad (identidad; requerido).'),
+        nombre: z.string().optional(),
+        entityType: z.number().int().optional().describe('tipo_entidad (E3L lo exige a nivel entidad).'),
+        telefono: z.string().optional(),
+        mail: z.string().optional(),
+        gestor: z.boolean().optional(),
+        transportista: z.boolean().optional(),
+    }, async (args) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const res = await client.post('/mwm/retirada/upsert-entidad', { confirm: true, ...args });
+        const verbo = res.outcome === 'created' ? 'creada' : 'actualizada';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Entidad **${verbo}** (CIF \`${args.cif}\`) — clientId \`${res.clientId}\`.`,
+                }],
+        };
+    });
+    server.tool('upsert_centro', 'Alta o completado (best-effort) de un centro de un gestor, bajo la elevación del operador. Identidad ' +
+        'por centerId o por nima inequívoco (varios con la misma nima → 409, aporta centerId). Valida un id de ' +
+        'catálogo solo si se aporta. Si aportas authId+autorizacion, hace también el upsert de la autorización.', {
+        clientId: z.number().int().describe('clientId de la entidad padre (requerido; debe existir).'),
+        centerId: z.number().int().optional().describe('Identidad explícita del centro (si se conoce).'),
+        nima: z.number().int().optional().describe('NIMA para identificar el centro si no hay centerId.'),
+        nombre: z.string().optional(),
+        direccion: z.string().optional(),
+        ciudad: z.string().optional(),
+        cp: z.string().optional(),
+        regionId: z.number().int().optional(),
+        provinceId: z.number().int().optional(),
+        localityId: z.number().int().optional(),
+        vialId: z.number().int().optional(),
+        codigoCnae: z.string().optional().describe('Código CNAE (varchar(4), PK de IneCnae).'),
+        telefono: z.string().optional(),
+        mail: z.string().optional(),
+        authId: z.string().optional().describe('Tipo de autorización (T01/G0x) — con autorizacion, hace el upsert.'),
+        autorizacion: z.string().optional().describe('Número de registro de la autorización (lo aporta el humano).'),
+    }, async (args) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const res = await client.post('/mwm/retirada/upsert-centro', { confirm: true, ...args });
+        const verbo = res.outcome === 'created' ? 'creado' : 'actualizado';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Centro **${verbo}** — clientId \`${res.clientId}\`, centerId \`${res.centerId}\`.`,
+                }],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zincapp/mcp-server",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "MCP server for ZincApp — search docs, read API reference, execute sandbox calls, and audit/complete waste removals (retiradas)",
   "type": "module",
   "bin": {