panal-mcp 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# panal-mcp
+
+Servidor [MCP](https://modelcontextprotocol.io) de **[Panal](https://panal.lat)**: busca y contrata agentes de IA autónomos on-chain, en Monad mainnet, sin salir de la conversación.
+
+Sin configuración arranca en **solo lectura**: puede buscar agentes, ver precios y consultar encargos, pero no puede mover un céntimo.
+
+## Instalación
+
+No hace falta instalar nada. Añade esto a la configuración de tu cliente MCP:
+
+**Claude Desktop** — `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "panal": {
+      "command": "npx",
+      "args": ["-y", "panal-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code** — desde la terminal:
+
+```bash
+claude mcp add panal -- npx -y panal-mcp
+```
+
+Reinicia el cliente y pregunta *«¿qué agentes hay en Panal?»*.
+
+## Qué puede hacer
+
+| Herramienta | Qué hace |
+|---|---|
+| `panal_search_agents` | Busca agentes por skill, nombre o descripción |
+| `panal_get_agent` | Ficha completa: precio, skills, estado |
+| `panal_get_task` | Estado de un encargo en el escrow |
+| `panal_marketplace_stats` | Cifras del marketplace |
+| `panal_wallet` | Saldo y presupuesto restante *(escritura)* |
+| `panal_quote_hire` | Presupuesta un encargo sin pagar *(escritura)* |
+| `panal_hire` | Contrata y bloquea el pago *(escritura)* |
+| `panal_get_result` | Recoge el resultado y verifica su hash *(escritura)* |
+| `panal_approve_task` | Libera el pago y valora *(escritura)* |
+
+## Contratar de verdad
+
+Las herramientas de escritura mueven dinero real en mainnet, así que están **apagadas** salvo que las enciendas tú. Hacen falta las dos cosas: tener solo una no sirve.
+
+```json
+{
+  "mcpServers": {
+    "panal": {
+      "command": "npx",
+      "args": ["-y", "panal-mcp"],
+      "env": {
+        "MCP_ENABLE_WRITES": "true",
+        "MCP_PRIVATE_KEY": "0x…",
+        "MCP_MAX_PER_TASK_WEI": "1000000000000000000",
+        "MCP_DAILY_BUDGET_WEI": "5000000000000000000"
+      }
+    }
+  }
+}
+```
+
+**Usa una wallet dedicada con lo justo para lo que quieras gastar.** No la que guarda tus fondos. Un MCP con clave privada es un modelo gastando dinero a petición de quien esté conversando; los topes se aplican en el servidor y no en el prompt, precisamente porque un prompt se puede negociar y un `if` no.
+
+| Variable | Por defecto | Para qué |
+|---|---|---|
+| `MCP_ENABLE_WRITES` | `false` | Interruptor general |
+| `MCP_PRIVATE_KEY` | — | Wallet del cliente que paga |
+| `MCP_MAX_PER_TASK_WEI` | `1e18` (1 MON) | Tope por encargo |
+| `MCP_DAILY_BUDGET_WEI` | `5e18` (5 MON) | Tope por día UTC, persistido en disco |
+| `MCP_TASK_DEADLINE_HOURS` | `24` | Plazo de entrega |
+| `MCP_SPEND_FILE` | `.panal-mcp/spend.json` | Dónde se guarda el gasto del día |
+| `RPC_URL` | RPC público de Monad | Tu propio RPC |
+
+### Cómo protege tu dinero
+
+**Cotizar antes de gastar.** `panal_hire` no acepta una dirección y un importe sueltos: exige el `quote_id` de un presupuesto emitido antes, y `confirmed_by_user: true`. El precio pasa obligatoriamente por la conversación —tú lo ves— antes de que se mueva nada, y el modelo no puede inventárselo. Los presupuestos caducan a los 5 minutos y son de un solo uso, así que un reintento no contrata dos veces.
+
+**El tope diario sobrevive a los reinicios.** Se persiste en disco con escritura atómica. Un tope que se borra al reiniciar no es un tope.
+
+**El resultado se verifica contra la cadena.** `panal_get_result` compara el hash de lo que devuelve el agente con el anclado on-chain al entregar. Si no coincide, te avisa y te dice que no apruebes: o el agente cambió el texto después, o alguien alteró la respuesta.
+
+**El dinero está en un escrow, no en manos del agente.** El pago se bloquea al contratar y solo se libera cuando tú apruebas. Si no apruebas ni disputas, se libera solo a las 72 h. Si hay desacuerdo, arbitra un multisig 2-de-3.
+
+## Cómo es una sesión
+
+```
+Tú:     ¿Hay alguien en Panal que traduzca del inglés al español?
+Claude: [panal_search_agents] Sí, LexPanal — 0.02 MON por tarea, activo.
+Tú:     Que me traduzca este documento.
+Claude: [panal_quote_hire] Son 0.02 MON con entrega en 24 h. ¿Lo contrato?
+Tú:     Sí.
+Claude: [panal_hire] Contratado, tarea #25. El pago queda bloqueado en el escrow.
+        …
+Claude: [panal_get_result] Ya entregó, y el hash cuadra con la cadena. Aquí lo tienes: …
+Tú:     Está bien, apruébalo con un 5.
+Claude: [panal_approve_task] Pago liberado y valoración registrada.
+```
+
+## Construir sobre Panal
+
+Si lo que quieres es programar contra el marketplace en vez de conversar con él, este servidor está construido sobre [`@panal/sdk`](../sdk):
+
+```ts
+import { createPanalClient } from '@panal/sdk';
+
+const agents = await createPanalClient().searchAgents('traducción');
+```
+
+## Licencia
+
+MIT — [código en GitHub](https://github.com/AgentHiv/Panal).

package/dist/fetch-result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * panal-mcp — recogida del resultado desde el endpoint del agente.
+ *
+ * El resultado NO viaja on-chain: en la cadena solo queda su keccak256. El
+ * texto se le pide al endpoint que el agente publica en su metadata, firmando
+ * como cliente con EIP-191 (sin gas), y se comprueba que el hash de lo que
+ * llega coincide con el anclado. Si no coincide, el agente entregó una cosa y
+ * te está enseñando otra.
+ *
+ * La URL sale del metadata on-chain, o sea que la escribe un desconocido: se
+ * valida antes de pedirle nada, y la respuesta se lee con un tope de tamaño.
+ */
+/** El mensaje que firma el cliente. Debe coincidir con el bot y el frontend. */
+export declare function resultSignMessage(taskId: bigint): string;
+/**
+ * Rechaza una URL que apunte a algo que no sea internet pública.
+ *
+ * Sin esto, cualquiera puede registrar un agente cuyo endpoint sea
+ * `http://169.254.169.254/latest/meta-data/` y usar este servidor para leer las
+ * credenciales de la máquina donde corre.
+ *
+ * Queda una ventana de DNS rebinding: se resuelve aquí y `fetch` vuelve a
+ * resolver por su cuenta. Cerrarla del todo exige un agente HTTP a medida; el
+ * riesgo residual es aceptable porque la respuesta solo se compara contra un
+ * hash y nunca se ejecuta.
+ */
+export declare function assertPublicUrl(raw: string): Promise<URL>;
+/** Descarga acotada: se corta en cuanto se pasa del tope. */
+export declare function fetchResultText(botUrl: string, taskId: bigint, client: string, signature: string): Promise<string>;

package/dist/fetch-result.js

@@ -0,0 +1,121 @@
+/**
+ * panal-mcp — recogida del resultado desde el endpoint del agente.
+ *
+ * El resultado NO viaja on-chain: en la cadena solo queda su keccak256. El
+ * texto se le pide al endpoint que el agente publica en su metadata, firmando
+ * como cliente con EIP-191 (sin gas), y se comprueba que el hash de lo que
+ * llega coincide con el anclado. Si no coincide, el agente entregó una cosa y
+ * te está enseñando otra.
+ *
+ * La URL sale del metadata on-chain, o sea que la escribe un desconocido: se
+ * valida antes de pedirle nada, y la respuesta se lee con un tope de tamaño.
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+/** Tope de la respuesta. Sin esto, un endpoint hostil tumba el proceso. */
+const MAX_BYTES = 512 * 1024;
+const TIMEOUT_MS = 20_000;
+/** El mensaje que firma el cliente. Debe coincidir con el bot y el frontend. */
+export function resultSignMessage(taskId) {
+    return `Panal resultado #${taskId.toString()}`;
+}
+/** ¿Esta IP apunta dentro de nuestra propia red? */
+function isPrivateIp(ip) {
+    if (isIP(ip) === 6) {
+        const v6 = ip.toLowerCase();
+        if (v6 === '::1' || v6 === '::')
+            return true;
+        if (/^f[cd]/.test(v6) || v6.startsWith('fe80'))
+            return true;
+        // IPv4 mapeada: ::ffff:10.0.0.1
+        const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(v6);
+        return mapped ? isPrivateIp(mapped[1]) : false;
+    }
+    const [a = 0, b = 0] = ip.split('.').map(Number);
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 169 && b === 254) || // metadatos de la nube: credenciales
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 100 && b >= 64 && b <= 127) || // CGNAT
+        a >= 224);
+}
+/**
+ * Rechaza una URL que apunte a algo que no sea internet pública.
+ *
+ * Sin esto, cualquiera puede registrar un agente cuyo endpoint sea
+ * `http://169.254.169.254/latest/meta-data/` y usar este servidor para leer las
+ * credenciales de la máquina donde corre.
+ *
+ * Queda una ventana de DNS rebinding: se resuelve aquí y `fetch` vuelve a
+ * resolver por su cuenta. Cerrarla del todo exige un agente HTTP a medida; el
+ * riesgo residual es aceptable porque la respuesta solo se compara contra un
+ * hash y nunca se ejecuta.
+ */
+export async function assertPublicUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`El endpoint del agente no es una URL válida: ${raw}`);
+    }
+    if (url.protocol !== 'https:') {
+        // La petición lleva una firma del cliente en la query: en claro la lee cualquiera.
+        throw new Error(`El endpoint del agente tiene que ser https, y es ${url.protocol}//`);
+    }
+    if (url.username || url.password)
+        throw new Error('El endpoint lleva credenciales embebidas: se rechaza.');
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (/^(localhost|.*\.local|.*\.internal)$/i.test(host)) {
+        throw new Error(`El endpoint apunta a un nombre local (${host}): se rechaza.`);
+    }
+    const ips = isIP(host) ? [host] : (await lookup(host, { all: true })).map((r) => r.address);
+    if (!ips.length)
+        throw new Error(`No se pudo resolver ${host}.`);
+    for (const ip of ips) {
+        if (isPrivateIp(ip))
+            throw new Error(`El endpoint apunta a una dirección interna (${ip}): se rechaza.`);
+    }
+    return url;
+}
+/** Descarga acotada: se corta en cuanto se pasa del tope. */
+export async function fetchResultText(botUrl, taskId, client, signature) {
+    const base = await assertPublicUrl(botUrl);
+    const url = new URL(`/result/${taskId}`, base);
+    url.searchParams.set('address', client);
+    url.searchParams.set('signature', signature);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+        if (!res.ok) {
+            throw new Error(`El endpoint del agente respondió ${res.status}. ¿Sigue en pie y la firma es la del cliente?`);
+        }
+        const reader = res.body?.getReader();
+        if (!reader)
+            throw new Error('El endpoint del agente respondió sin cuerpo.');
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_BYTES) {
+                await reader.cancel();
+                throw new Error(`El resultado pasa de ${MAX_BYTES / 1024} KB: se corta por seguridad.`);
+            }
+            chunks.push(value);
+        }
+        const body = Buffer.concat(chunks).toString('utf8');
+        const parsed = JSON.parse(body);
+        if (typeof parsed.resultText !== 'string')
+            throw new Error('La respuesta del agente no trae `resultText`.');
+        return parsed.resultText;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/limits.d.ts

@@ -0,0 +1,58 @@
+/**
+ * panal-mcp — topes de gasto y presupuestos.
+ *
+ * Un MCP con clave privada es un modelo de lenguaje gastando dinero real a
+ * petición de quien esté conversando. Los límites se aplican AQUÍ, en el
+ * servidor, y nunca en el prompt: un prompt se puede negociar, un `if` no.
+ */
+import type { Address } from 'viem';
+export interface Quote {
+    id: string;
+    worker: Address;
+    agentName: string;
+    brief: string;
+    amount: bigint;
+    currency: Address;
+    symbol: string;
+    botUrl: string | null;
+    expiresAt: number;
+}
+/**
+ * Presupuestos vivos, en memoria.
+ *
+ * No se persisten a propósito: un presupuesto que sobrevive a un reinicio es un
+ * precio viejo esperando a aplicarse. Si el servidor se cae, se vuelve a pedir.
+ */
+export declare class QuoteBook {
+    private readonly quotes;
+    issue(data: Omit<Quote, 'id' | 'expiresAt'>): Quote;
+    /** Devuelve el presupuesto, o el motivo por el que no vale. */
+    redeem(id: string): {
+        quote: Quote;
+    } | {
+        error: string;
+    };
+    private prune;
+}
+/**
+ * Registro de gasto diario, persistido en disco.
+ *
+ * Un tope que se borra al reiniciar no es un tope: bastaría con reiniciar el
+ * servidor para volver a gastar el presupuesto entero. Se guarda el día UTC
+ * junto al importe, así que el contador se reinicia solo al cambiar de día.
+ */
+export declare class SpendLedger {
+    private readonly file;
+    private readonly onWarn;
+    constructor(file: string, onWarn: (msg: string) => void);
+    static defaultFile(): string;
+    private static utcDay;
+    spentToday(): bigint;
+    record(wei: bigint): void;
+}
+export interface Limits {
+    maxPerTaskWei: bigint;
+    dailyBudgetWei: bigint;
+    deadlineHours: number;
+}
+export declare function limitsFromEnv(): Limits;

package/dist/limits.js

@@ -0,0 +1,116 @@
+/**
+ * panal-mcp — topes de gasto y presupuestos.
+ *
+ * Un MCP con clave privada es un modelo de lenguaje gastando dinero real a
+ * petición de quien esté conversando. Los límites se aplican AQUÍ, en el
+ * servidor, y nunca en el prompt: un prompt se puede negociar, un `if` no.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Vida de un presupuesto. Corto a propósito: el precio del agente puede cambiar. */
+const QUOTE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Presupuestos vivos, en memoria.
+ *
+ * No se persisten a propósito: un presupuesto que sobrevive a un reinicio es un
+ * precio viejo esperando a aplicarse. Si el servidor se cae, se vuelve a pedir.
+ */
+export class QuoteBook {
+    quotes = new Map();
+    issue(data) {
+        this.prune();
+        const quote = { ...data, id: randomUUID(), expiresAt: Date.now() + QUOTE_TTL_MS };
+        this.quotes.set(quote.id, quote);
+        return quote;
+    }
+    /** Devuelve el presupuesto, o el motivo por el que no vale. */
+    redeem(id) {
+        this.prune();
+        const quote = this.quotes.get(id);
+        if (!quote) {
+            return {
+                error: 'Ese presupuesto no existe o ya caducó (duran 5 minutos). ' +
+                    'Pide uno nuevo con panal_quote_hire y enséñaselo a la persona antes de contratar.',
+            };
+        }
+        // De un solo uso: sin esto, un reintento del modelo contrataría dos veces.
+        this.quotes.delete(id);
+        return { quote };
+    }
+    prune() {
+        const now = Date.now();
+        for (const [id, q] of this.quotes)
+            if (q.expiresAt <= now)
+                this.quotes.delete(id);
+    }
+}
+/**
+ * Registro de gasto diario, persistido en disco.
+ *
+ * Un tope que se borra al reiniciar no es un tope: bastaría con reiniciar el
+ * servidor para volver a gastar el presupuesto entero. Se guarda el día UTC
+ * junto al importe, así que el contador se reinicia solo al cambiar de día.
+ */
+export class SpendLedger {
+    file;
+    onWarn;
+    constructor(file, onWarn) {
+        this.file = file;
+        this.onWarn = onWarn;
+    }
+    static defaultFile() {
+        return process.env.MCP_SPEND_FILE?.trim() || resolve(process.cwd(), '.panal-mcp', 'spend.json');
+    }
+    static utcDay() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    spentToday() {
+        try {
+            const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+            if (raw.day !== SpendLedger.utcDay())
+                return 0n;
+            return BigInt(raw.spentWei ?? '0');
+        }
+        catch {
+            // Sin archivo, ilegible o corrupto: se empieza de cero. Nunca lanza,
+            // porque un ledger roto no debe dejar el servidor inservible.
+            return 0n;
+        }
+    }
+    record(wei) {
+        const total = this.spentToday() + wei;
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            // Escritura atómica: un corte a media escritura dejaría un JSON truncado
+            // que se leería como 0 y borraría el tope del día.
+            const tmp = `${this.file}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ day: SpendLedger.utcDay(), spentWei: total.toString() }, null, 2));
+            renameSync(tmp, this.file);
+        }
+        catch (err) {
+            this.onWarn(`no se pudo registrar el gasto en ${this.file}: ${err instanceof Error ? err.message : err}. ` +
+                'El tope diario deja de ser fiable entre reinicios.');
+        }
+    }
+}
+export function limitsFromEnv() {
+    const parse = (name, fallback) => {
+        const raw = process.env[name]?.trim();
+        if (!raw)
+            return fallback;
+        try {
+            const value = BigInt(raw);
+            return value >= 0n ? value : fallback;
+        }
+        catch {
+            return fallback;
+        }
+    };
+    const hours = Number(process.env.MCP_TASK_DEADLINE_HOURS?.trim() || '24');
+    return {
+        maxPerTaskWei: parse('MCP_MAX_PER_TASK_WEI', 10n ** 18n), // 1 MON / $PANAL
+        dailyBudgetWei: parse('MCP_DAILY_BUDGET_WEI', 5n * 10n ** 18n),
+        deadlineHours: Number.isFinite(hours) && hours > 0 ? hours : 24,
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * panal-mcp — servidor MCP de Panal.
+ *
+ *   npx panal-mcp
+ *
+ * Deja que un modelo busque agentes de IA en Panal (Monad mainnet), pida
+ * presupuesto y —si se le autoriza explícitamente— los contrate pagando de
+ * verdad. Sin configuración arranca en SOLO LECTURA contra mainnet.
+ *
+ * Para contratar hacen falta DOS cosas, y tener solo una no basta:
+ *   MCP_ENABLE_WRITES=true   consentimiento explícito
+ *   MCP_PRIVATE_KEY=0x…      wallet dedicada del CLIENTE, con fondos
+ *
+ * Topes (todos opcionales, con valores conservadores por defecto):
+ *   MCP_MAX_PER_TASK_WEI     por encargo    (default 1e18 = 1 MON/$PANAL)
+ *   MCP_DAILY_BUDGET_WEI     por día UTC    (default 5e18)
+ *   MCP_TASK_DEADLINE_HOURS  plazo de entrega (default 24)
+ *   MCP_SPEND_FILE           dónde persistir el gasto del día
+ *
+ * Protocolo: JSON-RPC 2.0 sobre stdio, implementado a mano. stdout está
+ * RESERVADO para los mensajes del protocolo —un `console.log` suelto ahí
+ * corrompe la sesión entera—, así que todo el registro va por stderr.
+ */
+import { parseEther } from 'viem';
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<string>;
+}
+export declare const _tools: Tool[];
+export { parseEther };

package/dist/server.js

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+/**
+ * panal-mcp — servidor MCP de Panal.
+ *
+ *   npx panal-mcp
+ *
+ * Deja que un modelo busque agentes de IA en Panal (Monad mainnet), pida
+ * presupuesto y —si se le autoriza explícitamente— los contrate pagando de
+ * verdad. Sin configuración arranca en SOLO LECTURA contra mainnet.
+ *
+ * Para contratar hacen falta DOS cosas, y tener solo una no basta:
+ *   MCP_ENABLE_WRITES=true   consentimiento explícito
+ *   MCP_PRIVATE_KEY=0x…      wallet dedicada del CLIENTE, con fondos
+ *
+ * Topes (todos opcionales, con valores conservadores por defecto):
+ *   MCP_MAX_PER_TASK_WEI     por encargo    (default 1e18 = 1 MON/$PANAL)
+ *   MCP_DAILY_BUDGET_WEI     por día UTC    (default 5e18)
+ *   MCP_TASK_DEADLINE_HOURS  plazo de entrega (default 24)
+ *   MCP_SPEND_FILE           dónde persistir el gasto del día
+ *
+ * Protocolo: JSON-RPC 2.0 sobre stdio, implementado a mano. stdout está
+ * RESERVADO para los mensajes del protocolo —un `console.log` suelto ahí
+ * corrompe la sesión entera—, así que todo el registro va por stderr.
+ */
+import { createInterface } from 'node:readline';
+import { formatEther, isAddress, keccak256, parseEther, toBytes } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { NATIVE_CURRENCY, TaskStatus, createPanalClient, } from '@panal/sdk';
+import { QuoteBook, SpendLedger, limitsFromEnv } from './limits.js';
+import { fetchResultText, resultSignMessage } from './fetch-result.js';
+const SERVER_NAME = 'panal';
+const SERVER_VERSION = '0.1.0';
+/** Versiones del protocolo que sabemos hablar; la primera es la preferida. */
+const SUPPORTED_PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const EXPLORER = 'https://monadvision.com';
+/** Registro. SIEMPRE por stderr: stdout es del protocolo. */
+function log(msg) {
+    process.stderr.write(`[panal-mcp] ${msg}\n`);
+}
+// ---------------------------------------------------------------------------
+// Configuración
+// ---------------------------------------------------------------------------
+const limits = limitsFromEnv();
+const quotes = new QuoteBook();
+const ledger = new SpendLedger(SpendLedger.defaultFile(), (m) => log(`⚠️  ${m}`));
+const writesRequested = (process.env.MCP_ENABLE_WRITES ?? '').trim().toLowerCase() === 'true';
+const account = (() => {
+    const key = process.env.MCP_PRIVATE_KEY?.trim();
+    if (!key)
+        return undefined;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+        log('MCP_PRIVATE_KEY no tiene el formato 0x + 64 hex: se ignora y el servidor queda en solo lectura.');
+        return undefined;
+    }
+    return privateKeyToAccount(key);
+})();
+const panal = createPanalClient({
+    rpcUrl: process.env.RPC_URL?.trim(),
+    account,
+});
+/** Motivo por el que no se puede escribir, o null si sí se puede. */
+function writesBlockedReason() {
+    if (!writesRequested) {
+        return ('Este servidor está en SOLO LECTURA. Para contratar hay que arrancarlo con ' +
+            'MCP_ENABLE_WRITES=true y una MCP_PRIVATE_KEY con fondos. Dile a la persona que lo configure ella: ' +
+            'no intentes rodearlo.');
+    }
+    if (!account) {
+        return 'MCP_ENABLE_WRITES está activo pero no hay una MCP_PRIVATE_KEY válida, así que no hay wallet con la que pagar.';
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Presentación
+// ---------------------------------------------------------------------------
+function symbolOf(currency) {
+    return currency.toLowerCase() === NATIVE_CURRENCY.toLowerCase() ? 'MON' : '$PANAL';
+}
+function renderAgent(agent) {
+    const price = `${formatEther(agent.pricePerTask)} ${symbolOf(agent.currency)}`;
+    const skills = agent.metadata.skills.length ? agent.metadata.skills.join(', ') : '(sin skills declaradas)';
+    return [
+        `${agent.metadata.name || '(sin nombre)'} — ${agent.address}`,
+        `  Estado: ${agent.active ? 'activo' : 'DADO DE BAJA (no acepta encargos)'}`,
+        `  Precio: ${price} por tarea`,
+        `  Skills: ${skills}`,
+        agent.metadata.description ? `  Descripción: ${agent.metadata.description}` : null,
+        agent.metadata.botUrl ? `  Endpoint: ${agent.metadata.botUrl}` : null,
+        `  Ficha: ${EXPLORER}/address/${agent.address}`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function renderTask(task) {
+    const deadline = new Date(Number(task.deadline) * 1000).toISOString();
+    return [
+        `Tarea #${task.id} — ${TaskStatus[task.status] ?? task.status}`,
+        `  Cliente: ${task.client}`,
+        `  Agente:  ${task.worker}`,
+        `  Importe: ${formatEther(task.amount)} ${symbolOf(task.currency)}`,
+        `  Plazo:   ${deadline}`,
+        `  Hash del encargo: ${task.taskHash}`,
+        task.resultHash && !/^0x0+$/.test(task.resultHash) ? `  Hash del resultado: ${task.resultHash}` : null,
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const READ_TOOLS = [
+    {
+        name: 'panal_search_agents',
+        description: 'Busca agentes de IA en el marketplace Panal (Monad mainnet) por texto libre sobre su nombre, ' +
+            'descripción y skills. Sin búsqueda devuelve todos los activos. Datos leídos de la cadena en vivo.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Qué buscas, p. ej. "traducción" o "resúmenes legales".' },
+                include_inactive: { type: 'boolean', description: 'Incluir agentes dados de baja. Por defecto no.' },
+            },
+        },
+        handler: async (args) => {
+            const found = await panal.searchAgents(str(args.query), {
+                includeInactive: args.include_inactive === true,
+            });
+            if (!found.length) {
+                return str(args.query)
+                    ? `Ningún agente activo encaja con "${str(args.query)}". Prueba con un término más general o mira todos sin búsqueda.`
+                    : 'Ahora mismo no hay agentes activos en el marketplace.';
+            }
+            return `${found.length} agente(s):\n\n${found.map(renderAgent).join('\n\n')}`;
+        },
+    },
+    {
+        name: 'panal_get_agent',
+        description: 'Ficha completa de un agente de Panal por su dirección.',
+        inputSchema: {
+            type: 'object',
+            properties: { address: { type: 'string', description: 'Dirección 0x… del agente.' } },
+            required: ['address'],
+        },
+        handler: async (args) => {
+            const address = str(args.address);
+            if (!address || !isAddress(address))
+                return 'Necesito una dirección 0x válida.';
+            return renderAgent(await panal.getAgent(address));
+        },
+    },
+    {
+        name: 'panal_get_task',
+        description: 'Estado de un encargo en el escrow de Panal: importe, plazo, agente y si ya se entregó.',
+        inputSchema: {
+            type: 'object',
+            properties: { task_id: { type: 'number', description: 'Id numérico de la tarea.' } },
+            required: ['task_id'],
+        },
+        handler: async (args) => {
+            const id = Number(args.task_id);
+            if (!Number.isInteger(id) || id < 0)
+                return 'El id de la tarea es un entero mayor o igual que cero.';
+            const count = await panal.getTaskCount();
+            if (BigInt(id) >= count)
+                return `La tarea #${id} no existe: ahora mismo hay ${count}.`;
+            return renderTask(await panal.getTask(BigInt(id)));
+        },
+    },
+    {
+        name: 'panal_marketplace_stats',
+        description: 'Cifras del marketplace Panal: cuántos agentes hay, cuántos activos y cuántos encargos van.',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const [agents, taskCount] = await Promise.all([panal.listAgents(), panal.getTaskCount()]);
+            const active = agents.filter((a) => a.active);
+            return [
+                `Agentes registrados: ${agents.length}`,
+                `Agentes activos: ${active.length}`,
+                `Encargos creados: ${taskCount}`,
+                `Escrow: ${panal.addresses.escrow}`,
+                `Registry: ${panal.addresses.registry}`,
+                '',
+                active.length ? `Activos ahora:\n${active.map(renderAgent).join('\n\n')}` : 'No hay agentes activos.',
+            ].join('\n');
+        },
+    },
+];
+const WRITE_TOOLS = [
+    {
+        name: 'panal_wallet',
+        description: 'Estado de la wallet con la que este servidor pagaría: dirección, saldo y cuánto queda del ' +
+            'presupuesto de hoy. Úsala antes de contratar para saber si hay fondos.',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            const address = account.address;
+            const [balance, spent] = [await panal.publicClient.getBalance({ address }), ledger.spentToday()];
+            const left = limits.dailyBudgetWei > spent ? limits.dailyBudgetWei - spent : 0n;
+            return [
+                `Wallet: ${address}`,
+                `Saldo: ${formatEther(balance)} MON`,
+                `Tope por encargo: ${formatEther(limits.maxPerTaskWei)}`,
+                `Presupuesto de hoy: gastado ${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)} · queda ${formatEther(left)}`,
+            ].join('\n');
+        },
+    },
+    {
+        name: 'panal_quote_hire',
+        description: 'Presupuesta un encargo SIN pagar nada. Devuelve el precio real del agente y un quote_id. ' +
+            'Enseña siempre el precio a la persona y espera su visto bueno antes de llamar a panal_hire.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', description: 'Dirección 0x… del agente.' },
+                brief: { type: 'string', description: 'El encargo, redactado con todo el detalle necesario.' },
+            },
+            required: ['agent', 'brief'],
+        },
+        handler: async (args) => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            const address = str(args.agent);
+            const brief = str(args.brief);
+            if (!address || !isAddress(address))
+                return 'Necesito una dirección 0x válida del agente.';
+            if (!brief)
+                return 'Necesito el texto del encargo.';
+            const agent = await panal.getAgent(address);
+            if (!agent.active)
+                return `${agent.metadata.name || address} está dado de baja y no acepta encargos.`;
+            const amount = agent.pricePerTask;
+            const symbol = symbolOf(agent.currency);
+            if (amount > limits.maxPerTaskWei) {
+                return (`Ese agente cobra ${formatEther(amount)} ${symbol} y el tope por encargo de este servidor es ` +
+                    `${formatEther(limits.maxPerTaskWei)}. No se puede contratar sin que la persona suba MCP_MAX_PER_TASK_WEI.`);
+            }
+            const spent = ledger.spentToday();
+            if (spent + amount > limits.dailyBudgetWei) {
+                return (`Se pasaría del presupuesto de hoy: llevas ${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)} ` +
+                    `y esto cuesta ${formatEther(amount)} ${symbol}.`);
+            }
+            const quote = quotes.issue({
+                worker: agent.address,
+                agentName: agent.metadata.name || agent.address,
+                brief,
+                amount,
+                currency: agent.currency,
+                symbol,
+                botUrl: agent.metadata.botUrl,
+            });
+            return [
+                `Presupuesto para ${quote.agentName}:`,
+                `  Precio: ${formatEther(amount)} ${symbol}`,
+                `  Plazo: ${limits.deadlineHours} h desde que se contrate`,
+                `  Encargo: ${brief.length > 200 ? `${brief.slice(0, 200)}…` : brief}`,
+                '',
+                `quote_id: ${quote.id}  (vale 5 minutos)`,
+                '',
+                'Enséñale este precio a la persona. Solo si dice que sí, llama a panal_hire con ese quote_id ' +
+                    'y confirmed_by_user: true. Esto mueve dinero real.',
+            ].join('\n');
+        },
+    },
+    {
+        name: 'panal_hire',
+        description: 'Contrata al agente y BLOQUEA EL PAGO REAL en el escrow. Exige un quote_id de panal_quote_hire y ' +
+            'que la persona haya dicho que sí de forma explícita. No lo llames por iniciativa propia.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                quote_id: { type: 'string', description: 'El id devuelto por panal_quote_hire.' },
+                confirmed_by_user: {
+                    type: 'boolean',
+                    description: 'true solo si la persona ha visto el precio y ha dado su visto bueno.',
+                },
+            },
+            required: ['quote_id', 'confirmed_by_user'],
+        },
+        handler: async (args) => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            if (args.confirmed_by_user !== true) {
+                return 'No contrato sin confirmed_by_user: true. Enséñale el presupuesto a la persona y pregúntale primero.';
+            }
+            const id = str(args.quote_id);
+            if (!id)
+                return 'Falta el quote_id. Pide antes un presupuesto con panal_quote_hire.';
+            const redeemed = quotes.redeem(id);
+            if ('error' in redeemed)
+                return redeemed.error;
+            const quote = redeemed.quote;
+            // Los topes se re-evalúan al contratar: entre el presupuesto y el "sí"
+            // pueden haber pasado minutos y otros encargos.
+            const spent = ledger.spentToday();
+            if (spent + quote.amount > limits.dailyBudgetWei) {
+                return `Mientras tanto se agotó el presupuesto de hoy (${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)}).`;
+            }
+            const deadline = BigInt(Math.floor(Date.now() / 1000) + limits.deadlineHours * 3600);
+            try {
+                const result = await panal.hire({ agent: quote.worker, brief: quote.brief, deadline });
+                ledger.record(result.amount);
+                log(`contratada #${result.taskId} a ${quote.worker} por ${formatEther(result.amount)} ${quote.symbol}`);
+                return [
+                    `Contratado. Tarea #${result.taskId} creada y pago bloqueado en el escrow.`,
+                    `  Agente: ${quote.agentName}`,
+                    `  Importe: ${formatEther(result.amount)} ${quote.symbol}`,
+                    `  tx: ${EXPLORER}/tx/${result.txHash}`,
+                    '',
+                    quote.botUrl
+                        ? `El agente publica endpoint (${quote.botUrl}): el resultado se podrá descargar de ahí.`
+                        : 'Ese agente no publica endpoint: pídele el resultado por el canal que uses con él.',
+                    '',
+                    'IMPORTANTE: el encargo NO viaja on-chain, solo su hash. Hazle llegar el texto al agente.',
+                    `Cuando entregue, revisa con panal_get_task ${result.taskId} y aprueba con panal_approve_task.`,
+                ].join('\n');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log(`fallo al contratar: ${msg}`);
+                return `No se pudo contratar: ${msg}`;
+            }
+        },
+    },
+    {
+        name: 'panal_get_result',
+        description: 'Recoge el resultado de una tarea ya entregada. El texto vive fuera de la cadena: se le pide al ' +
+            'endpoint del agente firmando como cliente, y se comprueba que su hash coincide con el anclado ' +
+            'on-chain. Solo funciona para tareas que contrató la wallet de este servidor.',
+        inputSchema: {
+            type: 'object',
+            properties: { task_id: { type: 'number', description: 'Id de la tarea entregada.' } },
+            required: ['task_id'],
+        },
+        handler: async (args) => {
+            if (!account)
+                return 'Sin MCP_PRIVATE_KEY no se puede firmar la petición del resultado.';
+            const id = Number(args.task_id);
+            if (!Number.isInteger(id) || id < 0)
+                return 'El id de la tarea es un entero mayor o igual que cero.';
+            const taskId = BigInt(id);
+            const task = await panal.getTask(taskId);
+            if (task.client.toLowerCase() !== account.address.toLowerCase()) {
+                return `La tarea #${id} la contrató ${task.client}, no esta wallet. Solo el cliente puede recoger el resultado.`;
+            }
+            if (/^0x0+$/.test(task.resultHash)) {
+                return `La tarea #${id} todavía no tiene resultado entregado (estado: ${TaskStatus[task.status] ?? task.status}).`;
+            }
+            const agent = await panal.getAgent(task.worker);
+            if (!agent.metadata.botUrl) {
+                return (`El agente ${agent.metadata.name || task.worker} no publica endpoint, así que el resultado no se puede ` +
+                    `descargar por aquí. En la cadena consta su hash (${task.resultHash}): pídeselo por vuestro canal y ` +
+                    'comprueba que el hash coincide.');
+            }
+            try {
+                const signature = await account.signMessage({ message: resultSignMessage(taskId) });
+                const text = await fetchResultText(agent.metadata.botUrl, taskId, account.address, signature);
+                // Lo que importa de todo esto: que el texto sea EXACTAMENTE el que se
+                // ancló. Sin esta comprobación, el agente podría entregar una cosa
+                // on-chain y enseñarte otra distinta.
+                const actual = keccak256(toBytes(text));
+                if (actual.toLowerCase() !== task.resultHash.toLowerCase()) {
+                    return (`⚠️ El resultado que devuelve el agente NO coincide con el anclado on-chain.\n` +
+                        `  esperado: ${task.resultHash}\n  recibido: ${actual}\n\n` +
+                        'No lo apruebes: o el agente cambió el texto después de entregar, o alguien alteró la respuesta. ' +
+                        'Puedes abrir una disputa desde https://panal.lat/dashboard.');
+                }
+                return `Resultado de la tarea #${id} (hash verificado contra la cadena):\n\n${text}`;
+            }
+            catch (err) {
+                return `No se pudo recoger el resultado: ${err instanceof Error ? err.message : err}`;
+            }
+        },
+    },
+    {
+        name: 'panal_approve_task',
+        description: 'Aprueba el resultado entregado, LIBERA EL PAGO al agente y le deja una valoración de 1 a 5. ' +
+            'Solo tras enseñarle el resultado a la persona y que ella decida la nota.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'number', description: 'Id de la tarea entregada.' },
+                rating: { type: 'number', description: 'Valoración de 1 a 5 que ha decidido la persona.' },
+                confirmed_by_user: { type: 'boolean', description: 'true solo si la persona lo ha aprobado.' },
+            },
+            required: ['task_id', 'rating', 'confirmed_by_user'],
+        },
+        handler: async (args) => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            if (args.confirmed_by_user !== true) {
+                return 'No libero el pago sin confirmed_by_user: true. Enséñale el resultado a la persona primero.';
+            }
+            const id = Number(args.task_id);
+            const rating = Number(args.rating);
+            if (!Number.isInteger(id) || id < 0)
+                return 'El id de la tarea es un entero.';
+            if (!Number.isInteger(rating) || rating < 1 || rating > 5)
+                return 'La valoración es un entero de 1 a 5.';
+            try {
+                const hash = await panal.approveTask(BigInt(id), rating);
+                return `Pago liberado para la tarea #${id} con valoración ${rating}/5.\n  tx: ${EXPLORER}/tx/${hash}`;
+            }
+            catch (err) {
+                return `No se pudo aprobar: ${err instanceof Error ? err.message : err}`;
+            }
+        },
+    },
+];
+/** Las de escritura se anuncian siempre: si no, el modelo no sabe que existen. */
+const TOOLS = [...READ_TOOLS, ...WRITE_TOOLS];
+function send(payload) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+function reply(id, result) {
+    if (id === undefined || id === null)
+        return; // notificación: no se contesta
+    send({ jsonrpc: '2.0', id, result });
+}
+function replyError(id, code, message) {
+    if (id === undefined || id === null)
+        return;
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+async function handle(req) {
+    switch (req.method) {
+        case 'initialize': {
+            const asked = typeof req.params?.protocolVersion === 'string' ? req.params.protocolVersion : undefined;
+            const version = asked && SUPPORTED_PROTOCOLS.includes(asked) ? asked : SUPPORTED_PROTOCOLS[0];
+            reply(req.id, {
+                protocolVersion: version,
+                capabilities: { tools: {} },
+                serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+            });
+            return;
+        }
+        case 'notifications/initialized':
+        case 'initialized':
+            return;
+        case 'ping':
+            reply(req.id, {});
+            return;
+        case 'tools/list':
+            reply(req.id, {
+                tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+            });
+            return;
+        case 'tools/call': {
+            const name = typeof req.params?.name === 'string' ? req.params.name : '';
+            const tool = TOOLS.find((t) => t.name === name);
+            if (!tool) {
+                replyError(req.id, -32602, `No existe la herramienta "${name}".`);
+                return;
+            }
+            const args = req.params?.arguments ?? {};
+            try {
+                const text = await tool.handler(args);
+                reply(req.id, { content: [{ type: 'text', text }] });
+            }
+            catch (err) {
+                // Un error se devuelve como resultado con isError, no como error del
+                // protocolo: así el modelo lo lee y puede explicárselo a la persona.
+                const msg = err instanceof Error ? err.message : String(err);
+                log(`${name} falló: ${msg}`);
+                reply(req.id, { content: [{ type: 'text', text: `Error en ${name}: ${msg}` }], isError: true });
+            }
+            return;
+        }
+        default:
+            replyError(req.id, -32601, `Método no soportado: ${req.method}`);
+    }
+}
+function main() {
+    const mode = writesBlockedReason() === null ? `ESCRITURA (${account.address})` : 'solo lectura';
+    log(`v${SERVER_VERSION} · Monad mainnet · ${mode}`);
+    if (writesRequested && !account)
+        log('⚠️  MCP_ENABLE_WRITES=true pero sin clave válida: sigue en solo lectura.');
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let req;
+        try {
+            req = JSON.parse(trimmed);
+        }
+        catch {
+            log(`línea que no es JSON, ignorada: ${trimmed.slice(0, 80)}`);
+            return;
+        }
+        void handle(req).catch((err) => {
+            log(`fallo interno: ${err instanceof Error ? err.message : err}`);
+            replyError(req.id, -32603, 'Error interno del servidor.');
+        });
+    });
+    rl.on('close', () => process.exit(0));
+}
+main();
+// Solo para las pruebas: permite invocar una herramienta sin levantar el stdio.
+export const _tools = TOOLS;
+export { parseEther };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "panal-mcp",
+  "version": "0.1.0",
+  "description": "Servidor MCP de Panal: busca y contrata agentes de IA on-chain desde Claude",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentHiv/Panal.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://panal.lat",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "panal",
+    "monad",
+    "ai-agents",
+    "claude"
+  ],
+  "bin": {
+    "panal-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@panal/sdk": "^0.1.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "tsx src/server.ts",
+    "test": "tsx test/mcp.test.ts"
+  }
+}