@zincapp/mcp-server 1.3.1 → 1.4.0

package/dist/client.js

@@ -39,7 +39,7 @@ 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.
+                // Optional per-call headers (currently unused; kept for forward compatibility).
                 ...(extraHeaders ?? {}),
             },
             body: body ? JSON.stringify(body) : undefined,

package/dist/tools/apply-completion.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 // The confirmed edit shape (mirrors the backend ReconcileApplyItem). Produced from propose_completion.
 const EditSchema = z.object({
     removalId: z.number(),
@@ -18,25 +19,21 @@ 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'),
+        'elevation, and if you are not elevated 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. The company is DERIVED from your ' +
+        'elevation (no companyId parameter). Only apply edits you have confirmed.', {
         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 });
+    }, async ({ edits }) => {
+        // Step 1: check the operator's current elevation (opened in the web with step-up). The
+        // company is whatever you elevated into — it is never passed by the tool.
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const companyId = elev.companyId;
+        // Step 2: apply under the active elevation. The backend derives the company from the live
+        // OPEN row and re-verifies eligibility — the companyId is NOT sent (server is the authority).
+        const result = await client.post('/mwm/retirada/apply-elevated', { confirm: true, edits });
         const ok = result.applied.length;
         const bad = result.failed.length;
         const failLines = bad

package/dist/tools/audit-entities.js

@@ -1,15 +1,20 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'one row per party, ranked by how many removals use it. Read-only, no AI. Runs under YOUR ' +
+        'active operator elevation — the company is the one you elevated into from the web (no ' +
+        'companyId parameter).', {
         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 };
+    }, async ({ role, year }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const companyId = elev.companyId;
+        const params = { role };
         if (year != null)
             params.year = String(year);
         const r = await client.get('/mwm/retirada/audit-entities', params);

package/dist/tools/audit-retiradas.js

@@ -1,14 +1,19 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'Runs under YOUR active operator elevation: the company is the one you elevated into from the ' +
+        'web (no companyId parameter). If you are not elevated, it asks you to elevate first.', {
         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) };
+    }, async ({ year, limit }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const companyId = elev.companyId;
+        const params = { year: String(year) };
         if (limit != null)
             params.limit = String(limit);
         const r = await client.get('/mwm/retirada/audit', params);

package/dist/tools/elevation.d.ts

@@ -0,0 +1,29 @@
+import type { ZincAppClient } from '../client.js';
+/** The operator's current web-opened elevation, as seen through the agent token's account. */
+export interface CurrentElevation {
+    companyId: number | null;
+    elevated: boolean;
+}
+/** A user-facing text result (the MCP tool content shape) — returned when NOT elevated. */
+export type NotElevatedResult = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};
+/**
+ * Resolve the operator's active elevation for a retirada tool.
+ *
+ * The agent channel derives the tenant from the operator's WEB-opened elevation — no tool takes a
+ * companyId, and the agent token NEVER opens an elevation itself (that needs the web step-up). This
+ * helper hits `operator/current-elevation` and returns EITHER the elevated `companyId`, or a ready
+ * user-facing message telling the operator to elevate in the web first.
+ *
+ * Usage:
+ *   const elev = await resolveElevation(client)
+ *   if ('content' in elev) return elev   // not elevated → surface the message
+ *   const companyId = elev.companyId     // proceed under this tenant
+ */
+export declare function resolveElevation(client: ZincAppClient): Promise<{
+    companyId: number;
+} | NotElevatedResult>;

package/dist/tools/elevation.js

@@ -0,0 +1,27 @@
+/**
+ * Resolve the operator's active elevation for a retirada tool.
+ *
+ * The agent channel derives the tenant from the operator's WEB-opened elevation — no tool takes a
+ * companyId, and the agent token NEVER opens an elevation itself (that needs the web step-up). This
+ * helper hits `operator/current-elevation` and returns EITHER the elevated `companyId`, or a ready
+ * user-facing message telling the operator to elevate in the web first.
+ *
+ * Usage:
+ *   const elev = await resolveElevation(client)
+ *   if ('content' in elev) return elev   // not elevated → surface the message
+ *   const companyId = elev.companyId     // proceed under this tenant
+ */
+export async function resolveElevation(client) {
+    const elev = await client.get('/mwm/retirada/operator/current-elevation');
+    if (!elev.elevated || elev.companyId == null) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'No estás elevado a ningún tenant. Elévate a la company objetivo desde el portal web ' +
+                        '(IAM → elevar) con step-up, y luego vuelve a lanzar la herramienta. El token nunca ' +
+                        'abre una elevación por sí mismo — actúa bajo la que tú abras en la web.',
+                }],
+        };
+    }
+    return { companyId: elev.companyId };
+}

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

@@ -1,14 +1,17 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'mismatch plus the field that proves it. Read-only, no AI. Runs under YOUR active operator ' +
+        'elevation — the company is the one you elevated into from the web (no companyId parameter).', {
         removalId: z.number().describe('The removal id to audit'),
-    }, async ({ companyId, removalId }) => {
-        const a = await client.get(`/mwm/retirada/audit/${removalId}`, { companyId: String(companyId) });
+    }, async ({ removalId }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const a = await client.get(`/mwm/retirada/audit/${removalId}`);
         const icon = (s) => (s === 'ok' ? '✅' : s === 'mismatch' ? '⚠️' : '❌');
         const lines = a.findings.map(f => {
             const cur = f.current ?? '—';

package/dist/tools/propose-authorizations.js

@@ -1,15 +1,20 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'registry number; the agent only proposes the type. Runs under YOUR active operator elevation ' +
+        '— the company is the one you elevated into from the web (no companyId parameter).', {
         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 };
+    }, async ({ role, year }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const companyId = elev.companyId;
+        const params = { role };
         if (year != null)
             params.year = String(year);
         const r = await client.get('/mwm/retirada/propose-authorizations', params);

package/dist/tools/propose-completion.js

@@ -1,15 +1,19 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'each cost an AI call). Runs under YOUR active operator elevation — the company is the one you ' +
+        'elevated into from the web (no companyId parameter).', {
         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) });
+    }, async ({ removalId }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const d = await client.get(`/mwm/retirada/propose/${removalId}`);
         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.).` }] };
         }

package/dist/tools/propose-nt.js

@@ -1,14 +1,19 @@
 import { z } from 'zod';
+import { resolveElevation } from './elevation.js';
 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'),
+        'creates via the web UI. Runs under YOUR active operator elevation — the company is the one ' +
+        'you elevated into from the web (no companyId parameter).', {
         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) });
+    }, async ({ removalId }) => {
+        const elev = await resolveElevation(client);
+        if ('content' in elev)
+            return elev;
+        const companyId = elev.companyId;
+        const p = await client.get(`/mwm/retirada/propose-nt/${removalId}`);
         if (p.alreadyHasNt) {
             return { content: [{ type: 'text', text: `La retirada ${removalId} ya tiene NT. Nada que proponer.` }] };
         }

package/package.json

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