@pharmadate/mcp 0.0.0-stage → 0.1.1

package/dist/operation-mode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Clasificacion de cada herramienta por tipo de operacion y modo de operacion.
+ *
+ *   READ_ONLY  solo herramientas de lectura (incluye `createQuote` y `lookupConditions`, que son POST pero no escriben)
+ *   STANDARD   lectura y escritura (las destructivas llevan `destructiveHint` para que el cliente pida confirmacion)
+ *
+ * Una herramienta que no esta en la tabla se DENIEGA (fail-closed).
+ *
+ * @module operation-mode
+ */
+import type { OperationMode } from './config.js';
+export type OperationType = 'READ' | 'WRITE' | 'DELETE';
+export declare function isAllowed(mode: OperationMode, op: OperationType | undefined): boolean;
+export declare function deniedMessage(toolName: string, mode: OperationMode): string;

package/dist/operation-mode.js

@@ -0,0 +1,10 @@
+export function isAllowed(mode, op) {
+    if (!op)
+        return false;
+    if (mode === 'STANDARD')
+        return true;
+    return op === 'READ';
+}
+export function deniedMessage(toolName, mode) {
+    return `La herramienta ${toolName} escribe datos y no esta permitida en modo ${mode}. Arranca el MCP con PHARMADATE_MCP_MODE=STANDARD para permitir escrituras.`;
+}

package/dist/pharmacy-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolucion de la farmacia sobre la que opera un partner.
+ *
+ * PUNTO CRITICO DE SEGURIDAD. Con una credencial de partner, cualquier ruta con `apiKeyAuth` (`/quote`, `/orders`,
+ * `/conditions`...) DA DE ALTA AUTOMATICAMENTE una farmacia cuyo CIF no existe (`apiV1.js`, `apiKeyAuth`). Un CIF mal
+ * escrito por el modelo crearia, por tanto, una farmacia fantasma. Para que eso no pueda pasar:
+ *
+ *   1. La herramienta recibe `pharmacy: { pharmacy_id }` (preferido) o `pharmacy: { cif }`.
+ *   2. Se RESUELVE ANTES con `GET /pharmacies/{id}` o `GET /pharmacies?cif=` (ambas solo leen y solo ven las farmacias
+ *      del propio partner).
+ *   3. Si no aparece, o esta de baja, se responde con un error y NO se llama a la API operativa.
+ *   4. Solo entonces se envia `X-Pharmacy-Ref` con el CIF ya verificado.
+ *   5. NUNCA se envia `pharmacy` ni `pharmacy_ref` en el cuerpo (ademas lo impide `PharmadateClient`).
+ *
+ * Con una API key de farmacia no hay nada que resolver: la propia credencial identifica a la farmacia y la herramienta
+ * ni siquiera expone el argumento `pharmacy`.
+ *
+ * @module pharmacy-resolver
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { PharmadateClient } from './client.js';
+import type { Principal } from './principal.js';
+/** Argumento `pharmacy` de las herramientas operativas, solo para partners. */
+export declare const pharmacyRefShape: z.ZodObject<{
+    pharmacy_id: z.ZodOptional<z.ZodNumber>;
+    cif: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pharmacy_id?: number | undefined;
+    cif?: string | undefined;
+}, {
+    pharmacy_id?: number | undefined;
+    cif?: string | undefined;
+}>;
+export type PharmacyRefArg = z.infer<typeof pharmacyRefShape>;
+export interface ResolvedPharmacy {
+    id: number;
+    cif: string;
+    nombre: string;
+}
+export type Resolution = {
+    ok: true;
+    cif: string | undefined;
+    pharmacy?: ResolvedPharmacy;
+} | {
+    ok: false;
+    result: CallToolResult;
+};
+export declare const normalizeCif: (cif: string) => string;
+/**
+ * Devuelve el CIF que debe ir en `X-Pharmacy-Ref`, o el resultado de error que la herramienta debe devolver tal cual.
+ * Con una key de farmacia devuelve `{ok:true, cif: undefined}` y no llama a nada.
+ */
+export declare function resolvePharmacy(client: PharmadateClient, principal: Principal, ref: PharmacyRefArg | undefined): Promise<Resolution>;

package/dist/pharmacy-resolver.js

@@ -0,0 +1,92 @@
+/**
+ * Resolucion de la farmacia sobre la que opera un partner.
+ *
+ * PUNTO CRITICO DE SEGURIDAD. Con una credencial de partner, cualquier ruta con `apiKeyAuth` (`/quote`, `/orders`,
+ * `/conditions`...) DA DE ALTA AUTOMATICAMENTE una farmacia cuyo CIF no existe (`apiV1.js`, `apiKeyAuth`). Un CIF mal
+ * escrito por el modelo crearia, por tanto, una farmacia fantasma. Para que eso no pueda pasar:
+ *
+ *   1. La herramienta recibe `pharmacy: { pharmacy_id }` (preferido) o `pharmacy: { cif }`.
+ *   2. Se RESUELVE ANTES con `GET /pharmacies/{id}` o `GET /pharmacies?cif=` (ambas solo leen y solo ven las farmacias
+ *      del propio partner).
+ *   3. Si no aparece, o esta de baja, se responde con un error y NO se llama a la API operativa.
+ *   4. Solo entonces se envia `X-Pharmacy-Ref` con el CIF ya verificado.
+ *   5. NUNCA se envia `pharmacy` ni `pharmacy_ref` en el cuerpo (ademas lo impide `PharmadateClient`).
+ *
+ * Con una API key de farmacia no hay nada que resolver: la propia credencial identifica a la farmacia y la herramienta
+ * ni siquiera expone el argumento `pharmacy`.
+ *
+ * @module pharmacy-resolver
+ */
+import { z } from 'zod';
+import { ApiNetworkError } from './client.js';
+import { apiErrorResult, errResult, networkErrorResult } from './results.js';
+const CIF_VALIDO = /^[A-Z0-9]{8,12}$/;
+/** Argumento `pharmacy` de las herramientas operativas, solo para partners. */
+export const pharmacyRefShape = z
+    .object({
+    pharmacy_id: z.number().int().positive().optional().describe('Id de la farmacia en Pharmadate (el `id` que devuelven listPharmacies / createPharmacy). PREFERIDO.'),
+    cif: z.string().min(8).max(12).optional().describe('CIF de la farmacia, solo si no tienes su id. Debe ser una farmacia YA dada de alta entre las tuyas (comprueba con listPharmacies).'),
+})
+    .describe('Farmacia sobre la que operar (obligatorio con una key de partner). Indica pharmacy_id (preferido) o cif. Se resuelve ANTES de operar: si no es una farmacia tuya y activa, no se hace nada (nunca se da de alta una nueva).');
+export const normalizeCif = (cif) => cif.trim().toUpperCase();
+const NOT_FOUND = 'Farmacia no encontrada entre las tuyas. No se ha llamado a la API operativa (para no dar de alta una farmacia nueva por error). ' +
+    'Comprueba el id o el CIF con listPharmacies; si la farmacia no existe todavia, crea con createPharmacy.';
+/**
+ * Devuelve el CIF que debe ir en `X-Pharmacy-Ref`, o el resultado de error que la herramienta debe devolver tal cual.
+ * Con una key de farmacia devuelve `{ok:true, cif: undefined}` y no llama a nada.
+ */
+export async function resolvePharmacy(client, principal, ref) {
+    if (principal.role === 'pharmacy')
+        return { ok: true, cif: undefined };
+    if (!ref || (ref.pharmacy_id === undefined && !ref.cif)) {
+        return {
+            ok: false,
+            result: errResult('Falta la farmacia. Con una key de partner indica pharmacy: { pharmacy_id } (preferido) o pharmacy: { cif }. Consulta tus farmacias con listPharmacies.', { error_code: 'pharmacy_required' }),
+        };
+    }
+    if (ref.cif !== undefined && !CIF_VALIDO.test(normalizeCif(ref.cif))) {
+        return { ok: false, result: errResult('El CIF no es valido: son 8 a 12 letras o numeros, sin espacios ni guiones.', { error_code: 'invalid_cif' }) };
+    }
+    try {
+        let found;
+        if (ref.pharmacy_id !== undefined) {
+            const res = await client.request({ method: 'GET', path: `/v1/pharmacies/${ref.pharmacy_id}` });
+            if (res.status === 404)
+                return { ok: false, result: errResult(NOT_FOUND, { error_code: 'pharmacy_not_found', request_id: res.requestId }) };
+            if (!res.ok)
+                return { ok: false, result: apiErrorResult(res) };
+            found = res.body;
+        }
+        else {
+            const cif = normalizeCif(ref.cif);
+            const res = await client.request({ method: 'GET', path: '/v1/pharmacies', query: { cif, per_page: 2 } });
+            if (!res.ok)
+                return { ok: false, result: apiErrorResult(res) };
+            const lista = (res.body?.pharmacies ?? []).filter((f) => normalizeCif(f.cif) === cif);
+            found = lista.find((f) => f.active) ?? lista[0];
+            if (!found)
+                return { ok: false, result: errResult(NOT_FOUND, { error_code: 'pharmacy_not_found', request_id: res.requestId }) };
+        }
+        if (!found || !found.cif)
+            return { ok: false, result: errResult(NOT_FOUND, { error_code: 'pharmacy_not_found' }) };
+        // Si se dieron las dos cosas, tienen que ser la misma farmacia
+        if (ref.pharmacy_id !== undefined && ref.cif !== undefined && normalizeCif(ref.cif) !== normalizeCif(found.cif)) {
+            return {
+                ok: false,
+                result: errResult(`El CIF indicado no coincide con el de la farmacia ${found.id}. No se ha operado. Indica solo pharmacy_id o revisa el CIF.`, { error_code: 'pharmacy_mismatch' }),
+            };
+        }
+        if (!found.active) {
+            return {
+                ok: false,
+                result: errResult(`La farmacia ${found.id} (${found.nombre}) esta DADA DE BAJA y no puede operar. Llama a reactivatePharmacy con id ${found.id} (genera una API key nueva) y vuelve a intentarlo. No se ha hecho nada.`, { error_code: 'pharmacy_inactive' }),
+            };
+        }
+        return { ok: true, cif: normalizeCif(found.cif), pharmacy: { id: found.id, cif: normalizeCif(found.cif), nombre: found.nombre } };
+    }
+    catch (err) {
+        if (err instanceof ApiNetworkError)
+            return { ok: false, result: networkErrorResult(err) };
+        throw err;
+    }
+}

package/dist/principal.d.ts

@@ -0,0 +1,30 @@
+import type { PharmadateClient } from './client.js';
+export type Role = 'partner' | 'pharmacy';
+export interface Principal {
+    role: Role;
+    partnerId?: number;
+    partnerName?: string;
+    pharmacyId?: number;
+    pharmacyName?: string;
+}
+/** La credencial no es valida (401) o la API no pudo confirmarla. */
+export declare class PrincipalError extends Error {
+    readonly kind: 'unauthorized' | 'unavailable';
+    constructor(message: string, kind: 'unauthorized' | 'unavailable');
+}
+export declare function detectPrincipal(client: PharmadateClient): Promise<Principal>;
+/** Hash estable de una credencial, para cachear y para limitar sin guardar la key. */
+export declare function credentialId(apiKey: string): string;
+/** Cache de roles con TTL. Acotada para que un barrido de keys no agote la memoria. */
+export declare class PrincipalCache {
+    private readonly ttlMs;
+    private readonly max;
+    private readonly ahora;
+    private readonly mapa;
+    constructor(ttlMs?: number, max?: number, ahora?: () => number);
+    get(id: string): Principal | undefined;
+    set(id: string, principal: Principal): void;
+    /** Devuelve el rol cacheado o lo detecta (y lo guarda). */
+    resolve(apiKey: string, client: PharmadateClient): Promise<Principal>;
+    get size(): number;
+}

package/dist/principal.js

@@ -0,0 +1,85 @@
+/**
+ * Deteccion del rol de una credencial.
+ *
+ * Se hace con `GET /api/v1/ping`:
+ *   - `partner != null`                   -> partner
+ *   - `partner == null && pharmacy != null` -> farmacia
+ *   - 401                                  -> credencial invalida (en remoto, el cliente relanza el OAuth)
+ *
+ * El rol se cachea 60 s por `sha256(key)`: solo `{rol, partner_id, pharmacy_id}`, nunca la key. La autorizacion real la
+ * hace la API en cada llamada, asi que una key revocada deja de servir aunque el rol siga en cache.
+ *
+ * @module principal
+ */
+import { createHash } from 'node:crypto';
+/** La credencial no es valida (401) o la API no pudo confirmarla. */
+export class PrincipalError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = 'PrincipalError';
+    }
+}
+export async function detectPrincipal(client) {
+    const res = await client.request({ method: 'GET', path: '/v1/ping' });
+    if (res.status === 401)
+        throw new PrincipalError('Credencial invalida, caducada o revocada.', 'unauthorized');
+    if (!res.ok)
+        throw new PrincipalError(`La API respondio ${res.status} al comprobar la credencial.`, 'unavailable');
+    const body = (res.body ?? {});
+    if (body.partner) {
+        return { role: 'partner', partnerId: body.partner.id, partnerName: body.partner.nombre };
+    }
+    if (body.pharmacy) {
+        return { role: 'pharmacy', pharmacyId: body.pharmacy.id, pharmacyName: body.pharmacy.nombre };
+    }
+    throw new PrincipalError('La API no devolvio ni partner ni farmacia para esta credencial.', 'unauthorized');
+}
+/** Hash estable de una credencial, para cachear y para limitar sin guardar la key. */
+export function credentialId(apiKey) {
+    return createHash('sha256').update(apiKey).digest('hex');
+}
+/** Cache de roles con TTL. Acotada para que un barrido de keys no agote la memoria. */
+export class PrincipalCache {
+    ttlMs;
+    max;
+    ahora;
+    mapa = new Map();
+    constructor(ttlMs = 60_000, max = 2_000, ahora = Date.now) {
+        this.ttlMs = ttlMs;
+        this.max = max;
+        this.ahora = ahora;
+    }
+    get(id) {
+        const e = this.mapa.get(id);
+        if (!e)
+            return undefined;
+        if (e.expira <= this.ahora()) {
+            this.mapa.delete(id);
+            return undefined;
+        }
+        return e.principal;
+    }
+    set(id, principal) {
+        if (this.mapa.size >= this.max) {
+            const primera = this.mapa.keys().next().value;
+            if (primera !== undefined)
+                this.mapa.delete(primera);
+        }
+        this.mapa.set(id, { principal, expira: this.ahora() + this.ttlMs });
+    }
+    /** Devuelve el rol cacheado o lo detecta (y lo guarda). */
+    async resolve(apiKey, client) {
+        const id = credentialId(apiKey);
+        const cacheado = this.get(id);
+        if (cacheado)
+            return cacheado;
+        const principal = await detectPrincipal(client);
+        this.set(id, principal);
+        return principal;
+    }
+    get size() {
+        return this.mapa.size;
+    }
+}

package/dist/prompts.d.ts

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

package/dist/prompts.js

@@ -0,0 +1,42 @@
+/**
+ * Prompts MCP: plantillas de las tareas habituales.
+ *
+ * @module prompts
+ */
+import { z } from 'zod';
+const user = (text) => ({ messages: [{ role: 'user', content: { type: 'text', text } }] });
+export function registerPrompts(server, role) {
+    server.registerPrompt('placeOrder', {
+        title: 'Hacer un pedido',
+        description: 'Guia el pedido completo: buscar productos, valorar, confirmar y crear.',
+        argsSchema: { productos: z.string().describe('Que se quiere pedir (nombres o CN con unidades).'), ...(role === 'partner' ? { farmacia: z.string().describe('Id o CIF de la farmacia.') } : {}) },
+    }, (args) => user(`Quiero hacer este pedido en Pharmadate: ${args['productos']}.` +
+        (role === 'partner' ? ` Farmacia: ${args['farmacia']}.` : '') +
+        '\n\nSigue este orden: 1) localiza cada producto con getCatalog (q) y confirma conmigo los CN y las unidades dudosas; ' +
+        '2) valora la cesta con createQuote y ensename el resumen (total, lineas no servibles, pedido minimo); ' +
+        '3) NO crees el pedido hasta que yo confirme explicitamente; ' +
+        '4) con mi confirmacion, createOrder con una external_ref nueva que inventes una sola vez; 5) resume el resultado (order_id, envios).'));
+    server.registerPrompt('orderStatus', {
+        title: 'Estado de un pedido',
+        description: 'Resume el estado de un pedido: envios, faltas y entrega.',
+        argsSchema: { pedido: z.string().describe('order_id o external_ref.'), ...(role === 'partner' ? { farmacia: z.string().describe('Id o CIF de la farmacia.') } : {}) },
+    }, (args) => user(`Dime el estado del pedido ${args['pedido']}` +
+        (role === 'partner' ? ` de la farmacia ${args['farmacia']}` : '') +
+        '. Si es una referencia, busca con listOrders (external_ref). Despues mira listOrderShipments y getOrderModification y resumeme: estado, que envios hay, que falta y la entrega estimada.'));
+    if (role !== 'partner')
+        return;
+    server.registerPrompt('onboardPharmacy', {
+        title: 'Dar de alta una farmacia',
+        description: 'Alta guiada de una farmacia nueva comprobando antes que no existe.',
+        argsSchema: { datos: z.string().describe('CIF, nombre, direccion, codigo postal, localidad, provincia y email de la farmacia.') },
+    }, (args) => user(`Quiero dar de alta esta farmacia: ${args['datos']}.\n\n1) Comprueba con listPharmacies (cif) que no existe ya, tambien entre las dadas de baja. ` +
+        '2) Si existe y esta de baja, ofrece reactivatePharmacy en vez de crearla. 3) Si falta algun dato obligatorio, preguntamelo. ' +
+        '4) ENSEÑAME los datos y espera mi confirmacion. 5) createPharmacy con reveal_api_key=true para que yo reciba la API key y la guarde.'));
+    server.registerPrompt('recoverPharmacyAccess', {
+        title: 'Recuperar el acceso de una farmacia',
+        description: 'Para una farmacia que ha perdido su API key o esta de baja.',
+        argsSchema: { farmacia: z.string().describe('Id o CIF de la farmacia.') },
+    }, (args) => user(`La farmacia ${args['farmacia']} ha perdido el acceso. Localizala con listPharmacies/getPharmacy. ` +
+        'Si esta de baja: explicamelo y, con mi confirmacion, reactivatePharmacy (key nueva). Si esta activa: avisame de que rotatePharmacyApiKey invalida la key actual en el acto y, con mi confirmacion, rotala. ' +
+        'En ambos casos usa reveal_api_key=true para que la key me llegue a mi.'));
+}

package/dist/resources.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resources MCP:
+ *   pharmadate://docs/integration-guide   guia corta de integracion
+ *   pharmadate://docs/errors              codigos de error y la accion siguiente
+ *   pharmadate://docs/openapi             el OpenAPI vigente (se descarga de /api-docs/openapi.yaml)
+ *   pharmadate://me                       quien eres para esta credencial
+ *
+ * @module resources
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { PharmadateClient } from './client.js';
+import type { Principal } from './principal.js';
+export declare const INTEGRATION_GUIDE = "# Guia de integracion (resumen)\n\nBase: https://www.pharmadatepedido.es/api/v1 . Autenticacion: `Authorization: Bearer <api key>`.\n\n## Credenciales\n- **Partner** (`pk_partner_...`): gestiona sus farmacias (/pharmacies) y opera en nombre de ellas con la cabecera `X-Pharmacy-Ref` (CIF).\n- **Farmacia** (`pk_live_...`): identifica a la farmacia por si sola; sirve para /catalog, /conditions, /quote y /orders.\n\n## Pedido\n1. GET /catalog?q=... -> productos (el precio es orientativo).\n2. POST /quote {items:[{cn,unidades}]} -> precio firme por linea, ofertas, envios, impuestos y pedido minimo. No crea nada.\n3. POST /orders {items, external_ref} -> pedido REAL. `external_ref` es la clave de idempotencia:\n   misma ref y misma cesta = 200 con el pedido existente; misma ref y otra cesta = 409 external_ref_conflict.\n4. GET /orders, /orders/{id}, /orders/{id}/shipments, /orders/{id}/modification -> seguimiento.\n\n## Pedido minimo\nLa parte que sirve Pharmadate tiene que llegar al minimo (150 EUR netos de momento). Si no, 422 below_minimum_order y no se crea nada.\n\n## Farmacias de un partner\nAlta (POST /pharmacies), edicion (PATCH), baja logica (DELETE, reversible), reactivacion (POST .../reactivate, key nueva) y rotacion de la API key (POST .../api-key).\nEl CIF es unico en toda la plataforma y no se puede cambiar.\n\n## Limites\nLa API admite 120 peticiones por minuto y credencial. Este MCP limita ademas a 30 escrituras/hora y 10 pedidos/hora por credencial, y 500 lineas por quote/pedido.\n";
+export declare const ERRORS_GUIDE = "# Errores de la API y que hacer\n\n| HTTP | error | Que hacer |\n|---|---|---|\n| 400 | invalid_request, invalid_item, invalid_cn, too_many_items | Corregir la peticion segun el mensaje |\n| 400 | missing_pharmacy_ref | (partner) indicar la farmacia |\n| 401 | unauthorized | Credencial invalida, revocada o rotada: reconectar con una key vigente |\n| 403 | pharmacy_inactive | La farmacia esta de baja: reactivatePharmacy |\n| 403 | forbidden | La credencial no puede hacer esto (p. ej. una key de farmacia en /pharmacies) |\n| 404 | not_found | No existe entre los datos de esta credencial |\n| 409 | external_ref_conflict | Misma ref, otra cesta: getOrder del order_id o usar otra ref nueva |\n| 409 | pharmacy_exists | CIF ya existente (con pharmacy_id: es vuestra; sin el: Conflicto, no es vuestra) |\n| 409 | pharmacy_active | Ya esta activa: rotatePharmacyApiKey si se necesita key nueva |\n| 409 | pharmacy_inactive | Edicion/rotacion de una farmacia de baja: reactivatePharmacy |\n| 409 | partner_pharmacy_id_exists, pharmacy_email_conflict | Ese dato ya lo usa otra farmacia |\n| 422 | below_minimum_order | No llega al minimo: ver order_minimum; no se creo nada |\n| 422 | no_orderable_lines | Ninguna linea es servible: revisar createQuote |\n| 429 | rate_limited | Esperar Retry-After |\n| 5xx | internal_error | Reintentar; si persiste, dar el request_id a Pharmadate |\n\nCada respuesta de la API lleva `X-Request-Id`; el MCP lo devuelve en `_meta.request_id`.\n";
+export declare function registerResources(server: McpServer, client: PharmadateClient, principal: Principal): void;

package/dist/resources.js

@@ -0,0 +1,58 @@
+import { apiOrigin } from './config.js';
+export const INTEGRATION_GUIDE = `# Guia de integracion (resumen)
+
+Base: https://www.pharmadatepedido.es/api/v1 . Autenticacion: \`Authorization: Bearer <api key>\`.
+
+## Credenciales
+- **Partner** (\`pk_partner_...\`): gestiona sus farmacias (/pharmacies) y opera en nombre de ellas con la cabecera \`X-Pharmacy-Ref\` (CIF).
+- **Farmacia** (\`pk_live_...\`): identifica a la farmacia por si sola; sirve para /catalog, /conditions, /quote y /orders.
+
+## Pedido
+1. GET /catalog?q=... -> productos (el precio es orientativo).
+2. POST /quote {items:[{cn,unidades}]} -> precio firme por linea, ofertas, envios, impuestos y pedido minimo. No crea nada.
+3. POST /orders {items, external_ref} -> pedido REAL. \`external_ref\` es la clave de idempotencia:
+   misma ref y misma cesta = 200 con el pedido existente; misma ref y otra cesta = 409 external_ref_conflict.
+4. GET /orders, /orders/{id}, /orders/{id}/shipments, /orders/{id}/modification -> seguimiento.
+
+## Pedido minimo
+La parte que sirve Pharmadate tiene que llegar al minimo (150 EUR netos de momento). Si no, 422 below_minimum_order y no se crea nada.
+
+## Farmacias de un partner
+Alta (POST /pharmacies), edicion (PATCH), baja logica (DELETE, reversible), reactivacion (POST .../reactivate, key nueva) y rotacion de la API key (POST .../api-key).
+El CIF es unico en toda la plataforma y no se puede cambiar.
+
+## Limites
+La API admite 120 peticiones por minuto y credencial. Este MCP limita ademas a 30 escrituras/hora y 10 pedidos/hora por credencial, y 500 lineas por quote/pedido.
+`;
+export const ERRORS_GUIDE = `# Errores de la API y que hacer
+
+| HTTP | error | Que hacer |
+|---|---|---|
+| 400 | invalid_request, invalid_item, invalid_cn, too_many_items | Corregir la peticion segun el mensaje |
+| 400 | missing_pharmacy_ref | (partner) indicar la farmacia |
+| 401 | unauthorized | Credencial invalida, revocada o rotada: reconectar con una key vigente |
+| 403 | pharmacy_inactive | La farmacia esta de baja: reactivatePharmacy |
+| 403 | forbidden | La credencial no puede hacer esto (p. ej. una key de farmacia en /pharmacies) |
+| 404 | not_found | No existe entre los datos de esta credencial |
+| 409 | external_ref_conflict | Misma ref, otra cesta: getOrder del order_id o usar otra ref nueva |
+| 409 | pharmacy_exists | CIF ya existente (con pharmacy_id: es vuestra; sin el: Conflicto, no es vuestra) |
+| 409 | pharmacy_active | Ya esta activa: rotatePharmacyApiKey si se necesita key nueva |
+| 409 | pharmacy_inactive | Edicion/rotacion de una farmacia de baja: reactivatePharmacy |
+| 409 | partner_pharmacy_id_exists, pharmacy_email_conflict | Ese dato ya lo usa otra farmacia |
+| 422 | below_minimum_order | No llega al minimo: ver order_minimum; no se creo nada |
+| 422 | no_orderable_lines | Ninguna linea es servible: revisar createQuote |
+| 429 | rate_limited | Esperar Retry-After |
+| 5xx | internal_error | Reintentar; si persiste, dar el request_id a Pharmadate |
+
+Cada respuesta de la API lleva \`X-Request-Id\`; el MCP lo devuelve en \`_meta.request_id\`.
+`;
+export function registerResources(server, client, principal) {
+    const texto = (uri, text, mimeType) => ({ contents: [{ uri, mimeType, text }] });
+    server.registerResource('integration-guide', 'pharmadate://docs/integration-guide', { title: 'Guia de integracion', description: 'Resumen del flujo catalogo -> quote -> pedido -> seguimiento.', mimeType: 'text/markdown' }, async (uri) => texto(uri.href, INTEGRATION_GUIDE, 'text/markdown'));
+    server.registerResource('errors', 'pharmadate://docs/errors', { title: 'Errores y accion siguiente', description: 'Codigos de error de la API y que hacer con cada uno.', mimeType: 'text/markdown' }, async (uri) => texto(uri.href, ERRORS_GUIDE, 'text/markdown'));
+    server.registerResource('openapi', 'pharmadate://docs/openapi', { title: 'OpenAPI de la API v1', description: 'Especificacion completa vigente (YAML), descargada del servidor.', mimeType: 'application/yaml' }, async (uri) => {
+        const yaml = await client.fetchPublicText(`${apiOrigin(client.baseUrl)}/api-docs/openapi.yaml`);
+        return texto(uri.href, yaml, 'application/yaml');
+    });
+    server.registerResource('me', 'pharmadate://me', { title: 'Quien soy', description: 'El rol y la entidad asociados a la credencial con la que estas conectado.', mimeType: 'application/json' }, async (uri) => texto(uri.href, JSON.stringify(principal, null, 2), 'application/json'));
+}

package/dist/results.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resultados de herramienta: exito, error y traduccion de los errores de la API a la accion siguiente.
+ *
+ * @module results
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ApiNetworkError, type ApiResponse } from './client.js';
+/** Maximo de caracteres que se devuelven al modelo en un resultado. */
+export declare const MAX_RESULT_CHARS = 120000;
+export interface ResultMeta {
+    request_id?: string | null;
+    http_status?: number;
+    [k: string]: unknown;
+}
+export declare function jsonText(valor: unknown): string;
+export declare function okResult(data: unknown, meta?: ResultMeta, extraBlocks?: CallToolResult['content']): CallToolResult;
+export declare function errResult(texto: string, meta?: ResultMeta): CallToolResult;
+export declare function networkErrorResult(err: ApiNetworkError): CallToolResult;
+export interface ErrorContext {
+    /** `id` de farmacia sobre la que se opera (si lo hay), para citarlo en las instrucciones. */
+    pharmacyId?: number | undefined;
+    externalRef?: string | undefined;
+}
+/**
+ * Traduce una respuesta de error de la API a un `isError` con la ACCION SIGUIENTE para el modelo.
+ * Siempre incluye el codigo y el mensaje originales de la API; `_meta.request_id` sale de `X-Request-Id`.
+ */
+export declare function apiErrorResult(res: ApiResponse, ctx?: ErrorContext): CallToolResult;
+/** `true` si el valor es un objeto con un `api_key` en claro. */
+export declare function hasApiKey(data: unknown): data is Record<string, unknown> & {
+    api_key: string;
+};
+/**
+ * Aplica la politica de keys reveladas.
+ *
+ *   - Sin `reveal`: se quita `api_key` y queda `api_key_prefix`, mas un aviso. NO hay bloque con la key.
+ *   - Con `reveal`: el bloque para el MODELO sigue enmascarado y la key completa va en un bloque aparte con
+ *     `annotations.audience: ["user"]` (el cliente decide si lo muestra solo a la persona).
+ *
+ * La key queda en el historial del chat si el cliente la envia de vuelta al modelo: las descripciones lo avisan.
+ */
+export declare function applyKeyPolicy(data: unknown, reveal: boolean, meta?: ResultMeta): CallToolResult;

package/dist/results.js

@@ -0,0 +1,121 @@
+import { scrubText } from './scrub.js';
+/** Maximo de caracteres que se devuelven al modelo en un resultado. */
+export const MAX_RESULT_CHARS = 120_000;
+function limitar(texto) {
+    if (texto.length <= MAX_RESULT_CHARS)
+        return texto;
+    return texto.slice(0, MAX_RESULT_CHARS) + '\n... [resultado truncado: usa filtros o paginacion para ver menos datos]';
+}
+export function jsonText(valor) {
+    return limitar(scrubText(JSON.stringify(valor, null, 2)));
+}
+export function okResult(data, meta, extraBlocks = []) {
+    const r = { content: [{ type: 'text', text: jsonText(data) }, ...extraBlocks] };
+    if (meta)
+        r._meta = meta;
+    return r;
+}
+export function errResult(texto, meta) {
+    const r = { isError: true, content: [{ type: 'text', text: limitar(scrubText(texto)) }] };
+    if (meta)
+        r._meta = meta;
+    return r;
+}
+export function networkErrorResult(err) {
+    return errResult(`${err.message} No se ha confirmado que la operacion se haya ejecutado. ` +
+        'Si era un pedido, NO lo repitas con otra external_ref: reintentalo con la MISMA external_ref (es idempotente) o consulta listOrders con external_ref.', { error_code: 'network_error', timed_out: err.timedOut });
+}
+/**
+ * Traduce una respuesta de error de la API a un `isError` con la ACCION SIGUIENTE para el modelo.
+ * Siempre incluye el codigo y el mensaje originales de la API; `_meta.request_id` sale de `X-Request-Id`.
+ */
+export function apiErrorResult(res, ctx = {}) {
+    const body = (res.body && typeof res.body === 'object' ? res.body : {});
+    const code = typeof body.error === 'string' ? body.error : `http_${res.status}`;
+    const apiMessage = typeof body.message === 'string' ? body.message : '';
+    const meta = { request_id: res.requestId, http_status: res.status, error_code: code };
+    const pid = body.pharmacy_id ?? ctx.pharmacyId;
+    let accion = '';
+    switch (true) {
+        case res.status === 401:
+            accion = 'La credencial no es valida o ha sido revocada o rotada. Pide al usuario que vuelva a conectar el MCP con una API key vigente.';
+            break;
+        case code === 'pharmacy_active' || body.next_action === 'rotatePharmacyApiKey':
+            accion = `La farmacia ya esta activa y no se ha tocado su API key. Si el usuario necesita una key nueva, llama a rotatePharmacyApiKey con id ${pid ?? '<id de la farmacia>'} (invalida la anterior en el acto).`;
+            break;
+        case code === 'pharmacy_exists' && pid !== undefined:
+            accion = body.active === false
+                ? `Esa farmacia ya existe entre las tuyas (id ${pid}) y esta DADA DE BAJA. Llama a reactivatePharmacy con id ${pid} para recuperarla (genera una API key nueva).`
+                : `Esa farmacia ya existe entre las tuyas (id ${pid}) y esta activa. Usa getPharmacy / updatePharmacy con id ${pid}; no la vuelvas a crear.`;
+            break;
+        case code === 'pharmacy_exists':
+            accion = 'Ese CIF ya existe en Pharmadate y no es de este partner (de otro partner o del canal web). La API no da mas detalles a proposito. Comprueba el CIF con el usuario.';
+            break;
+        case code === 'pharmacy_inactive':
+            accion = `La farmacia esta dada de baja. Llama a reactivatePharmacy con id ${pid ?? '<id de la farmacia>'} (genera una API key nueva) y vuelve a intentarlo.`;
+            break;
+        case code === 'external_ref_conflict':
+            accion = `Ya existe el pedido ${body.order_id ?? '?'} con la external_ref ${ctx.externalRef ?? ''} y una cesta DISTINTA. No se ha creado nada. Si es el mismo pedido, consulta getOrder con id ${body.order_id ?? '?'}; si es un pedido nuevo, usa OTRA external_ref (una sola vez) y confirmalo con el usuario.`;
+            break;
+        case code === 'below_minimum_order': {
+            const m = body.order_minimum;
+            accion = `El pedido no llega al minimo de Pharmadate${m ? ` (exigido ${m.required_eur} EUR, actual ${m.current_eur} EUR, faltan ${m.missing_eur} EUR)` : ''}. No se ha creado nada. Enseña la diferencia al usuario: que anada lineas o renuncie al pedido. La external_ref queda libre.`;
+            break;
+        }
+        case code === 'no_orderable_lines':
+            accion = 'Ninguna linea se puede servir, asi que no se ha creado el pedido. Revisa el detalle con createQuote (motivo por linea) y corrige la cesta.';
+            break;
+        case code === 'partner_pharmacy_id_exists' || code === 'pharmacy_email_conflict':
+            accion = 'Ese dato ya lo usa otra farmacia. Cambialo o localiza la existente con listPharmacies.';
+            break;
+        case code === 'cif_immutable':
+            accion = 'El CIF de una farmacia no se puede cambiar. Si el CIF es erroneo, da de baja la farmacia y crea otra.';
+            break;
+        case res.status === 404:
+            accion = 'No encontrado entre los datos de esta credencial.';
+            break;
+        case res.status === 429:
+            accion = `Limite de peticiones de la API. Espera ${res.retryAfter ?? 'unos segundos'} s antes de reintentar.`;
+            break;
+        case res.status >= 500:
+            accion = `Error interno de la API. Reintenta en un momento; si persiste, comunica el request_id ${res.requestId ?? ''} a Pharmadate.`;
+            break;
+        default:
+            accion = res.status === 403 ? 'La credencial no tiene permiso para esta operacion.' : 'Corrige la peticion segun el mensaje de la API.';
+    }
+    const detalle = JSON.stringify(res.body);
+    return errResult(`Error ${res.status} (${code})${apiMessage ? `: ${apiMessage}` : ''}\n${accion}\nDetalle de la API: ${detalle}${res.requestId ? `\nrequest_id: ${res.requestId}` : ''}`, meta);
+}
+/** `true` si el valor es un objeto con un `api_key` en claro. */
+export function hasApiKey(data) {
+    return !!data && typeof data === 'object' && typeof data['api_key'] === 'string';
+}
+/**
+ * Aplica la politica de keys reveladas.
+ *
+ *   - Sin `reveal`: se quita `api_key` y queda `api_key_prefix`, mas un aviso. NO hay bloque con la key.
+ *   - Con `reveal`: el bloque para el MODELO sigue enmascarado y la key completa va en un bloque aparte con
+ *     `annotations.audience: ["user"]` (el cliente decide si lo muestra solo a la persona).
+ *
+ * La key queda en el historial del chat si el cliente la envia de vuelta al modelo: las descripciones lo avisan.
+ */
+export function applyKeyPolicy(data, reveal, meta) {
+    if (!hasApiKey(data))
+        return okResult(data, meta);
+    const { api_key, ...resto } = data;
+    const nombre = typeof resto['nombre'] === 'string' ? resto['nombre'] : `id ${String(resto['id'] ?? '?')}`;
+    if (!reveal) {
+        return okResult({
+            ...resto,
+            api_key_hidden: true,
+            note: 'La API key completa NO se ha mostrado (reveal_api_key=false). Si la anterior ya no vale, repite con reveal_api_key=true: rotatePharmacyApiKey genera otra y invalida la actual.',
+        }, meta);
+    }
+    return okResult({ ...resto, api_key_hidden: true, note: 'La API key completa se entrega al usuario en un bloque aparte (audience: user).' }, meta, [
+        {
+            type: 'text',
+            text: `API key de la farmacia ${nombre}: ${api_key}\nGuardala ahora en un lugar seguro: no se vuelve a mostrar.`,
+            annotations: { audience: ['user'], priority: 1 },
+        },
+    ]);
+}

package/dist/scrub.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+/** Sustituye las credenciales de un texto por marcas inofensivas. */
+export declare function scrubText(texto: string): string;
+/** Un `Error` como objeto plano y redactado: sus campos no son enumerables y `Object.entries(err)` daba `{}` (se perdia el motivo). */
+export declare function scrubError(err: Error): {
+    name: string;
+    message: string;
+    stack?: string;
+};
+/** Igual que {@link scrubText} pero recorre objetos y listas. No muta el original. Los `Error` salen como `{name, message, stack}`. */
+export declare function scrubDeep<T>(valor: T, profundidad?: number): T;