@zincapp/mcp-server 1.0.1 → 1.3.0

package/dist/client.d.ts

@@ -2,7 +2,8 @@ import type { McpConfig } from './config.js';
 export declare class ZincAppClient {
     private baseUrl;
     private token;
+    private locale;
     constructor(config: McpConfig);
-    get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
 }

package/dist/client.js

@@ -1,13 +1,25 @@
 export class ZincAppClient {
     baseUrl;
     token;
+    locale;
     constructor(config) {
         this.baseUrl = config.apiBaseUrl.replace(/\/$/, '');
         this.token = config.agentToken;
+        this.locale = config.locale;
     }
-    async get(path) {
-        const url = `${this.baseUrl}/agent/v1${path}`;
-        const res = await fetch(url, {
+    async get(path, params) {
+        const url = new URL(`${this.baseUrl}/agent/v1${path}`);
+        // Auto-append locale if not English
+        if (this.locale && this.locale !== 'en') {
+            url.searchParams.set('locale', this.locale);
+        }
+        // Apply per-call param overrides
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const res = await fetch(url.toString(), {
             headers: {
                 'Authorization': `Bearer ${this.token}`,
                 'Accept': 'application/json',
@@ -19,7 +31,7 @@ export class ZincAppClient {
         }
         return res.json();
     }
-    async post(path, body) {
+    async post(path, body, extraHeaders) {
         const url = `${this.baseUrl}/agent/v1${path}`;
         const res = await fetch(url, {
             method: 'POST',
@@ -27,6 +39,8 @@ export class ZincAppClient {
                 'Authorization': `Bearer ${this.token}`,
                 'Accept': 'application/json',
                 'Content-Type': 'application/json',
+                // e.g. the X-Agent-Apply-Token carrying the batch-bound, single-use human-apply token.
+                ...(extraHeaders ?? {}),
             },
             body: body ? JSON.stringify(body) : undefined,
         });

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 export interface McpConfig {
     agentToken: string;
     apiBaseUrl: string;
+    locale: string;
 }
 /**
  * Loads config from environment variables, then falls back to .zincapp.json

package/dist/config.js

@@ -9,6 +9,7 @@ export function loadConfig() {
     // Environment variables take precedence
     let agentToken = process.env.ZINCAPP_AGENT_TOKEN || '';
     let apiBaseUrl = process.env.ZINCAPP_API_URL || '';
+    let locale = process.env.ZINCAPP_LOCALE || '';
     // Try .zincapp.json if env vars missing
     if (!agentToken) {
         const configPaths = [
@@ -23,6 +24,8 @@ export function loadConfig() {
                     agentToken = parsed.agentToken;
                 if (!apiBaseUrl && parsed.apiUrl)
                     apiBaseUrl = parsed.apiUrl;
+                if (!locale && parsed.locale)
+                    locale = parsed.locale;
                 break;
             }
             catch {
@@ -37,5 +40,6 @@ export function loadConfig() {
     return {
         agentToken,
         apiBaseUrl: apiBaseUrl || 'https://api.zincapp.com/api',
+        locale: locale || 'en',
     };
 }

package/dist/tools/apply-completion.d.ts

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

package/dist/tools/apply-completion.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+// The confirmed edit shape (mirrors the backend ReconcileApplyItem). Produced from propose_completion.
+const EditSchema = z.object({
+    removalId: z.number(),
+    fields: z.record(z.string(), z.string().nullable()).optional(),
+    createTransport: z
+        .object({
+        cif: z.string(),
+        nombre: z.string(),
+        nima: z.number().nullable().optional(),
+        direccion: z.string().nullable().optional(),
+    })
+        .nullable()
+        .optional(),
+    ntId: z.number().nullable().optional(),
+});
+export function registerApplyCompletion(server, client) {
+    server.tool('apply_completion', 'Apply confirmed field completions to waste removals, UNDER YOUR ACTIVE OPERATOR ELEVATION. ' +
+        'You (the platform operator) must first elevate into the company from the web (IAM) — this ' +
+        'tool NEVER opens an elevation itself (that requires the web step-up). It checks your current ' +
+        'elevation, and if you are not elevated into this company it asks you to do so in the web, then ' +
+        'applies each confirmed edit through the framework (hooks + audit fire) as the elevated ' +
+        '_sysadmin, recording the real operator in the elevation audit trail. Requires the ' +
+        'RETIRADAS_WRITE scope + companyId in the token allowlist. Only apply edits you have confirmed.', {
+        companyId: z.number().describe('The company (tenant) id you are elevated into, e.g. 9'),
+        edits: z.array(EditSchema).describe('The confirmed edits (from propose_completion), one per removal'),
+    }, async ({ companyId, edits }) => {
+        // Step 1: check the operator's current elevation (opened in the web with step-up).
+        const elev = await client.get('/mwm/retirada/operator/current-elevation');
+        if (!elev.elevated) {
+            return { content: [{ type: 'text', text: `No estás elevado a ningún tenant. Elévate a la company ${companyId} desde el portal web ` +
+                            `(IAM → elevar), y luego vuelve a lanzar apply_completion.` }] };
+        }
+        if (elev.companyId !== companyId) {
+            return { content: [{ type: 'text', text: `Estás elevado a la company ${elev.companyId}, no a la ${companyId}. Des-elévate y eleva a ` +
+                            `la ${companyId} desde el portal web, luego vuelve a lanzar apply_completion.` }] };
+        }
+        // Step 2: apply under the active elevation. The backend re-verifies eligibility + the live OPEN.
+        const result = await client.post('/mwm/retirada/apply-elevated', { companyId, confirm: true, edits });
+        const ok = result.applied.length;
+        const bad = result.failed.length;
+        const failLines = bad
+            ? '\n\n### Fallidos\n' + result.failed.map(f => `- Retirada ${f.removalId}: ${f.error}`).join('\n')
+            : '';
+        const text = `# Aplicado · company ${companyId}\n` +
+            `${ok} retirada(s) actualizada(s)${bad ? `, ${bad} con error` : ''}, bajo tu elevación de operador.\n` +
+            (ok ? '\nAplicadas: ' + result.applied.join(', ') : '') +
+            failLines +
+            `\n\n_Recuerda des-elevarte desde el portal web con un motivo cuando termines._`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/audit-entities.d.ts

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

package/dist/tools/audit-entities.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export function registerAuditEntities(server, client) {
+    server.tool('audit_entities', 'Audit the gestores or transportistas used by a company\'s waste removals. For each distinct ' +
+        'party it checks: authorization (T01/T02 by hazard for transporters; destino+hazard role ' +
+        'flags for gestores), NIMA validity (exactly 10 digits), and address plausibility. Returns ' +
+        'one row per party, ranked by how many removals use it. Read-only, no AI. Requires the ' +
+        'RETIRADAS_AUDIT scope + the companyId in the allowlist.', {
+        companyId: z.number().describe('The company (tenant) id, e.g. 9'),
+        role: z.enum(['gestor', 'transportista']).describe('Which party role to audit'),
+        year: z.number().optional().describe('Restrict to removals of this year (optional)'),
+    }, async ({ companyId, role, year }) => {
+        const params = { companyId: String(companyId), role };
+        if (year != null)
+            params.year = String(year);
+        const r = await client.get('/mwm/retirada/audit-entities', params);
+        if (r.parties.length === 0) {
+            return { content: [{ type: 'text', text: `Sin ${r.role}s en las retiradas de la company ${companyId}.` }] };
+        }
+        const rows = r.parties.map(p => {
+            const flag = (ok) => (ok ? '✅' : '❌');
+            const name = p.nombre ?? p.cif ?? '(sin nombre)';
+            const checks = `NIMA ${flag(p.nimaValid)}${p.nima ? ` (${p.nima})` : ''} · ` +
+                `Dir ${flag(p.direccionPlausible)} · ` +
+                `Autoriz ${flag(p.autorizacionPresent)}${p.autorizacion ? ` (${p.autorizacion})` : ''}`;
+            const gap = p.hasGaps ? '⚠️ ' : '';
+            return `- ${gap}**${name}** — ${p.usedByRemovals} retirada(s)${p.peligroso ? ' · peligroso' : ''}\n  ${checks}`;
+        }).join('\n');
+        const gapCount = r.parties.filter(p => p.hasGaps).length;
+        const text = `# Auditoría ${r.role}s · company ${companyId}\n` +
+            `${r.parties.length} ${r.role}(s), ${gapCount} con gaps\n\n${rows}`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/audit-retiradas.d.ts

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

package/dist/tools/audit-retiradas.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export function registerAuditRetiradas(server, client) {
+    server.tool('audit_retiradas', 'Audit a company\'s waste removals (retiradas) for a year. Returns a health projection — how ' +
+        'many removals are missing an NT, a transporter, documents, a residue, how many have a kg ' +
+        'mismatch or exceed NT capacity — plus a ranked list of the worst offenders. Read-only, no AI. ' +
+        'The token must hold the RETIRADAS_AUDIT scope and list the companyId in its allowlist.', {
+        companyId: z.number().describe('The company (tenant) id to audit, e.g. 9 for La Paz'),
+        year: z.number().describe('Calendar year, e.g. 2025'),
+        limit: z.number().optional().describe('Max ranked removals to return (default 20, max 100)'),
+    }, async ({ companyId, year, limit }) => {
+        const params = { companyId: String(companyId), year: String(year) };
+        if (limit != null)
+            params.limit = String(limit);
+        const r = await client.get('/mwm/retirada/audit', params);
+        const s = r.stats;
+        const summary = `# Auditoría retiradas · company ${companyId} · ${s.year}\n\n` +
+            `**Total:** ${s.total} (${s.abiertas} abiertas)\n\n` +
+            `| Dimensión | Faltan |\n|---|---|\n` +
+            `| Sin NT | ${s.sinNt} |\n` +
+            `| Sin transportista | ${s.sinTransportista} |\n` +
+            `| Sin documentos | ${s.sinDi} |\n` +
+            `| Sin residuo (LER) | ${s.sinResiduo} |\n` +
+            `| Kg mismatch | ${s.kgMismatch} |\n` +
+            `| Exceso capacidad NT | ${s.ntExcesoKg} |\n`;
+        const ranked = r.worst.length === 0
+            ? '\n\n_Sin retiradas con gaps en el ranking escaneado._'
+            : '\n\n## Peores retiradas (por nº de gaps)\n' +
+                r.worst.map(w => {
+                    const gaps = w.findings.filter(f => f.status !== 'ok')
+                        .map(f => `${f.dimension}:${f.status}`).join(', ');
+                    return `- **${w.removalId}** (${w.label}) — ${gaps}`;
+                }).join('\n');
+        const note = `\n\n_Escaneadas ${r.scanned} retiradas para el ranking (top ${r.ranked})._`;
+        return { content: [{ type: 'text', text: summary + ranked + note }] };
+    });
+}

package/dist/tools/get-retirada-audit.d.ts

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

package/dist/tools/get-retirada-audit.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export function registerGetRetiradaAudit(server, client) {
+    server.tool('get_retirada_audit', 'Audit ONE waste removal (retirada) across every dimension: transporter (+ its T01/T02 ' +
+        'authorization), NT, declared vs weighed kg, residue (LER), R/D operation codes, gestor ' +
+        'NIMA/authorization/address, and attached documents. Each check reports ok / missing / ' +
+        'mismatch plus the field that proves it. Read-only, no AI. The token must hold RETIRADAS_AUDIT ' +
+        'and list the companyId.', {
+        companyId: z.number().describe('The company (tenant) id, e.g. 9'),
+        removalId: z.number().describe('The removal id to audit'),
+    }, async ({ companyId, removalId }) => {
+        const a = await client.get(`/mwm/retirada/audit/${removalId}`, { companyId: String(companyId) });
+        const icon = (s) => (s === 'ok' ? '✅' : s === 'mismatch' ? '⚠️' : '❌');
+        const lines = a.findings.map(f => {
+            const cur = f.current ?? '—';
+            const exp = f.expected != null ? ` → esperado: ${f.expected}` : '';
+            return `${icon(f.status)} **${f.dimension}**: ${f.status} (actual: ${cur}${exp}) · _${f.provingField}_`;
+        }).join('\n');
+        const text = `# Retirada ${a.removalId} — ${a.label}\n` +
+            `${a.hasGaps ? '**Tiene gaps.**' : '**Completa.**'}\n\n${lines}`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/index.js

@@ -5,6 +5,13 @@ import { registerListEndpoints } from './list-endpoints.js';
 import { registerGetEndpoint } from './get-endpoint.js';
 import { registerSandboxRequest } from './sandbox-request.js';
 import { registerGetContract } from './get-contract.js';
+import { registerAuditRetiradas } from './audit-retiradas.js';
+import { registerGetRetiradaAudit } from './get-retirada-audit.js';
+import { registerProposeCompletion } from './propose-completion.js';
+import { registerAuditEntities } from './audit-entities.js';
+import { registerApplyCompletion } from './apply-completion.js';
+import { registerProposeAuthorizations } from './propose-authorizations.js';
+import { registerProposeNt } from './propose-nt.js';
 export function registerAllTools(server, client) {
     registerSearchDocs(server, client);
     registerReadDoc(server, client);
@@ -13,4 +20,11 @@ export function registerAllTools(server, client) {
     registerGetEndpoint(server, client);
     registerSandboxRequest(server, client);
     registerGetContract(server, client);
+    registerAuditRetiradas(server, client);
+    registerGetRetiradaAudit(server, client);
+    registerProposeCompletion(server, client);
+    registerAuditEntities(server, client);
+    registerApplyCompletion(server, client);
+    registerProposeAuthorizations(server, client);
+    registerProposeNt(server, client);
 }

package/dist/tools/list-docs.js

@@ -1,6 +1,8 @@
+import { z } from 'zod';
 export function registerListDocs(server, client) {
-    server.tool('list_docs', 'List all available ZincApp developer documentation with titles and summaries.', {}, async () => {
-        const docs = await client.get('/docs?limit=200');
+    server.tool('list_docs', 'List all available ZincApp developer documentation with titles and summaries.', { locale: z.enum(['en', 'es']).optional().describe('Language locale (default: config locale)') }, async ({ locale }) => {
+        const params = locale ? { locale } : undefined;
+        const docs = await client.get('/docs?limit=200', params);
         const text = docs.length === 0
             ? 'No documentation available.'
             : docs.map(d => `- **${d.title}** (\`${d.id}\`): ${d.aiSummary || d.description}`).join('\n');

package/dist/tools/propose-authorizations.d.ts

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

package/dist/tools/propose-authorizations.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export function registerProposeAuthorizations(server, client) {
+    server.tool('propose_authorizations', 'PROPOSE-ONLY: for each gestor or transportista used by the company\'s removals that lacks the ' +
+        'required authorization, suggest the static authorization TYPE codes (authId) that would ' +
+        'satisfy it — T01/T02 by hazard for transporters, destino+hazard role flags for gestores. ' +
+        'Read-only, never writes. A human still creates the authorization and supplies the real ' +
+        'registry number; the agent only proposes the type. Requires the RETIRADAS_AUDIT scope.', {
+        companyId: z.number().describe('The company (tenant) id, e.g. 9'),
+        role: z.enum(['gestor', 'transportista']).describe('Which party role to propose for'),
+        year: z.number().optional().describe('Restrict to removals of this year (optional)'),
+    }, async ({ companyId, role, year }) => {
+        const params = { companyId: String(companyId), role };
+        if (year != null)
+            params.year = String(year);
+        const r = await client.get('/mwm/retirada/propose-authorizations', params);
+        if (r.proposals.length === 0) {
+            return { content: [{ type: 'text', text: `Ningún ${r.role} sin autorización en la company ${companyId}.` }] };
+        }
+        const blocks = r.proposals.map(p => {
+            const name = p.nombre ?? p.cif ?? '(sin nombre)';
+            const cands = p.candidates.length
+                ? p.candidates.map(c => `  - \`${c.authId}\`${c.name ? ` — ${c.name}` : ''}`).join('\n')
+                : '  _(sin candidatos en el catálogo)_';
+            const warns = p.warnings.map(w => `  ⚠️ ${w}`).join('\n');
+            return `### ${name} — ${p.usedByRemovals} retirada(s)${p.peligroso ? ' · peligroso' : ''}\nCandidatos (authId):\n${cands}\n${warns}`;
+        }).join('\n\n');
+        const text = `# Propuesta de autorizaciones · ${r.role}s · company ${companyId}\n${r.proposals.length} sin autorización\n\n${blocks}`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/propose-completion.d.ts

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

package/dist/tools/propose-completion.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export function registerProposeCompletion(server, client) {
+    server.tool('propose_completion', 'Propose field completions for ONE waste removal by re-reading its attached documents (DIs, ' +
+        'certificates) through the importer pipeline and diffing against the current DB values. Returns ' +
+        'a typed diff: per field, the current value vs. the value read from the document, whether it ' +
+        'resolves to a DB entity, and (for a carrier not yet in the DB) the data to create it. ' +
+        'READ-ONLY — proposes only, never writes. One removal per call (cost control: scanned/CDO docs ' +
+        'each cost an AI call). Requires RETIRADAS_AUDIT scope + the companyId in the allowlist.', {
+        companyId: z.number().describe('The company (tenant) id, e.g. 9'),
+        removalId: z.number().describe('The removal id to propose completions for'),
+    }, async ({ companyId, removalId }) => {
+        const d = await client.get(`/mwm/retirada/propose/${removalId}`, { companyId: String(companyId) });
+        if (d.changes.length === 0 && d.warnings.length === 0) {
+            return { content: [{ type: 'text', text: `# Retirada ${d.removalId} — ${d.label}\n\nSin cambios propuestos (${d.docCount} doc.).` }] };
+        }
+        const changeLines = d.changes.map(c => {
+            const cur = c.currentDisplay ?? c.currentValue ?? '—';
+            const prop = c.proposedDisplay ?? c.proposedValue ?? '—';
+            const create = c.createEntity
+                ? ` · **CREAR entidad** ${c.createEntity.nombre} (CIF ${c.createEntity.cif}${c.createEntity.nima ? `, NIMA ${c.createEntity.nima}` : ''})`
+                : '';
+            const unresolved = c.resolvable || c.createEntity ? '' : ' _(no resuelve a entidad)_';
+            return `- **${c.label}** (\`${c.field}\`): ${cur} → **${prop}**${create}${unresolved}`;
+        }).join('\n');
+        const warnLines = d.warnings.length
+            ? '\n\n### Avisos\n' + d.warnings.map(w => `- ⚠️ ${w}`).join('\n')
+            : '';
+        const text = `# Retirada ${d.removalId} — ${d.label}\n` +
+            `${d.docCount} documento(s) · ${d.changes.length} cambio(s) propuesto(s)\n\n` +
+            changeLines + warnLines +
+            `\n\n_Propuesta read-only. Aplicar requerirá confirmación humana (fase de escritura)._`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/propose-nt.d.ts

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

package/dist/tools/propose-nt.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export function registerProposeNt(server, client) {
+    server.tool('propose_nt', 'PROPOSE-ONLY: for a removal WITHOUT an NT (notificación previa), describe the contract + NT + ' +
+        'NT-LER that would be created to cover it, with the create-vs-reuse dedup (existing contract ' +
+        'by parties, existing NT by code) and the human-review warnings. Read-only, never writes — ' +
+        'creating an NT is high-risk (wrong contract, duplicate, capacity), so a human confirms and ' +
+        'creates via the web UI. Requires the RETIRADAS_AUDIT scope.', {
+        companyId: z.number().describe('The company (tenant) id, e.g. 9'),
+        removalId: z.number().describe('The removal id (must have no NT)'),
+    }, async ({ companyId, removalId }) => {
+        const p = await client.get(`/mwm/retirada/propose-nt/${removalId}`, { companyId: String(companyId) });
+        if (p.alreadyHasNt) {
+            return { content: [{ type: 'text', text: `La retirada ${removalId} ya tiene NT. Nada que proponer.` }] };
+        }
+        const contract = p.reuseContractId != null
+            ? `Contrato: **reusar** el existente (ctId ${p.reuseContractId})`
+            : `Contrato: **crear uno nuevo** (no existe para estas partes)`;
+        const parties = `Partes — origen: ${p.parties.originId}/${p.parties.originCenterId} · ` +
+            `operador/destino: ${p.parties.destId}/${p.parties.destCenterId}`;
+        const residuo = `Residuo: LER ${p.codigoLer ?? '?'} (residueId ${p.residueId ?? '?'}` +
+            `${p.existingCtLerResidueId != null ? `, reusar residueId ${p.existingCtLerResidueId} del CT_LER` : ''})`;
+        const cantidad = `Cantidad NT propuesta: ${p.proposedCantidad ?? '(desconocida)'}`;
+        const warns = p.warnings.map(w => `- ⚠️ ${w}`).join('\n');
+        const text = `# Propuesta de NT · retirada ${p.removalId} · company ${companyId}\n\n` +
+            `${contract}\n${parties}\n${residuo}\n${cantidad}\n\n### Avisos de revisión\n${warns}\n\n` +
+            `_Propuesta read-only. La creación la confirma y ejecuta una persona (por el framework)._`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/read-doc.js

@@ -1,7 +1,11 @@
 import { z } from 'zod';
 export function registerReadDoc(server, client) {
-    server.tool('read_doc', 'Read a specific ZincApp documentation page by its ID. Returns the full markdown content.', { docId: z.string().describe('Document ID (e.g. "api.overview")') }, async ({ docId }) => {
-        const doc = await client.get(`/docs/${encodeURIComponent(docId)}`);
+    server.tool('read_doc', 'Read a specific ZincApp documentation page by its ID. Returns the full markdown content.', {
+        docId: z.string().describe('Document ID (e.g. "api.overview")'),
+        locale: z.enum(['en', 'es']).optional().describe('Language locale (default: config locale)'),
+    }, async ({ docId, locale }) => {
+        const params = locale ? { locale } : undefined;
+        const doc = await client.get(`/docs/${encodeURIComponent(docId)}`, params);
         const text = `# ${doc.title}\n\n${doc.markdown}`;
         return { content: [{ type: 'text', text }] };
     });

package/dist/tools/search-docs.js

@@ -1,7 +1,14 @@
 import { z } from 'zod';
 export function registerSearchDocs(server, client) {
-    server.tool('search_docs', 'Search ZincApp developer documentation by keyword. Returns matching documents ranked by relevance.', { query: z.string().describe('Search query'), limit: z.number().optional().describe('Max results (default 10)') }, async ({ query, limit }) => {
-        const results = await client.get(`/docs/search?q=${encodeURIComponent(query)}&limit=${limit || 10}`);
+    server.tool('search_docs', 'Search ZincApp developer documentation by keyword. Returns matching documents ranked by relevance.', {
+        query: z.string().describe('Search query'),
+        limit: z.number().optional().describe('Max results (default 10)'),
+        locale: z.enum(['en', 'es']).optional().describe('Language locale (default: config locale)'),
+    }, async ({ query, limit, locale }) => {
+        const params = {};
+        if (locale)
+            params.locale = locale;
+        const results = await client.get(`/docs/search?q=${encodeURIComponent(query)}&limit=${limit || 10}`, Object.keys(params).length > 0 ? params : undefined);
         const text = results.length === 0
             ? 'No documents found matching your query.'
             : results.map(r => `## ${r.title}\n- ID: \`${r.id}\`\n- ${r.aiSummary || r.description}\n- Relevance: ${r.relevance.toFixed(2)}`).join('\n\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zincapp/mcp-server",
-  "version": "1.0.1",
-  "description": "MCP server for ZincApp Developer Portal — enables AI coding assistants to search docs, read API reference, and execute sandbox API calls",
+  "version": "1.3.0",
+  "description": "MCP server for ZincApp — search docs, read API reference, execute sandbox calls, and audit/complete waste removals (retiradas)",
   "type": "module",
   "bin": {
     "zincapp-mcp-server": "./dist/index.js"