@pharmadate/mcp 0.0.0-stage → 0.1.1

package/dist/scrub.js

@@ -0,0 +1,49 @@
+/**
+ * Redaccion de credenciales.
+ *
+ * Ninguna API key ni token del MCP puede acabar en un log, en un mensaje de error ni en un resultado de herramienta
+ * (salvo la key que el usuario ha pedido ver con `reveal_api_key: true`, que sale por su propio bloque).
+ *
+ * @module scrub
+ */
+/** API keys de Pharmadate: `pk_live_`, `pk_partner_`, `pk_test_` y `pk_admin_` seguidas de hex. */
+const KEY_RE = /pk_(live|partner|test|admin)_[0-9a-fA-F]{16,}/g;
+/** Tokens que emite el OAuth del propio MCP (`pda1.` + base64url). */
+const TOKEN_RE = /pd[acr]1\.[A-Za-z0-9_-]{16,}/g;
+/** `Bearer <algo>` suelto en un texto. */
+const BEARER_RE = /(Bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi;
+/** Sustituye las credenciales de un texto por marcas inofensivas. */
+export function scrubText(texto) {
+    return texto
+        .replace(KEY_RE, 'pk_$1_[REDACTED]')
+        .replace(TOKEN_RE, '[REDACTED_TOKEN]')
+        .replace(BEARER_RE, '$1[REDACTED]');
+}
+/** Un `Error` como objeto plano y redactado: sus campos no son enumerables y `Object.entries(err)` daba `{}` (se perdia el motivo). */
+export function scrubError(err) {
+    const salida = { name: err.name, message: scrubText(err.message) };
+    if (typeof err.stack === 'string')
+        salida.stack = scrubText(err.stack);
+    return salida;
+}
+/** Igual que {@link scrubText} pero recorre objetos y listas. No muta el original. Los `Error` salen como `{name, message, stack}`. */
+export function scrubDeep(valor, profundidad = 0) {
+    if (valor instanceof Error)
+        return scrubError(valor);
+    if (profundidad > 12)
+        return valor;
+    if (typeof valor === 'string')
+        return scrubText(valor);
+    if (Array.isArray(valor))
+        return valor.map((v) => scrubDeep(v, profundidad + 1));
+    if (valor && typeof valor === 'object') {
+        const salida = {};
+        for (const [k, v] of Object.entries(valor)) {
+            salida[k] = /^(authorization|api_key|apikey|x-api-key|access_token|refresh_token|client_secret)$/i.test(k)
+                ? '[REDACTED]'
+                : scrubDeep(v, profundidad + 1);
+        }
+        return salida;
+    }
+    return valor;
+}

package/dist/server-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Instrucciones del servidor: el modelo mental que recibe el LLM al conectar. Se mantienen cortas; el detalle esta en
+ * los resources (`pharmadate://docs/...`) y en las descripciones de cada herramienta.
+ *
+ * @module server-instructions
+ */
+import type { Role } from './principal.js';
+export declare function buildInstructions(role: Role): string;

package/dist/server-instructions.js

@@ -0,0 +1,39 @@
+export function buildInstructions(role) {
+    const comun = `
+# Pharmadate MCP
+
+Pharmadate es la plataforma de pedidos de farmacias a laboratorios y almacen. Este servidor expone su API v1; el nombre de cada herramienta es el \`operationId\` del OpenAPI.
+
+## Flujo de un pedido
+1. **getCatalog** (con \`q\`) para localizar los productos y su codigo nacional (CN). El precio del catalogo es orientativo.
+2. **createQuote** SIEMPRE antes de pedir: ensena al usuario el resumen (total, lineas no servibles, si llega al pedido minimo).
+3. **createOrder** solo tras la confirmacion EXPLICITA del usuario. Es un pedido REAL y firme.
+   - \`external_ref\` es obligatoria y es la clave de idempotencia: inventala UNA vez y REUTILIZALA en cualquier reintento.
+   - Si la llamada se corta, NO la repitas con otra ref: reintenta con la misma o consulta listOrders con \`external_ref\`.
+4. **listOrders / getOrder / listOrderShipments / getOrderModification** para seguir el pedido (estados, envios, faltas).
+
+## Reglas
+- Nunca inventes codigos nacionales, ids, CIF ni referencias: salen de las herramientas o del usuario.
+- Pide confirmacion antes de cualquier escritura. Las destructivas (baja, rotar key, modificar) llevan \`destructiveHint\`.
+- Un error de la herramienta (\`isError\`) trae la accion siguiente en el texto: sigue esa instruccion en vez de reintentar a ciegas.
+- Las API keys son secretos. No las repitas ni las guardes; \`reveal_api_key: true\` las entrega al usuario en un bloque aparte, pero pueden quedar en el historial del chat.
+
+## Errores frecuentes -> accion
+- \`external_ref_conflict\`: la ref ya existe con otra cesta -> getOrder del \`order_id\` o usa otra ref nueva (con confirmacion).
+- \`below_minimum_order\` (422): no llega al minimo -> ensena \`order_minimum\`; no se creo nada.
+- \`pharmacy_inactive\`: farmacia de baja -> reactivatePharmacy.
+- \`pharmacy_active\` (409 al reactivar): ya esta activa -> rotatePharmacyApiKey si se necesita una key nueva.
+`;
+    const partner = `
+## Eres un PARTNER
+Las herramientas operativas (getConditions, lookupConditions, createQuote, createOrder, listOrders, getOrder, getOrderModification, listOrderShipments, getOrderShipment, getShipment) piden el argumento **pharmacy**: \`{ pharmacy_id }\` (preferido) o \`{ cif }\`.
+- La farmacia se COMPRUEBA antes de operar. Si no es una de las tuyas y activa, no se hace nada: este MCP nunca da de alta una farmacia por error.
+- Para una farmacia nueva: **listPharmacies** (comprueba el CIF), luego **createPharmacy** con confirmacion del usuario.
+- Gestion de farmacias: listPharmacies, getPharmacy, createPharmacy, updatePharmacy, deactivatePharmacy (se deshace con reactivatePharmacy), reactivatePharmacy, rotatePharmacyApiKey (invalida la anterior en el acto).
+`;
+    const farmacia = `
+## Eres una FARMACIA
+Tu API key ya identifica a la farmacia: no hay que indicar ninguna. Solo ves y pides lo tuyo. Las herramientas de gestion de farmacias son solo para partners.
+`;
+    return (comun + (role === 'partner' ? partner : farmacia)).trim();
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Fabrica del servidor MCP: `createPharmadateServer({ principal, client })`.
+ *
+ * Se crea UNO por peticion (HTTP stateless) o uno por proceso (stdio), siempre atado a la credencial del cliente. No
+ * guarda ningun estado de negocio: la autorizacion la hace la API en cada llamada.
+ *
+ * @module server
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { PharmadateClient } from './client.js';
+import type { OperationMode } from './config.js';
+import { credentialId, type Principal } from './principal.js';
+import type { PharmacyRefArg } from './pharmacy-resolver.js';
+import { McpLimits } from './limits.js';
+import { type ToolDef } from './tools/index.js';
+export interface CreateServerOptions {
+    principal: Principal;
+    client: PharmadateClient;
+    /** Hash de la credencial (clave de los limites). */
+    credentialId: string;
+    mode: OperationMode;
+    limits: McpLimits;
+    /** stdio: el cliente MCP ya esta conectado y su nombre va al User-Agent. */
+    transport?: 'stdio' | 'remote';
+    /** Farmacia por defecto (PHARMADATE_PHARMACY_REF), solo partners. */
+    defaultPharmacy?: PharmacyRefArg | undefined;
+}
+/** Herramientas que se registran para un rol y modo (en READ_ONLY no se ofrecen las de escritura). */
+export declare function selectTools(principal: Principal, mode: OperationMode, defaultPharmacy?: boolean): ToolDef[];
+export declare function createPharmadateServer(options: CreateServerOptions): McpServer;
+export { credentialId };

package/dist/server.js

@@ -0,0 +1,59 @@
+/**
+ * Fabrica del servidor MCP: `createPharmadateServer({ principal, client })`.
+ *
+ * Se crea UNO por peticion (HTTP stateless) o uno por proceso (stdio), siempre atado a la credencial del cliente. No
+ * guarda ningun estado de negocio: la autorizacion la hace la API en cada llamada.
+ *
+ * @module server
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { credentialId } from './principal.js';
+import { buildUserAgent } from './client.js';
+import { deniedMessage, isAllowed } from './operation-mode.js';
+import { errResult } from './results.js';
+import { buildInstructions } from './server-instructions.js';
+import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.js';
+import { toolsForRole } from './tools/index.js';
+import { logger } from './logger.js';
+import { VERSION } from './version.js';
+/** Herramientas que se registran para un rol y modo (en READ_ONLY no se ofrecen las de escritura). */
+export function selectTools(principal, mode, defaultPharmacy = false) {
+    return toolsForRole(principal.role, { defaultPharmacy }).filter((t) => isAllowed(mode, t.op));
+}
+export function createPharmadateServer(options) {
+    const { principal, client, mode, limits } = options;
+    const server = new McpServer({ name: 'pharmadate-mcp', title: 'Pharmadate', version: VERSION }, { instructions: buildInstructions(principal.role), capabilities: { logging: {} } });
+    for (const tool of selectTools(principal, mode, options.defaultPharmacy !== undefined && principal.role === 'partner')) {
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: { title: tool.title, ...tool.annotations } }, async (args) => {
+            const t0 = Date.now();
+            if (!isAllowed(mode, tool.op))
+                return errResult(deniedMessage(tool.name, mode), { error_code: 'operation_not_permitted' });
+            if (tool.op !== 'READ') {
+                const rechazo = limits.check(options.credentialId, tool.name === 'createOrder');
+                if (rechazo)
+                    return errResult(rechazo, { error_code: 'write_rate_limit_exceeded' });
+            }
+            try {
+                const result = await tool.handler(args, { client, principal, defaultPharmacy: options.defaultPharmacy });
+                logger.info({ tool: tool.name, role: principal.role, isError: result.isError === true, ms: Date.now() - t0, request_id: result._meta?.['request_id'] }, 'tool call');
+                return result;
+            }
+            catch (err) {
+                logger.error({ err, tool: tool.name }, 'tool call failed');
+                return errResult(`Error interno del MCP al ejecutar ${tool.name}. No se ha confirmado que la operacion se ejecutara.`, { error_code: 'mcp_internal_error' });
+            }
+        });
+    }
+    if (options.transport === 'stdio') {
+        server.server.oninitialized = () => {
+            const info = server.server.getClientVersion();
+            if (info)
+                client.setUserAgent(buildUserAgent(VERSION, 'stdio', `${info.name}/${info.version}`));
+        };
+    }
+    registerResources(server, client, principal);
+    registerPrompts(server, principal.role);
+    return server;
+}
+export { credentialId };

package/dist/tools/common.d.ts

@@ -0,0 +1,9 @@
+import type { Role } from '../principal.js';
+import { type ToolDef } from './types.js';
+/**
+ * Construye las herramientas comunes para un rol: solo el partner ve el argumento `pharmacy` (opcional si hay una farmacia
+ * por defecto configurada, `PHARMADATE_PHARMACY_REF`).
+ */
+export declare function commonTools(role: Role, opts?: {
+    defaultPharmacy?: boolean;
+}): ToolDef[];

package/dist/tools/common.js

@@ -0,0 +1,225 @@
+/**
+ * Herramientas comunes: las 12 operaciones de catalogo, condiciones, valoracion, pedidos y envios.
+ * Las usa una farmacia (con su key) o un partner (con el argumento `pharmacy`).
+ *
+ * @module tools/common
+ */
+import { z } from 'zod';
+import { LONG_TIMEOUT_MS } from '../client.js';
+import { MAX_LINES } from '../limits.js';
+import { pharmacyRefShape } from '../pharmacy-resolver.js';
+import { apiErrorResult, networkErrorResult, okResult } from '../results.js';
+import { ApiNetworkError } from '../client.js';
+import { operate } from './operate.js';
+import { BOTH_ROLES, READ_ANN } from './types.js';
+const LINEA = z.object({
+    cn: z.string().min(1).max(20).describe('Codigo nacional (CN) del producto. Solo cuentan los digitos.'),
+    unidades: z.number().int().min(1).max(99_999_999).describe('Unidades (entero >= 1).'),
+    descripcion: z.string().max(255).optional().describe('Opcional, solo informativo.'),
+});
+const ITEMS = z
+    .array(LINEA)
+    .min(1)
+    .max(MAX_LINES)
+    .describe(`Lineas de la cesta (entre 1 y ${MAX_LINES}). Un mismo CN repetido se fusiona.`);
+/** Un CN que va en la ruta (`/conditions/{cn}`): solo digitos. Se comprueba aqui y no se confia en `encodeURIComponent`. */
+const CN_RUTA = z.string().regex(/^\d{1,20}$/, 'Un codigo nacional son solo digitos (hasta 20).');
+const ORDER_ID = z.number().int().positive().describe('`order_id` del pedido en Pharmadate.');
+const SHIPMENT_ID = z.string().max(100).regex(/^shp_[\w-]+$/, 'Un shipment_id tiene la forma shp_... (letras, digitos, _ y -).').describe('Identificador del envio (`shp_...`, opaco y global).');
+const PAGE = z.number().int().min(1).optional().describe('Pagina (empieza en 1).');
+/**
+ * Construye las herramientas comunes para un rol: solo el partner ve el argumento `pharmacy` (opcional si hay una farmacia
+ * por defecto configurada, `PHARMADATE_PHARMACY_REF`).
+ */
+export function commonTools(role, opts = {}) {
+    const farmacia = role === 'partner' ? { pharmacy: opts.defaultPharmacy ? pharmacyRefShape.optional() : pharmacyRefShape } : {};
+    const aviso = role === 'partner' ? ' Con key de partner indica `pharmacy` (la farmacia se comprueba antes de operar).' : '';
+    return [
+        {
+            name: 'ping',
+            title: 'Comprobar la conexion',
+            description: 'Comprueba que la credencial es valida y dice quien eres: devuelve el partner o la farmacia asociados y la version de la API. No tiene efectos. Util para empezar.',
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/ping' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: {},
+            handler: async (_args, ctx) => {
+                try {
+                    const res = await ctx.client.request({ method: 'GET', path: '/v1/ping' });
+                    if (!res.ok)
+                        return apiErrorResult(res);
+                    return okResult({ role: ctx.principal.role, ...res.body }, { request_id: res.requestId, http_status: res.status });
+                }
+                catch (err) {
+                    if (err instanceof ApiNetworkError)
+                        return networkErrorResult(err);
+                    throw err;
+                }
+            },
+        },
+        {
+            name: 'getCatalog',
+            title: 'Buscar en el catalogo',
+            description: 'Catalogo de Pharmadate (la matriz y las referencias que solo existen dentro de una oferta, con `in_matrix: false`). Usa `q` para buscar por nombre o laboratorio (p. ej. q="ibuprofeno 600"). ' +
+                'El precio (`list_price_eur`) es ORIENTATIVO: el bueno lo da createQuote. No hace falta indicar farmacia. Por defecto 50 por pagina.',
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/catalog' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: {
+                q: z.string().min(2).max(100).optional().describe('Busqueda por nombre: cada palabra debe aparecer en la descripcion o el laboratorio, sin distinguir mayusculas ni tildes.'),
+                since: z.string().max(40).optional().describe('Solo lo modificado despues de esta fecha ISO 8601 (el `as_of` de una pasada anterior).'),
+                page: PAGE,
+                per_page: z.number().int().min(1).max(500).optional().describe('Resultados por pagina (maximo 500, por defecto 50).'),
+            },
+            handler: async (args, ctx) => operate(ctx, null, {
+                method: 'GET',
+                path: '/v1/catalog',
+                query: { q: args.q, since: args.since, page: args.page, per_page: args.per_page ?? 50 },
+            }),
+        },
+        {
+            name: 'getConditions',
+            title: 'Condiciones de un producto',
+            description: `Ofertas y condiciones comerciales vigentes de UN codigo nacional (precio, descuento, minimos y escalones).${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/conditions/{cn}' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, cn: CN_RUTA.describe('Codigo nacional (solo digitos).') },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/conditions/${encodeURIComponent(args.cn)}` }),
+        },
+        {
+            name: 'lookupConditions',
+            title: 'Condiciones de varios productos',
+            description: `Consulta masiva de condiciones (hasta 1000 codigos nacionales). No crea nada.${aviso}`,
+            op: 'READ',
+            http: { method: 'POST', path: '/api/v1/conditions/lookup' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, codes: z.array(z.string().min(1).max(20)).min(1).max(1000).describe('Codigos nacionales.') },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'POST', path: '/v1/conditions/lookup', body: { codes: args.codes } }),
+        },
+        {
+            name: 'createQuote',
+            title: 'Valorar una cesta (sin pedir)',
+            description: 'Valora una cesta SIN crear nada: precio por linea, ofertas desbloqueadas y las que faltan por alcanzar, envios, impuestos y pedido minimo. ' +
+                'Hazlo SIEMPRE antes de un pedido y ENSEÑA el resumen al usuario (total, lineas no servibles, si llega al minimo). Se puede repetir las veces que haga falta.' +
+                aviso,
+            op: 'READ',
+            http: { method: 'POST', path: '/api/v1/quote' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, items: ITEMS },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'POST', path: '/v1/quote', body: { items: args.items }, timeoutMs: LONG_TIMEOUT_MS }),
+        },
+        {
+            name: 'createOrder',
+            title: 'Crear un pedido REAL',
+            description: 'Crea un pedido REAL y firme (no se puede cancelar ni modificar por API; solo Pharmadate puede cancelarlo). ' +
+                'Hazlo SOLO tras createQuote y tras la confirmacion EXPLICITA del usuario con el resumen delante. ' +
+                '`external_ref` es OBLIGATORIA y actua como clave de idempotencia: inventala UNA SOLA VEZ para este pedido (p. ej. "mcp-2026-11-04-1") y REUTILIZA la misma si reintentas; misma ref y misma cesta devuelve el pedido existente (200), con otra cesta da external_ref_conflict. ' +
+                'Si se corta la llamada, NO repitas con otra ref: reintenta con la misma o mira listOrders con external_ref. Limite: 10 pedidos por hora.' +
+                aviso,
+            op: 'WRITE',
+            http: { method: 'POST', path: '/api/v1/orders' },
+            roles: BOTH_ROLES,
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            inputSchema: {
+                ...farmacia,
+                external_ref: z.string().min(1).max(255).regex(/^[^\u0000-\u001f\u007f]+$/, 'Sin caracteres de control').describe('Referencia unica del pedido (clave de idempotencia). Obligatoria.'),
+                items: ITEMS,
+                cooperativa: z.enum(['BIDAFARMA', 'HEFAME', 'COFARES', 'ALLIANCE', 'OTROS', 'PHARMADATE']).optional().describe('Cooperativa, si hay que fijarla.'),
+            },
+            handler: async (args, ctx) => {
+                const body = { items: args.items, external_ref: args.external_ref };
+                if (args.cooperativa)
+                    body['cooperativa'] = args.cooperativa;
+                return operate(ctx, args.pharmacy, { method: 'POST', path: '/v1/orders', body, timeoutMs: LONG_TIMEOUT_MS }, { externalRef: args.external_ref });
+            },
+        },
+        {
+            name: 'listOrders',
+            title: 'Listar pedidos',
+            description: `Lista los pedidos de la farmacia, paginados, con filtros por fecha, estado y \`external_ref\`. Con include="items" trae las lineas y los envios.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/orders' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: {
+                ...farmacia,
+                updated_since: z.string().max(40).optional().describe('Pedidos movidos despues de esta fecha ISO 8601 (usa el `as_of` anterior).'),
+                from: z.string().max(40).optional().describe('Creados desde (AAAA-MM-DD).'),
+                to: z.string().max(40).optional().describe('Creados hasta el final de este dia (AAAA-MM-DD).'),
+                external_ref: z.string().max(255).optional().describe('Busca por la referencia con la que se creo el pedido.'),
+                status: z.enum(['confirmed', 'sent_to_lab', 'invoiced', 'cancelled']).optional(),
+                status_detail: z.enum(['confirmed', 'sent_to_lab', 'shipped', 'delivered', 'invoiced', 'cancelled']).optional(),
+                shipment_status: z.enum(['confirmed', 'sent_to_lab', 'shipped', 'delivered', 'invoiced', 'cancelled']).optional().describe('Pedidos con algun envio en ese estado.'),
+                modified: z.boolean().optional().describe('true: solo pedidos con faltas definitivas.'),
+                include: z.enum(['items', 'shipments']).optional().describe('`items` incluye lineas y envios; `shipments` solo los envios.'),
+                page: PAGE,
+                per_page: z.number().int().min(1).max(200).optional().describe('Maximo 200 (por defecto 50).'),
+            },
+            handler: async (args, ctx) => {
+                const { pharmacy, ...query } = args;
+                return operate(ctx, pharmacy, { method: 'GET', path: '/v1/orders', query });
+            },
+        },
+        {
+            name: 'getOrder',
+            title: 'Detalle de un pedido',
+            description: `Un pedido completo: lineas, totales, impuestos, envios y estado.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/orders/{id}' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, id: ORDER_ID },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/orders/${args.id}` }),
+        },
+        {
+            name: 'getOrderModification',
+            title: 'Faltas y modificaciones de un pedido',
+            description: `Lo realmente servido frente a lo pedido: faltas definitivas, lineas modificadas y totales ajustados.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/orders/{id}/modification' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, id: ORDER_ID },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/orders/${args.id}/modification` }),
+        },
+        {
+            name: 'listOrderShipments',
+            title: 'Envios de un pedido',
+            description: `Los envios en que se reparte un pedido (Pharmadate, laboratorios, cooperativas) con su estado y entrega estimada.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/orders/{id}/shipments' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, id: ORDER_ID },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/orders/${args.id}/shipments` }),
+        },
+        {
+            name: 'getOrderShipment',
+            title: 'Un envio de un pedido',
+            description: `Un envio concreto de un pedido, con sus lineas y su estado.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/orders/{id}/shipments/{shipment_id}' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, id: ORDER_ID, shipment_id: SHIPMENT_ID },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/orders/${args.id}/shipments/${encodeURIComponent(args.shipment_id)}` }),
+        },
+        {
+            name: 'getShipment',
+            title: 'Un envio por su identificador',
+            description: `Un envio por su \`shipment_id\` global, sin necesitar el id del pedido.${aviso}`,
+            op: 'READ',
+            http: { method: 'GET', path: '/api/v1/shipments/{shipment_id}' },
+            roles: BOTH_ROLES,
+            annotations: READ_ANN,
+            inputSchema: { ...farmacia, shipment_id: SHIPMENT_ID },
+            handler: async (args, ctx) => operate(ctx, args.pharmacy, { method: 'GET', path: `/v1/shipments/${encodeURIComponent(args.shipment_id)}` }),
+        },
+    ];
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Registro de herramientas por rol.
+ *
+ *   farmacia: 12 (las comunes, sin argumento `pharmacy`)
+ *   partner:  19 (las 12 comunes con `pharmacy` + las 7 del CRUD de farmacias)
+ *   admin:    F2 (no incluido en esta fase)
+ *
+ * @module tools
+ */
+import type { Role } from '../principal.js';
+import type { ToolDef } from './types.js';
+export type { ToolDef, ToolContext } from './types.js';
+export declare function toolsForRole(role: Role, opts?: {
+    defaultPharmacy?: boolean;
+}): ToolDef[];

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+import { commonTools } from './common.js';
+import { partnerTools } from './partner.js';
+export function toolsForRole(role, opts = {}) {
+    const comunes = commonTools(role, opts);
+    return role === 'partner' ? [...comunes, ...partnerTools()] : comunes;
+}

package/dist/tools/operate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Plantilla comun de las herramientas operativas (las que, con una key de partner, necesitan una farmacia).
+ *
+ * @module tools/operate
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type ApiRequest } from '../client.js';
+import { type PharmacyRefArg } from '../pharmacy-resolver.js';
+import { type ErrorContext } from '../results.js';
+import type { ToolContext } from './types.js';
+/**
+ * 1) resuelve la farmacia (solo partner), 2) llama a la API con `X-Pharmacy-Ref` ya verificado, 3) traduce la respuesta.
+ * Con `pharmacy = null` no se resuelve nada (catalogo). El cuerpo que se pasa NUNCA lleva `pharmacy` ni `pharmacy_ref`.
+ */
+export declare function operate(ctx: ToolContext, pharmacy: PharmacyRefArg | undefined | null, req: Omit<ApiRequest, 'pharmacyCif'>, errorCtx?: ErrorContext): Promise<CallToolResult>;

package/dist/tools/operate.js

@@ -0,0 +1,24 @@
+import { ApiNetworkError } from '../client.js';
+import { resolvePharmacy } from '../pharmacy-resolver.js';
+import { apiErrorResult, networkErrorResult, okResult } from '../results.js';
+/**
+ * 1) resuelve la farmacia (solo partner), 2) llama a la API con `X-Pharmacy-Ref` ya verificado, 3) traduce la respuesta.
+ * Con `pharmacy = null` no se resuelve nada (catalogo). El cuerpo que se pasa NUNCA lleva `pharmacy` ni `pharmacy_ref`.
+ */
+export async function operate(ctx, pharmacy, req, errorCtx = {}) {
+    try {
+        // `null`: la operacion no necesita farmacia (catalogo): no se resuelve nada ni se envia X-Pharmacy-Ref
+        const resolution = pharmacy === null ? { ok: true, cif: undefined } : await resolvePharmacy(ctx.client, ctx.principal, pharmacy ?? ctx.defaultPharmacy);
+        if (!resolution.ok)
+            return resolution.result;
+        const res = await ctx.client.request({ ...req, ...(resolution.cif ? { pharmacyCif: resolution.cif } : {}) });
+        if (!res.ok)
+            return apiErrorResult(res, { pharmacyId: 'pharmacy' in resolution ? resolution.pharmacy?.id : undefined, ...errorCtx });
+        return okResult(res.body, { request_id: res.requestId, http_status: res.status });
+    }
+    catch (err) {
+        if (err instanceof ApiNetworkError)
+            return networkErrorResult(err);
+        throw err;
+    }
+}

package/dist/tools/partner.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDef } from './types.js';
+export declare function partnerTools(): ToolDef[];