@pharmadate/mcp 0.0.0-stage → 0.1.0

package/dist/limits.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Limites propios del MCP, por credencial (sha256 de la key). Se suman a los de la API (120 peticiones/min).
+ *
+ *   - 30 escrituras por hora (`createOrder`, `createPharmacy`, `updatePharmacy`, `deactivatePharmacy`,
+ *     `reactivatePharmacy`, `rotatePharmacyApiKey`)
+ *   - 10 `createOrder` por hora
+ *   - 500 lineas como maximo por quote/pedido (lo comprueba el esquema de la herramienta)
+ *
+ * Los contadores viven en memoria del proceso: un reinicio los pone a cero y, con varias instancias detras del
+ * balanceador, cada una tiene el suyo. Para lo que protegen (una conversacion desbocada o inyectada que lance
+ * escrituras sin freno) es suficiente. Una llamada rechazada no alarga la ventana.
+ *
+ * @module limits
+ */
+export declare const MAX_LINES = 500;
+export declare const DEFAULT_WRITES_PER_HOUR = 30;
+export declare const DEFAULT_ORDERS_PER_HOUR = 10;
+export type RateLimitResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+};
+/** Ventana deslizante por clave. */
+export declare class WriteRateLimiter {
+    readonly max: number;
+    private readonly windowMs;
+    private readonly now;
+    private readonly hits;
+    constructor(max: number, windowMs?: number, now?: () => number);
+    tryConsume(key: string): RateLimitResult;
+    /** Purga periodica de claves vencidas. El temporizador no mantiene vivo el proceso. */
+    startPurgeTimer(intervalMs?: number): () => void;
+    get size(): number;
+    private purge;
+}
+/** Los dos contadores de escritura. Una instancia por proceso (no por peticion). */
+export declare class McpLimits {
+    readonly writes: WriteRateLimiter;
+    readonly orders: WriteRateLimiter;
+    constructor(opts?: {
+        writesPerHour?: number;
+        ordersPerHour?: number;
+        now?: () => number;
+    });
+    /**
+     * Consume una escritura (y un pedido si `isOrder`). Devuelve el mensaje de rechazo, o `null` si puede seguir.
+     */
+    check(credentialId: string, isOrder: boolean): string | null;
+    startPurgeTimers(): () => void;
+}
+/** Limitador simple por IP para los endpoints sin autenticar (OAuth, 401). */
+export declare class IpRateLimiter {
+    readonly max: number;
+    private readonly windowMs;
+    private readonly now;
+    private readonly hits;
+    constructor(max: number, windowMs?: number, now?: () => number);
+    /** `true` si puede pasar. */
+    allow(ip: string): boolean;
+}

package/dist/limits.js

@@ -0,0 +1,122 @@
+/**
+ * Limites propios del MCP, por credencial (sha256 de la key). Se suman a los de la API (120 peticiones/min).
+ *
+ *   - 30 escrituras por hora (`createOrder`, `createPharmacy`, `updatePharmacy`, `deactivatePharmacy`,
+ *     `reactivatePharmacy`, `rotatePharmacyApiKey`)
+ *   - 10 `createOrder` por hora
+ *   - 500 lineas como maximo por quote/pedido (lo comprueba el esquema de la herramienta)
+ *
+ * Los contadores viven en memoria del proceso: un reinicio los pone a cero y, con varias instancias detras del
+ * balanceador, cada una tiene el suyo. Para lo que protegen (una conversacion desbocada o inyectada que lance
+ * escrituras sin freno) es suficiente. Una llamada rechazada no alarga la ventana.
+ *
+ * @module limits
+ */
+export const MAX_LINES = 500;
+export const DEFAULT_WRITES_PER_HOUR = 30;
+export const DEFAULT_ORDERS_PER_HOUR = 10;
+const HOUR_MS = 3_600_000;
+const PURGE_THRESHOLD = 5_000;
+/** Ventana deslizante por clave. */
+export class WriteRateLimiter {
+    max;
+    windowMs;
+    now;
+    hits = new Map();
+    constructor(max, windowMs = HOUR_MS, now = Date.now) {
+        this.max = max;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    tryConsume(key) {
+        const now = this.now();
+        if (this.hits.size > PURGE_THRESHOLD)
+            this.purge(now);
+        const recent = (this.hits.get(key) ?? []).filter((t) => now - t < this.windowMs);
+        if (recent.length >= this.max) {
+            this.hits.set(key, recent);
+            const retryAfterMs = recent[0] + this.windowMs - now;
+            return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil(retryAfterMs / 1000)) };
+        }
+        recent.push(now);
+        this.hits.set(key, recent);
+        return { allowed: true };
+    }
+    /** Purga periodica de claves vencidas. El temporizador no mantiene vivo el proceso. */
+    startPurgeTimer(intervalMs = 600_000) {
+        const timer = setInterval(() => this.purge(this.now()), intervalMs);
+        timer.unref();
+        return () => clearInterval(timer);
+    }
+    get size() {
+        return this.hits.size;
+    }
+    purge(now) {
+        for (const [k, ts] of this.hits) {
+            if (ts.every((t) => now - t >= this.windowMs))
+                this.hits.delete(k);
+        }
+    }
+}
+/** Los dos contadores de escritura. Una instancia por proceso (no por peticion). */
+export class McpLimits {
+    writes;
+    orders;
+    constructor(opts = {}) {
+        this.writes = new WriteRateLimiter(opts.writesPerHour ?? DEFAULT_WRITES_PER_HOUR, HOUR_MS, opts.now);
+        this.orders = new WriteRateLimiter(opts.ordersPerHour ?? DEFAULT_ORDERS_PER_HOUR, HOUR_MS, opts.now);
+    }
+    /**
+     * Consume una escritura (y un pedido si `isOrder`). Devuelve el mensaje de rechazo, o `null` si puede seguir.
+     */
+    check(credentialId, isOrder) {
+        if (isOrder) {
+            const o = this.orders.tryConsume(credentialId);
+            if (!o.allowed) {
+                return `Limite de pedidos alcanzado: como maximo ${this.orders.max} createOrder por hora y credencial. No se ha enviado nada. Reintenta en unos ${Math.ceil(o.retryAfterSeconds / 60)} minuto(s).`;
+            }
+        }
+        const w = this.writes.tryConsume(credentialId);
+        if (!w.allowed) {
+            return `Limite de escrituras alcanzado: como maximo ${this.writes.max} operaciones de escritura por hora y credencial. No se ha ejecutado nada. Reintenta en unos ${Math.ceil(w.retryAfterSeconds / 60)} minuto(s).`;
+        }
+        return null;
+    }
+    startPurgeTimers() {
+        const a = this.writes.startPurgeTimer();
+        const b = this.orders.startPurgeTimer();
+        return () => {
+            a();
+            b();
+        };
+    }
+}
+/** Limitador simple por IP para los endpoints sin autenticar (OAuth, 401). */
+export class IpRateLimiter {
+    max;
+    windowMs;
+    now;
+    hits = new Map();
+    constructor(max, windowMs = 60_000, now = Date.now) {
+        this.max = max;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    /** `true` si puede pasar. */
+    allow(ip) {
+        const now = this.now();
+        if (this.hits.size > PURGE_THRESHOLD) {
+            for (const [k, ts] of this.hits)
+                if (ts.every((t) => now - t >= this.windowMs))
+                    this.hits.delete(k);
+        }
+        const recent = (this.hits.get(ip) ?? []).filter((t) => now - t < this.windowMs);
+        if (recent.length >= this.max) {
+            this.hits.set(ip, recent);
+            return false;
+        }
+        recent.push(now);
+        this.hits.set(ip, recent);
+        return true;
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Logger estructurado (pino). Siempre a stderr: en stdio el stdout es el canal del protocolo y no se puede ensuciar.
+ * Todo lo que pasa por aqui se redacta con {@link scrubDeep}: una key o un token no llegan nunca al log.
+ *
+ * @module logger
+ */
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;

package/dist/logger.js

@@ -0,0 +1,30 @@
+/**
+ * Logger estructurado (pino). Siempre a stderr: en stdio el stdout es el canal del protocolo y no se puede ensuciar.
+ * Todo lo que pasa por aqui se redacta con {@link scrubDeep}: una key o un token no llegan nunca al log.
+ *
+ * @module logger
+ */
+import pino from 'pino';
+import { scrubDeep, scrubText } from './scrub.js';
+import { VERSION } from './version.js';
+const nivel = process.env['LOG_LEVEL'] ?? 'info';
+export const logger = pino({
+    level: nivel,
+    base: { service: 'pharmadate-mcp', version: VERSION },
+    redact: {
+        paths: ['authorization', 'req.headers.authorization', 'headers.authorization', '*.authorization', 'api_key', '*.api_key', 'access_token', 'refresh_token', '*.access_token', '*.refresh_token'],
+        censor: '[REDACTED]',
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    formatters: {
+        level: (label) => ({ level: label }),
+        log: (objeto) => scrubDeep(objeto),
+    },
+    hooks: {
+        logMethod(args, method) {
+            // El mensaje (primer string) tambien se redacta
+            const copia = args.map((a) => (typeof a === 'string' ? scrubText(a) : a));
+            return method.apply(this, copia);
+        },
+    },
+}, pino.destination({ dest: 2, sync: false }));

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'));
+}