@zincapp/mcp-server 1.11.0 → 1.12.0

package/dist/client.d.ts

@@ -6,4 +6,6 @@ export declare class ZincAppClient {
     constructor(config: McpConfig);
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    private send;
 }

package/dist/client.js

@@ -32,9 +32,15 @@ export class ZincAppClient {
         return res.json();
     }
     async post(path, body, extraHeaders) {
+        return this.send('POST', path, body, extraHeaders);
+    }
+    async put(path, body, extraHeaders) {
+        return this.send('PUT', path, body, extraHeaders);
+    }
+    async send(method, path, body, extraHeaders) {
         const url = `${this.baseUrl}/agent/v1${path}`;
         const res = await fetch(url, {
-            method: 'POST',
+            method,
             headers: {
                 'Authorization': `Bearer ${this.token}`,
                 'Accept': 'application/json',

package/dist/tools/index.js

@@ -18,6 +18,7 @@ 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';
+import { registerPrintables } from './printables.js';
 export function registerAllTools(server, client) {
     registerSearchDocs(server, client);
     registerReadDoc(server, client);
@@ -39,4 +40,5 @@ export function registerAllTools(server, client) {
     registerLookupAuthorization(server, client);
     registerNtFinalGestor(server, client);
     registerUpsertGestor(server, client);
+    registerPrintables(server, client);
 }

package/dist/tools/printables.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+interface SeriesSummary {
+    seriesUuid: string;
+    module: string | null;
+    document: string | null;
+    title: string | null;
+    style: string | null;
+}
+/** Page raster width in px — same as the portal's PAGE_WIDTH so the agent sees what the studio sees. */
+export declare const PAGE_WIDTH = 800;
+/** Default pages rasterised per render — the portal's MAX_PAGES. */
+export declare const DEFAULT_RENDER_PAGES = 3;
+/** Hard cap on pages per render (image content is expensive for the model). */
+export declare const MAX_RENDER_PAGES = 8;
+/**
+ * Rasterise a PDF to page PNGs — the Node twin of the portal's `renderPdfPages`
+ * (zn-web-app-v1 `printables/utils/pdf-images.ts`): pdfjs render at a fixed page width, one
+ * image per page, capped. Browser canvas → `@napi-rs/canvas`; JPEG → PNG (lossless proves
+ * layout: hairlines, kerning and 1px borders survive). Exported for tests.
+ */
+export declare function rasterizePdfToPngs(pdf: Buffer, maxPages: number, pageWidth?: number): Promise<{
+    pageCount: number;
+    pngs: Buffer[];
+}>;
+/** Una línea por serie, con el uuid en código para copiar/pegar en las demás herramientas. */
+export declare function formatSeriesList(series: SeriesSummary[]): string;
+/** JSON pretty en bloque de código — el modelo/estilo se lee y se re-manda ENTERO al actualizar. */
+export declare function formatJsonBlock(obj: unknown): string;
+/**
+ * Traduce el error del POST de render a una acción para el operador. El 409 característico es
+ * "No render session is stored for this elevation" — la elevación está viva pero el backend no
+ * capturó el sessid al elevarte (elevate lo captura best-effort): la salida es re-elevarte en la
+ * web. Cualquier otro error se muestra tal cual (el backend ya habla claro).
+ */
+export declare function renderErrorHint(message: string): string;
+export declare function registerPrintables(server: McpServer, client: ZincAppClient): void;
+export {};

package/dist/tools/printables.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
+// ── Rasterisation constants (mirrors the portal's renderPdfPages, pdf-images.ts) ──────────────
+/** Page raster width in px — same as the portal's PAGE_WIDTH so the agent sees what the studio sees. */
+export const PAGE_WIDTH = 800;
+/** Default pages rasterised per render — the portal's MAX_PAGES. */
+export const DEFAULT_RENDER_PAGES = 3;
+/** Hard cap on pages per render (image content is expensive for the model). */
+export const MAX_RENDER_PAGES = 8;
+/**
+ * Rasterise a PDF to page PNGs — the Node twin of the portal's `renderPdfPages`
+ * (zn-web-app-v1 `printables/utils/pdf-images.ts`): pdfjs render at a fixed page width, one
+ * image per page, capped. Browser canvas → `@napi-rs/canvas`; JPEG → PNG (lossless proves
+ * layout: hairlines, kerning and 1px borders survive). Exported for tests.
+ */
+export async function rasterizePdfToPngs(pdf, maxPages, pageWidth = PAGE_WIDTH) {
+    // Dynamic imports: pdfjs is a multi-MB parse and the canvas binding is native — only render pays.
+    const { getDocument } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const { createCanvas } = await import('@napi-rs/canvas');
+    const doc = await getDocument({
+        data: new Uint8Array(pdf),
+        isEvalSupported: false,
+    }).promise;
+    try {
+        const pageCount = doc.numPages;
+        const toRender = Math.min(pageCount, maxPages);
+        const pngs = [];
+        for (let i = 1; i <= toRender; i++) {
+            const page = await doc.getPage(i);
+            const base = page.getViewport({ scale: 1 });
+            const viewport = page.getViewport({ scale: pageWidth / base.width });
+            const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+            const ctx = canvas.getContext('2d');
+            await page.render({
+                canvasContext: ctx,
+                viewport,
+            }).promise;
+            pngs.push(canvas.toBuffer('image/png'));
+        }
+        return { pageCount, pngs };
+    }
+    finally {
+        await doc.destroy();
+    }
+}
+// ── Pure formatting helpers (exported for tests) ───────────────────────────────────────────────
+/** Una línea por serie, con el uuid en código para copiar/pegar en las demás herramientas. */
+export function formatSeriesList(series) {
+    if (series.length === 0)
+        return 'No hay series de printables.';
+    return series
+        .map((s) => {
+        const title = s.title ?? '(sin título)';
+        const doc = [s.module, s.document].filter(Boolean).join(' / ') || '—';
+        return `- **${title}** · \`${s.seriesUuid}\` · ${doc} · estilo: ${s.style ?? '—'}`;
+    })
+        .join('\n');
+}
+/** JSON pretty en bloque de código — el modelo/estilo se lee y se re-manda ENTERO al actualizar. */
+export function formatJsonBlock(obj) {
+    return '```json\n' + JSON.stringify(obj ?? null, null, 2) + '\n```';
+}
+/**
+ * Traduce el error del POST de render a una acción para el operador. El 409 característico es
+ * "No render session is stored for this elevation" — la elevación está viva pero el backend no
+ * capturó el sessid al elevarte (elevate lo captura best-effort): la salida es re-elevarte en la
+ * web. Cualquier otro error se muestra tal cual (el backend ya habla claro).
+ */
+export function renderErrorHint(message) {
+    if (/render session/i.test(message)) {
+        return ('# Render no disponible\n\n' +
+            'Tu elevación está abierta pero no tiene sesión de render capturada (se captura al ' +
+            'elevar, best-effort). Cierra la elevación y **vuelve a elevarte desde el portal web** ' +
+            'para capturar una nueva, y relanza la herramienta.\n\n' +
+            `_Detalle del backend:_ ${message}`);
+    }
+    return `# Error del render\n\n${message}`;
+}
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+// ── Tools ──────────────────────────────────────────────────────────────────────────────────────
+export function registerPrintables(server, client) {
+    server.tool('list_printable_series', 'Lista el catálogo de series de printables de plataforma (documentos imprimibles: facturas, ' +
+        'albaranes, tickets…): uuid, módulo/documento, título y estilo asignado. Sólo resúmenes — el ' +
+        'modelo se lee con read_printable_model. Requiere el permiso de operador `printables`; NO ' +
+        'requiere elevación (son datos globales de plataforma, sin tenant). Ningún parámetro de ' +
+        'company, host ni identidad.', {}, async () => {
+        const series = await client.get('/printable/series');
+        return text(`# Series de printables (${series.length})\n\n${formatSeriesList(series)}`);
+    });
+    server.tool('read_printable_model', 'Lee el MODELO completo (JSON) de una serie de printable — la definición del documento que ' +
+        'edita el estudio de printables del portal. Léelo SIEMPRE antes de update_printable_model: ' +
+        'la actualización reemplaza el modelo entero, así que tu edición parte de este JSON. ' +
+        'Permiso `printables`; sin elevación.', {
+        seriesUuid: z.string().describe('El uuid de la serie (de list_printable_series)'),
+    }, async ({ seriesUuid }) => {
+        const m = await client.get(`/printable/series/${encodeURIComponent(seriesUuid)}/model`);
+        return text(`# Modelo · serie ${m.seriesUuid}\n\n${formatJsonBlock(m.model)}`);
+    });
+    server.tool('update_printable_model', 'REEMPLAZA el modelo (JSON completo) de una serie de printable. Flujo lectura→edición: lee el ' +
+        'modelo actual con read_printable_model, aplica tu cambio sobre ese JSON y manda aquí el ' +
+        'MODELO ENTERO resultante (no un parche — lo que mandes es lo que queda). El backend guarda ' +
+        'un snapshot de versión antes de sobrescribir (mismo camino guardado que usa el portal). ' +
+        'Sólo aplica cambios que hayas revisado. Permiso `printables`; sin elevación. Verifica el ' +
+        'resultado visualmente con render_printable.', {
+        seriesUuid: z.string().describe('El uuid de la serie (de list_printable_series)'),
+        model: z
+            .record(z.string(), z.unknown())
+            .describe('El modelo COMPLETO resultante (JSON de read_printable_model con tu edición)'),
+    }, async ({ seriesUuid, model }) => {
+        const updated = await client.put(`/printable/series/${encodeURIComponent(seriesUuid)}/model`, { confirm: true, model });
+        return text(`# Modelo actualizado · serie ${updated.seriesUuid}\n\n` +
+            'El backend guardó un snapshot de la versión anterior antes de sobrescribir.\n\n' +
+            `Modelo vigente:\n${formatJsonBlock(updated.model)}\n\n` +
+            '_Comprueba el resultado con `render_printable` (requiere elevación web activa)._');
+    });
+    server.tool('read_printable_style', 'Lee la DEFINICIÓN DE ESTILO (JSON) asignada a una serie de printable (colores, fuentes, ' +
+        'espaciados…). Ojo: el estilo es COMPARTIDO — otras series con el mismo estilo también lo ' +
+        'usan. Léelo siempre antes de update_printable_style. Permiso `printables`; sin elevación.', {
+        seriesUuid: z.string().describe('El uuid de la serie cuyo estilo quieres leer'),
+    }, async ({ seriesUuid }) => {
+        const s = await client.get(`/printable/series/${encodeURIComponent(seriesUuid)}/style`);
+        return text(`# Estilo \`${s.style}\`\n\n${formatJsonBlock(s.definition)}`);
+    });
+    server.tool('update_printable_style', 'REEMPLAZA la definición del estilo asignado a una serie. Mismo flujo lectura→edición que el ' +
+        'modelo: lee con read_printable_style, edita ese JSON y manda la DEFINICIÓN ENTERA. ' +
+        'ATENCIÓN: el estilo es compartido entre series — tu cambio afecta a TODAS las series que ' +
+        'lo usen, no sólo a ésta. El backend guarda snapshot de versión antes de sobrescribir. ' +
+        'Permiso `printables`; sin elevación. Verifica con render_printable.', {
+        seriesUuid: z.string().describe('El uuid de la serie cuyo estilo quieres actualizar'),
+        definition: z
+            .record(z.string(), z.unknown())
+            .describe('La definición COMPLETA resultante (JSON de read_printable_style con tu edición)'),
+    }, async ({ seriesUuid, definition }) => {
+        const updated = await client.put(`/printable/series/${encodeURIComponent(seriesUuid)}/style`, { confirm: true, definition });
+        return text(`# Estilo \`${updated.style}\` actualizado\n\n` +
+            'El backend guardó un snapshot de la versión anterior. Recuerda: el estilo es ' +
+            'compartido — afecta a todas las series que lo usan.\n\n' +
+            `Definición vigente:\n${formatJsonBlock(updated.definition)}\n\n` +
+            '_Comprueba el resultado con `render_printable` (requiere elevación web activa)._');
+    });
+    server.tool('render_printable', 'Renderiza una serie de printable a PDF en el servidor y te devuelve las páginas como ' +
+        'IMÁGENES PNG para que las VEAS y juzgues la maquetación (tras un update_printable_model / ' +
+        '_style). REQUIERE tu elevación de operador ABIERTA EN LA WEB: el backend renderiza contra ' +
+        'el portal del tenant elevado reutilizando la sesión capturada al elevarte — esta ' +
+        'herramienta nunca abre una elevación ni acepta company, host o cookie. El cuerpo lleva ' +
+        'sólo presentación: theme, lang y testData (ids de documentos de prueba). Salida PNG ' +
+        `a ${PAGE_WIDTH}px de ancho (el formato HTML no está expuesto por el canal agente).`, {
+        seriesUuid: z.string().describe('El uuid de la serie a renderizar'),
+        theme: z.string().optional().describe('Tema de render (por defecto el test-theme del modelo, o "black")'),
+        lang: z.string().optional().describe('Idioma del documento (por defecto el test-lang del modelo, o "es")'),
+        testData: z
+            .string()
+            .optional()
+            .describe('Ids de documentos de prueba, separados por comas (p.ej. "15,16"); por defecto el test-data del modelo'),
+        maxPages: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_RENDER_PAGES)
+            .optional()
+            .describe(`Páginas a devolver como imagen (1-${MAX_RENDER_PAGES}; por defecto ${DEFAULT_RENDER_PAGES})`),
+    }, async ({ seriesUuid, theme, lang, testData, maxPages }) => {
+        // La elevación se abre en la web — si no hay, guía al operador en vez de un HTTP opaco.
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        let r;
+        try {
+            r = await client.post(`/printable/series/${encodeURIComponent(seriesUuid)}/render`, { theme, lang, testData });
+        }
+        catch (e) {
+            return text(renderErrorHint(e.message));
+        }
+        const pdf = Buffer.from(r.pdfBase64, 'base64');
+        const { pageCount, pngs } = await rasterizePdfToPngs(pdf, maxPages ?? DEFAULT_RENDER_PAGES);
+        const truncated = pngs.length < pageCount
+            ? ` (mostrando ${pngs.length}; sube maxPages para ver más)`
+            : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Render · serie ${seriesUuid} · company ${elev.companyId}\n` +
+                        `${pageCount} página(s)${truncated} · PNG a ${PAGE_WIDTH}px`,
+                },
+                ...pngs.map((p) => ({
+                    type: 'image',
+                    data: p.toString('base64'),
+                    mimeType: 'image/png',
+                })),
+            ],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zincapp/mcp-server",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "MCP server for ZincApp — search docs, read API reference, execute sandbox calls, and audit/complete waste removals (retiradas)",
   "type": "module",
   "bin": {
@@ -28,11 +28,13 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "@napi-rs/canvas": "^0.1.100",
+    "pdfjs-dist": "^4.10.38",
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
   },
   "repository": {
     "type": "git",
@@ -43,6 +45,6 @@
     "provenance": true
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }