@oracle-agent/oracle 0.1.0

package/bin/oracle-data-mcp.mjs

@@ -0,0 +1,603 @@
+#!/usr/bin/env node
+// Oracle data MCP — read-only multichain market/discovery plane.
+// Loaded by an Oracle/Hermes profile. Never expose signing or broadcast here.
+//
+// Every tool is a READ. No key, no signing, no broadcast. Routes to the Oracle
+// data server read plane (/data/call), which is unauthenticated on loopback.
+// This is the "scan all public APIs" surface: DeFiLlama protocol TVL, DexScreener
+// token/search, LI.FI + Uniswap quotes, multi-chain RPC balances/blocks.
+//
+// Mirrors the Oracle exec MCP stdio JSON-RPC shape.
+
+import process from "node:process";
+import { env } from "../src/oracle-env.mjs";
+
+const DATA_URL = (env("ORACLE_DATA_URL", "MAD_DESK_URL", "http://127.0.0.1:8787")).replace(/\/$/, "");
+
+const tools = [
+  {
+    name: "data_catalog",
+    description:
+      "List every read-plane provider the desk exposes (id, venue, chainIds, ops). Use this to discover what public APIs are available before calling data_call. Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "data_health",
+    description:
+      "Health of every read-plane provider (which public APIs are up / configured). Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "data_call",
+    description:
+      "Generic escape hatch: call any provider/op from the catalog. provider+op are required; args is a free-form object matching that op. Read-only. Use data_catalog first to see valid provider/op pairs.",
+    inputSchema: {
+      type: "object",
+      required: ["provider", "op"],
+      properties: {
+        provider: { type: "string", description: "provider id, e.g. defillama, dexscreener, lifi, evm-rpc" },
+        op: { type: "string", description: "op name for that provider, e.g. protocols, search, quote" },
+        args: { type: "object", description: "op arguments (free-form)" },
+      },
+    },
+  },
+  {
+    name: "llama_protocols",
+    description:
+      "DeFiLlama: full protocol list with TVL, chain(s), category, 1d/7d change. The primary cross-chain protocol scanner. Read-only. Large payload — filter client-side.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "llama_prices",
+    description:
+      "DeFiLlama current prices for coins keyed 'chain:address' or 'coingecko:id' (comma-joined or array). Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["coins"],
+      properties: {
+        coins: { type: "string", description: "comma-joined coin keys, e.g. 'ethereum:0x...,coingecko:bitcoin'" },
+      },
+    },
+  },
+  {
+    name: "dex_search",
+    description:
+      "DexScreener search across all chains by symbol/name/address. Returns matching pairs with price, liquidity, volume, chain. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["q"],
+      properties: { q: { type: "string", description: "query: symbol, name, or token address" } },
+    },
+  },
+  {
+    name: "dex_token",
+    description:
+      "DexScreener pairs for a specific token address (any chain). Price, liquidity, volume, pair addresses. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" } },
+    },
+  },
+  {
+    name: "lifi_quote",
+    description:
+      "LI.FI cross-chain / DEX aggregator quote (no key). Best route + expected out for a swap or bridge. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["fromChain", "toChain", "fromToken", "toToken", "fromAmount"],
+      properties: {
+        fromChain: { type: "number" },
+        toChain: { type: "number" },
+        fromToken: { type: "string" },
+        toToken: { type: "string" },
+        fromAmount: { type: "string", description: "raw integer amount (wei-scale)" },
+        fromAddress: { type: "string", description: "optional; defaults to operator wallet" },
+      },
+    },
+  },
+  {
+    name: "rpc_balance",
+    description:
+      "Native token balance of an address on a chain via public RPC. Read-only. Omit address to read the operator wallet.",
+    inputSchema: {
+      type: "object",
+      required: ["chainId"],
+      properties: {
+        chainId: { type: "number" },
+        address: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "rpc_block",
+    description: "Latest block number on a chain via public RPC. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["chainId"],
+      properties: { chainId: { type: "number" } },
+    },
+  },
+  {
+    name: "solana_balance",
+    description: "Solana mainnet SOL balance for a base58 public key. Read-only; no signing or broadcast.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" }, commitment: { type: "string" } },
+    },
+  },
+  {
+    name: "solana_token_accounts",
+    description: "Solana SPL token accounts for an owner, optionally filtered by mint. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["owner"],
+      properties: { owner: { type: "string" }, mint: { type: "string" }, commitment: { type: "string" } },
+    },
+  },
+  {
+    name: "solana_simulate",
+    description: "Simulate a base64 Solana transaction through RPC. Read-only; never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      required: ["transaction"],
+      properties: { transaction: { type: "string" }, sigVerify: { type: "boolean" }, replaceRecentBlockhash: { type: "boolean" } },
+    },
+  },
+  {
+    name: "jupiter_quote",
+    description: "Jupiter Solana Swap API quote with a hard <=100 bps slippage cap. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["inputMint", "outputMint", "amount"],
+      properties: { inputMint: { type: "string" }, outputMint: { type: "string" }, amount: { type: "string" }, slippageBps: { type: "number" } },
+    },
+  },
+  {
+    name: "jupiter_prepare",
+    description: "Prepare an unsigned Jupiter swap transaction for the user's Solana wallet to sign. No local signer, no broadcast.",
+    inputSchema: {
+      type: "object",
+      required: ["userPublicKey"],
+      properties: { userPublicKey: { type: "string" }, quoteResponse: { type: "object" }, inputMint: { type: "string" }, outputMint: { type: "string" }, amount: { type: "string" }, slippageBps: { type: "number" } },
+    },
+  },
+  {
+    name: "btc_health",
+    description: "Bitcoin L1 Esplora health + tip height (mempool.space by default). No Core RPC, no keys. Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "btc_fees",
+    description: "Recommended Bitcoin fee rates (sats/vB). Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "btc_balance",
+    description: "Bitcoin address balance in sats via Esplora. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string", description: "bc1…/1…/3… address" } },
+    },
+  },
+  {
+    name: "btc_utxos",
+    description: "UTXOs for a Bitcoin address via Esplora. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" } },
+    },
+  },
+  {
+    name: "btc_tx",
+    description: "Lookup a Bitcoin transaction by txid via Esplora. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["txid"],
+      properties: { txid: { type: "string" } },
+    },
+  },
+  {
+    name: "btc_meta_health",
+    description:
+      "Ordinals/runes indexer health. Reports whether BTC_META_API_URL / vendor API keys are configured. Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "btc_rune_balance",
+    description:
+      "Rune balances for a Bitcoin address (requires configured indexer + optional API key). Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" } },
+    },
+  },
+  {
+    name: "btc_inscriptions",
+    description:
+      "Inscriptions controlled by an address. REQUIRES a keyed indexer (ordinals.com has no address index). Returns unknownNotEmpty:true when unconfigured — that means UNKNOWN, never 'wallet holds none'. Protect these UTXOs from fee spends.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" }, limit: { type: "number" } },
+    },
+  },
+  {
+    name: "btc_inscription_info",
+    description:
+      "Inscription metadata by inscription id (content type/length, height, sat, fee). KEYLESS via ordinals.com recursive. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["inscriptionId"],
+      properties: {
+        inscriptionId: { type: "string", description: "<64-hex-txid>i<index>" },
+      },
+    },
+  },
+  {
+    name: "btc_inscription_children",
+    description:
+      "Child inscriptions of a parent (collections). KEYLESS via ordinals.com recursive. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["inscriptionId"],
+      properties: {
+        inscriptionId: { type: "string", description: "<64-hex-txid>i<index>" },
+        page: { type: "number" },
+      },
+    },
+  },
+  {
+    name: "btc_ord_block_info",
+    description:
+      "Ord node block info / indexer tip. KEYLESS. Use to confirm the ordinals indexer is at the same tip as Esplora before trusting metaprotocol reads.",
+    inputSchema: {
+      type: "object",
+      properties: { height: { type: "number", description: "omit for current tip" } },
+    },
+  },
+  {
+    name: "satflow_health",
+    description:
+      "Satflow marketplace health (primary BTC ordinals/runes market after Magic Eden BTC sunset). Needs SATFLOW_API_KEY. Read-only.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "satflow_floors",
+    description: "Satflow collection floor prices. type=ordinals|runes. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "ordinals or runes" },
+        ids: { type: "string", description: "optional comma-separated collection ids" },
+      },
+    },
+  },
+  {
+    name: "satflow_wallet",
+    description: "Satflow wallet contents (ordinals/runes) for an address. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" }, type: { type: "string" }, limit: { type: "number" } },
+    },
+  },
+  {
+    name: "satflow_item",
+    description: "Satflow item detail for an inscription id (listing + bids + meta). Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["inscriptionId"],
+      properties: { inscriptionId: { type: "string" } },
+    },
+  },
+  {
+    name: "satflow_floor_listings",
+    description: "Satflow floor listings for collection id(s). Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["collectionIds"],
+      properties: { collectionIds: { type: "string" }, limit: { type: "number" } },
+    },
+  },
+  {
+    name: "best_swap_route",
+    description:
+      "Compare swap routes across every available aggregator and rank by NET output " +
+      "(after gas and fees), not headline quote. Returns the winner plus all " +
+      "runners-up so the ranking can be checked rather than trusted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chainId: { type: "number", description: "EVM chain id, e.g. 8453 for Base" },
+        tokenIn: { type: "string", description: "sell token address" },
+        tokenOut: { type: "string", description: "buy token address" },
+        amountIn: { type: "string", description: "raw units of tokenIn (wei-scale)" },
+        taker: { type: "string", description: "address used for quoting only; nothing is signed" },
+        decimalsIn: { type: "number" },
+        decimalsOut: { type: "number" },
+      },
+      required: ["chainId", "tokenIn", "tokenOut", "amountIn"],
+    },
+  },
+  {
+    name: "best_bridge_route",
+    description:
+      "Compare cross-chain bridge routes and rank by NET output. Also reports each " +
+      "route's expected duration, which is NOT folded into the score -- a route that " +
+      "saves $2 but takes 30 minutes is a trade-off for the caller to make.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fromChainId: { type: "number" },
+        toChainId: { type: "number" },
+        tokenIn: { type: "string", description: "token on the origin chain" },
+        tokenOut: { type: "string", description: "token on the destination chain" },
+        amountIn: { type: "string", description: "raw units of tokenIn" },
+        taker: { type: "string", description: "address used for quoting only" },
+        decimalsOut: { type: "number" },
+      },
+      required: ["fromChainId", "toChainId", "tokenIn", "tokenOut", "amountIn"],
+    },
+  },
+  {
+    name: "prepare_best_route",
+    description:
+      "Compare routes, then build the SIGNABLE artifact for the winner. Returns an " +
+      "unsigned transaction (LI.FI/ParaSwap/0x) or EIP-712 typed data for an " +
+      "off-chain order (CoW) -- the artifactKind field says which, and they require " +
+      "different wallet actions. Re-quotes before preparing and reports drift " +
+      "against the comparison. Never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        chainId: { type: "number" },
+        tokenIn: { type: "string" },
+        tokenOut: { type: "string" },
+        amountIn: { type: "string", description: "raw units of tokenIn" },
+        taker: {
+          type: "string",
+          description:
+            "the REAL wallet that will sign. Placeholder/burn addresses are rejected: " +
+            "quoting is anonymous, preparing is not.",
+        },
+        decimalsIn: { type: "number" },
+        decimalsOut: { type: "number" },
+        source: {
+          type: "string",
+          description: "force a specific source instead of the winner (flagged in the result)",
+        },
+        driftToleranceBps: { type: "number", description: "default 100" },
+      },
+      required: ["chainId", "tokenIn", "tokenOut", "amountIn", "taker"],
+    },
+  },
+  {
+    name: "prepare_best_bridge_route",
+    description:
+      "Compare cross-chain bridge routes, then build the signable transaction " +
+      "sequence for the winner. Returns a LIST of unsigned transactions -- some " +
+      "routes need an approval and a deposit signed in order, and signing only the " +
+      "first leaves funds approved but not bridged. Reports the destination chain " +
+      "and expected credit time. Bridging is not atomic. Never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fromChainId: { type: "number" },
+        toChainId: { type: "number" },
+        tokenIn: { type: "string", description: "token on the origin chain" },
+        tokenOut: { type: "string", description: "token on the destination chain" },
+        amountIn: { type: "string", description: "raw units of tokenIn" },
+        taker: { type: "string", description: "the REAL wallet that will sign; placeholders rejected" },
+        source: { type: "string", description: "force a source instead of the winner" },
+        driftToleranceBps: { type: "number", description: "default 100" },
+      },
+      required: ["fromChainId", "toChainId", "tokenIn", "tokenOut", "amountIn", "taker"],
+    },
+  },
+];
+
+// Named tool -> { provider, op, argMap(args) }
+//
+// A default address for read tools (rpc_balance, lifi fromAddress) is read from env
+// and is entirely optional. When unset, those tools require an explicit address --
+// which is the correct default for a public tool: silently substituting SOMEONE'S
+// wallet would both leak whose it is and quote routes against the wrong balances.
+const DEFAULT_ADDRESS = String(
+  process.env.ORACLE_DEFAULT_ADDRESS || process.env.MAD_OPERATOR_ADDRESS || "",
+).trim();
+const ROUTES = {
+  llama_protocols: () => ({ provider: "defillama", op: "protocols", args: {} }),
+  llama_prices: (a) => ({ provider: "defillama", op: "prices", args: { coins: a.coins } }),
+  dex_search: (a) => ({ provider: "dexscreener", op: "search", args: { q: a.q } }),
+  dex_token: (a) => ({ provider: "dexscreener", op: "token", args: { address: a.address } }),
+  lifi_quote: (a) => ({
+    provider: "lifi",
+    op: "quote",
+    args: {
+      fromChain: a.fromChain,
+      toChain: a.toChain,
+      fromToken: a.fromToken,
+      toToken: a.toToken,
+      fromAmount: a.fromAmount,
+      fromAddress: a.fromAddress || DEFAULT_ADDRESS || undefined,
+    },
+  }),
+  rpc_balance: (a) => {
+    const addr = a.address || DEFAULT_ADDRESS;
+    if (!addr) throw new Error("address required (set ORACLE_DEFAULT_ADDRESS to supply a default)");
+    return { provider: "evm-rpc", op: "getBalance", args: { chainId: a.chainId, address: addr } };
+  },
+  rpc_block: (a) => ({ provider: "evm-rpc", op: "blockNumber", args: { chainId: a.chainId } }),
+  solana_balance: (a) => ({ provider: "solana-rpc", op: "getBalance", args: { address: a.address, commitment: a.commitment } }),
+  solana_token_accounts: (a) => ({ provider: "solana-rpc", op: "tokenAccounts", args: { owner: a.owner, mint: a.mint, commitment: a.commitment } }),
+  solana_simulate: (a) => ({ provider: "solana-rpc", op: "simulate", args: { transaction: a.transaction, sigVerify: a.sigVerify, replaceRecentBlockhash: a.replaceRecentBlockhash } }),
+  jupiter_quote: (a) => ({ provider: "jupiter", op: "quote", args: { inputMint: a.inputMint, outputMint: a.outputMint, amount: a.amount, slippageBps: a.slippageBps } }),
+  jupiter_prepare: (a) => ({ provider: "jupiter", op: "prepare", args: { userPublicKey: a.userPublicKey, quoteResponse: a.quoteResponse, inputMint: a.inputMint, outputMint: a.outputMint, amount: a.amount, slippageBps: a.slippageBps } }),
+  btc_health: () => ({ provider: "bitcoin-esplora", op: "health", args: {} }),
+  btc_fees: () => ({ provider: "bitcoin-esplora", op: "fees", args: {} }),
+  btc_balance: (a) => ({ provider: "bitcoin-esplora", op: "address", args: { address: a.address } }),
+  btc_utxos: (a) => ({ provider: "bitcoin-esplora", op: "utxos", args: { address: a.address } }),
+  btc_tx: (a) => ({ provider: "bitcoin-esplora", op: "tx", args: { txid: a.txid } }),
+  btc_meta_health: () => ({ provider: "bitcoin-meta", op: "health", args: {} }),
+  btc_rune_balance: (a) => ({ provider: "bitcoin-meta", op: "runeBalances", args: { address: a.address } }),
+  btc_inscriptions: (a) => ({
+    provider: "bitcoin-meta",
+    op: "inscriptions",
+    args: { address: a.address, limit: a.limit },
+  }),
+  btc_inscription_info: (a) => ({
+    provider: "bitcoin-meta",
+    op: "inscriptionInfo",
+    args: { inscriptionId: a.inscriptionId },
+  }),
+  btc_inscription_children: (a) => ({
+    provider: "bitcoin-meta",
+    op: "inscriptionChildren",
+    args: { inscriptionId: a.inscriptionId, page: a.page },
+  }),
+  btc_ord_block_info: (a) => ({
+    provider: "bitcoin-meta",
+    op: "ordBlockInfo",
+    args: { height: a.height },
+  }),
+  satflow_health: () => ({ provider: "satflow", op: "health", args: {} }),
+  satflow_floors: (a) => ({
+    provider: "satflow",
+    op: "collectionFloors",
+    args: { type: a.type, ids: a.ids },
+  }),
+  satflow_wallet: (a) => ({
+    provider: "satflow",
+    op: "walletContents",
+    args: { address: a.address, type: a.type, limit: a.limit },
+  }),
+  satflow_item: (a) => ({
+    provider: "satflow",
+    op: "item",
+    args: { inscriptionId: a.inscriptionId || a.id },
+  }),
+  satflow_floor_listings: (a) => ({
+    provider: "satflow",
+    op: "floorListings",
+    args: { collectionIds: a.collectionIds || a.ids, limit: a.limit },
+  }),
+};
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function error(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function httpJson(url, { method = "GET", body } = {}) {
+  const res = await fetch(url, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return data;
+}
+
+async function deskCall(provider, op, args = {}) {
+  return httpJson(`${DATA_URL}/data/call`, {
+    method: "POST",
+    body: { provider, op, args },
+  });
+}
+
+async function callTool(name, args = {}) {
+  // Routing runs IN-PROCESS rather than through the desk HTTP server. The router
+  // fans out to several aggregators itself, so proxying it through /data/call would
+  // add a hop and a second timeout budget for no benefit -- and it means routing
+  // works without a desk server running at all.
+  if (name === "best_swap_route" || name === "best_bridge_route") {
+    const { bestSwapRoute, bestBridgeRoute } = await import("../src/router/index.mjs");
+    return name === "best_swap_route" ? bestSwapRoute(args) : bestBridgeRoute(args);
+  }
+  if (name === "prepare_best_route") {
+    const { prepareBestRoute } = await import("../src/router/prepare-route.mjs");
+    return prepareBestRoute(args);
+  }
+  if (name === "prepare_best_bridge_route") {
+    const { prepareBestBridgeRoute } = await import("../src/router/prepare-bridge.mjs");
+    return prepareBestBridgeRoute(args);
+  }
+  if (name === "data_catalog") return httpJson(`${DATA_URL}/data/catalog`);
+  if (name === "data_health") return httpJson(`${DATA_URL}/data/health`);
+  if (name === "data_call") {
+    if (!args.provider || !args.op) throw new Error("provider and op are required");
+    return deskCall(args.provider, args.op, args.args || {});
+  }
+  const route = ROUTES[name];
+  if (route) {
+    const { provider, op, args: mapped } = route(args);
+    return deskCall(provider, op, mapped);
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+async function handle(request) {
+  const { id, method, params } = request;
+  if (method === "initialize") {
+    send({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: params?.protocolVersion || "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "oracle-data-mcp", version: "0.1.0" },
+      },
+    });
+    return;
+  }
+  if (method === "notifications/initialized") return;
+  if (method === "tools/list") {
+    send({ jsonrpc: "2.0", id, result: { tools } });
+    return;
+  }
+  if (method === "tools/call") {
+    try {
+      const result = await callTool(params?.name, params?.arguments || {});
+      send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+    } catch (err) {
+      send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: err.message }] } });
+    }
+    return;
+  }
+  if (id !== undefined) error(id, -32601, `Method not found: ${method}`);
+}
+
+let buffer = "";
+
+function startStdioLoop() {
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      try {
+        void handle(JSON.parse(line));
+      } catch (err) {
+        error(null, -32700, err.message);
+      }
+    }
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  startStdioLoop();
+}
+
+export { tools, callTool, handle };