@molpha/mcp 0.1.0

package/dist/src/config.js

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { getSdkExport } from "./sdk.js";
+const DEFAULT_SOLANA_RPC = "https://api.devnet.solana.com";
+const FALLBACK_GATEWAY_ENDPOINT = "https://dev-gateway.molpha.io";
+export function loadConfig(env = process.env) {
+    const sdkDefaultGateway = getSdkExport("DEFAULT_GATEWAY_ENDPOINT");
+    return {
+        gatewayEndpoints: parseCsv(resolveEnvString(env.GATEWAY_ENDPOINTS) ?? sdkDefaultGateway ?? FALLBACK_GATEWAY_ENDPOINT),
+        solanaRpc: resolveEnvString(env.SOLANA_RPC) ?? DEFAULT_SOLANA_RPC,
+        ownerKeypair: resolveEnvString(env.OWNER_KEYPAIR ?? env.AGENT_KEYPAIR),
+        evmNetworks: parseCsv(resolveEnvString(env.MOLPHA_EVM_NETWORKS) ?? "evm-sepolia"),
+        starknetNetworks: parseCsv(resolveEnvString(env.MOLPHA_STARKNET_NETWORKS) ?? "starknet-sepolia"),
+        guardrails: {
+            maxExecutesPerDay: parsePositiveInt(resolveEnvString(env.MOLPHA_MAX_EXECUTES_PER_DAY), 100),
+            dryRunDefault: (() => {
+                const dryRun = resolveEnvString(env.MOLPHA_DRY_RUN);
+                return dryRun === "1" || dryRun === "true";
+            })()
+        },
+        x402: {
+            maxPriceUsdcAtomic: parseUsdcAtomic(resolveEnvString(env.MOLPHA_X402_MAX_PRICE_USDC), 1000000n),
+            maxSpendPerDayUsdcAtomic: parseUsdcAtomic(resolveEnvString(env.MOLPHA_X402_MAX_SPEND_PER_DAY_USDC), 10000000n),
+            gatewayPda: resolveEnvString(env.MOLPHA_X402_GATEWAY_PDA)
+        }
+    };
+}
+export function loadOwnerKeypair(config) {
+    if (!config.ownerKeypair) {
+        throw new Error("OWNER_KEYPAIR is required for the Molpha MCP runtime (Model A owner key)");
+    }
+    return loadKeypair(config.ownerKeypair);
+}
+/** @deprecated Use loadOwnerKeypair — AGENT_KEYPAIR alias retained for compatibility. */
+export function loadAgentKeypair(config) {
+    return loadOwnerKeypair(config);
+}
+export function loadKeypair(pathOrJson) {
+    const raw = isInlineKeypair(pathOrJson) ? pathOrJson : readFileSync(resolvePath(pathOrJson), "utf8");
+    const secretKey = JSON.parse(raw);
+    if (!Array.isArray(secretKey) || secretKey.length !== 64) {
+        throw new Error("keypair must be a JSON array of 64 secret-key bytes");
+    }
+    return Uint8Array.from(secretKey);
+}
+function parseCsv(value) {
+    return value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+/** Parses a decimal USDC amount (e.g. "1.5") into base units (6 decimals). */
+function parseUsdcAtomic(value, fallback) {
+    if (!value?.trim()) {
+        return fallback;
+    }
+    const match = /^(\d+)(?:\.(\d{1,6}))?$/.exec(value.trim());
+    if (!match) {
+        throw new Error(`expected a decimal USDC amount, got "${value}"`);
+    }
+    const [, whole = "0", fraction = ""] = match;
+    return BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+}
+function parsePositiveInt(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`expected a positive integer, got "${value}"`);
+    }
+    return parsed;
+}
+const UNRESOLVED_MCP_USER_CONFIG = /^\$\{user_config\.[a-z0-9_]+\}$/i;
+/** Treats empty strings and unresolved MCP bundle `${user_config.*}` placeholders as unset. */
+export function resolveEnvString(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || UNRESOLVED_MCP_USER_CONFIG.test(trimmed)) {
+        return undefined;
+    }
+    return value;
+}
+export function resolvePath(path) {
+    if (path.startsWith("~/")) {
+        return resolve(homedir(), path.slice(2));
+    }
+    return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
+/** An OWNER_KEYPAIR value can be a file path or an inline JSON secret-key array. */
+export function isInlineKeypair(pathOrJson) {
+    return pathOrJson.trim().startsWith("[");
+}
+/** Formats a USDC atomic (6-decimal) amount as a decimal string, e.g. 1_500_000n -> "1.5". */
+export function formatUsdcAtomic(atomic) {
+    const whole = atomic / 1000000n;
+    const fraction = atomic % 1000000n;
+    return fraction === 0n ? whole.toString() : `${whole}.${fraction.toString().padStart(6, "0").replace(/0+$/, "")}`;
+}

package/dist/src/determinism.js

@@ -0,0 +1,31 @@
+/** Heuristic guard for API configs that may not converge across independent nodes. */
+const LIVE_DRIFTING_PATTERNS = [
+    /\/ticker\b/i,
+    /\/price\b/i,
+    /\/latest\b/i,
+    /\/stream\b/i,
+    /\/realtime\b/i,
+    /\/websocket\b/i,
+    /\/ws\b/i,
+    /\/live\b/i
+];
+export function checkApiConfigDeterminism(apiConfig) {
+    const warnings = [];
+    const url = typeof apiConfig.url === "string" ? apiConfig.url : "";
+    if (!url) {
+        return { ok: false, warnings: ["apiConfig.url is required"] };
+    }
+    for (const pattern of LIVE_DRIFTING_PATTERNS) {
+        if (pattern.test(url)) {
+            warnings.push(`URL "${url}" may return live-drifting data. Independent nodes must converge on a byte-identical value to co-sign. Prefer settled/finalized sources.`);
+        }
+    }
+    const method = typeof apiConfig.method === "string" ? apiConfig.method.toUpperCase() : "GET";
+    if (method !== "GET" && method !== "POST") {
+        warnings.push(`method "${method}" is unusual; prefer GET for public deterministic APIs`);
+    }
+    if (!apiConfig.responseParser) {
+        return { ok: false, warnings: [...warnings, "apiConfig.responseParser is required"] };
+    }
+    return { ok: warnings.length === 0, warnings };
+}

package/dist/src/env.js

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { config } from "dotenv";
+export function loadDotenv() {
+    const candidates = [process.env.MOLPHA_ENV_FILE, ".env"].filter((value) => Boolean(value && value.trim().length > 0));
+    for (const candidate of candidates) {
+        const path = resolve(process.cwd(), candidate);
+        if (existsSync(path)) {
+            config({ path, override: false });
+            return;
+        }
+    }
+}
+loadDotenv();

package/dist/src/errors.js

@@ -0,0 +1,104 @@
+/** Runs `run()`, capturing a failure as a normalized error instead of throwing. */
+export async function settle(label, run) {
+    try {
+        return { ok: true, value: await run() };
+    }
+    catch (error) {
+        return { ok: false, label, error: normalizeError(error) };
+    }
+}
+export function normalizeError(error) {
+    const status = getStatus(error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (status === 400) {
+        return withStatus("invalid_request", message, status);
+    }
+    if (status === 401) {
+        return {
+            ...withStatus("unauthorized", message, status),
+            remediation: "Ensure OWNER_KEYPAIR matches the job owner or an authorized request signer."
+        };
+    }
+    if (status === 402) {
+        const payload = getX402Payload(error);
+        return {
+            ...withStatus("payment_required", message, status),
+            remediation: "Fund the x402 escrow (see molpha_agent_status) and retry, or use payment: \"subscription\" with an active subscription.",
+            ...(payload !== undefined ? { details: payload } : {})
+        };
+    }
+    if (status === 503 || isTimeout(error)) {
+        return withStatus("round_timeout", message, status);
+    }
+    if (message.includes("OWNER_KEYPAIR") || message.includes("AGENT_KEYPAIR")) {
+        return {
+            code: "missing_config",
+            message,
+            remediation: "Set OWNER_KEYPAIR to the funded owner keypair JSON path in the MCP server env."
+        };
+    }
+    if (message.includes("must be a valid Solana address") ||
+        message.includes("Non-base58 character")) {
+        return {
+            code: "invalid_config",
+            message,
+            remediation: "Check PRIVY_WALLET_ADDRESS / TURNKEY_WALLET_ADDRESS (and optional MOLPHA_X402_GATEWAY_PDA) in your MCP env. Use a real Solana devnet pubkey — not placeholders like <base58-solana-address>."
+        };
+    }
+    if (message.includes("Subscription") || message.includes("subscription")) {
+        return {
+            code: "subscription_inactive",
+            message,
+            remediation: "Run the bootstrap CLI to subscribe, or use payment: \"x402\" for a self-funded round."
+        };
+    }
+    if (message.includes("cap reached")) {
+        return { code: "guardrail_exceeded", message };
+    }
+    if (message.includes('"jsonrpc"') && message.includes("Method not found")) {
+        return {
+            code: "invalid_config",
+            message,
+            remediation: "GATEWAY_ENDPOINTS is pointing at a Solana RPC URL, not a Molpha gateway. Set it to the Molpha gateway base URL (see README / npm run doctor) and keep SOLANA_RPC separate."
+        };
+    }
+    if (message.includes("/v1/agent/execute") && message.includes("page not found")) {
+        return {
+            code: "invalid_config",
+            message,
+            remediation: "This gateway host exposes /v1/nodes but not signing routes. Use https://dev-gateway.molpha.io (run npm run doctor to verify)."
+        };
+    }
+    if (message.includes("determinism") || message.includes("live-drifting")) {
+        return { code: "determinism_rejected", message };
+    }
+    return withStatus("internal_error", message, status);
+}
+function withStatus(code, message, status) {
+    return status === undefined ? { code, message } : { code, message, status };
+}
+function getStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const record = error;
+    const response = record.response;
+    const cause = record.cause;
+    const status = record.status ?? record.statusCode ?? response?.status ?? cause?.status;
+    return typeof status === "number" ? status : undefined;
+}
+function getX402Payload(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    return error.x402;
+}
+function isTimeout(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const record = error;
+    const code = typeof record.code === "string" ? record.code : undefined;
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    return code === "ETIMEDOUT" || code === "ECONNRESET" || message.includes("timeout");
+}

package/dist/src/feed.js

@@ -0,0 +1,53 @@
+/**
+ * Feed-account presentation helpers.
+ *
+ * Anchor encodes the on-chain `FeedValueKind` enum as a single-key variant
+ * object — `{ value: {} }` / `{ hash: {} }` — which reads like an empty stub in
+ * tool output. Flatten it to a string and say what it means.
+ */
+const VALUE_KIND_MEANING = {
+    value: "`value` holds the raw oracle payload (<= 32 bytes), stored verbatim on-chain.",
+    hash: "`value` holds a keccak digest of the payload; the preimage lives off-chain."
+};
+export function decodeFeedValueKind(feed) {
+    const raw = feed?.valueKind ?? feed?.value_kind;
+    if (typeof raw === "string") {
+        const lowered = raw.toLowerCase();
+        return lowered === "value" || lowered === "hash" ? lowered : null;
+    }
+    if (raw && typeof raw === "object") {
+        const key = Object.keys(raw)[0]?.toLowerCase();
+        return key === "value" || key === "hash" ? key : null;
+    }
+    return null;
+}
+/** Feed account with `valueKind` flattened to a string and explained. */
+export function presentFeed(feed) {
+    if (!feed) {
+        return null;
+    }
+    const kind = decodeFeedValueKind(feed);
+    if (!kind) {
+        return { ...feed };
+    }
+    return {
+        ...feed,
+        valueKind: kind,
+        valueKindMeaning: VALUE_KIND_MEANING[kind]
+    };
+}
+/**
+ * Molpha attests *which encoding* the stored bytes use (`FeedValueKind` is only
+ * `value | hash`) but not their scale: there is no decimals field on the Feed
+ * account or in the signed DataUpdate. Any scale a consumer applies comes from
+ * the off-chain apiConfig that produced the number, so report it as unsigned
+ * provenance — verbatim, never parsed into a decimals count we cannot attest.
+ */
+export function describeValueEncoding(valueTransform) {
+    return {
+        attested: false,
+        source: "apiConfig.valueTransform (off-chain; not part of the signed payload)",
+        valueTransform: valueTransform ?? null,
+        note: "Molpha does not attest scale/decimals on-chain — FeedValueKind is only value|hash. A verifier contract must be configured with this feed's scale out of band; do not infer it from the integer alone."
+    };
+}

package/dist/src/guardrails.js

@@ -0,0 +1,62 @@
+import { formatUsdcAtomic } from "./config.js";
+const executes = { day: "", count: 0 };
+const x402Spend = { day: "", spentAtomic: 0n };
+function todayKey() {
+    return new Date().toISOString().slice(0, 10);
+}
+function bump(counter, max, label) {
+    const day = todayKey();
+    if (counter.day !== day) {
+        counter.day = day;
+        counter.count = 0;
+    }
+    if (counter.count >= max) {
+        throw new Error(`${label} cap reached (${max} per day). Adjust MOLPHA_MAX_${label.toUpperCase().replace(/ /g, "_")}_PER_DAY or wait until tomorrow.`);
+    }
+    counter.count += 1;
+}
+/** Reset counters — exposed for tests. */
+export function resetGuardrailCounters() {
+    executes.day = "";
+    executes.count = 0;
+    x402Spend.day = "";
+    x402Spend.spentAtomic = 0n;
+}
+export function enforceExecuteCap(config) {
+    bump(executes, config.maxExecutesPerDay, "execute");
+}
+/** Checks a proposed round price against the per-round cap only. */
+export function checkX402PerRoundCap(priceAtomic, maxPriceUsdcAtomic) {
+    if (priceAtomic > maxPriceUsdcAtomic) {
+        throw new Error(`x402 per-round price cap reached: round price (${formatUsdcAtomic(priceAtomic)} USDC) exceeds MOLPHA_X402_MAX_PRICE_USDC (${formatUsdcAtomic(maxPriceUsdcAtomic)} USDC).`);
+    }
+}
+/** Checks a proposed wallet outflow against the daily spend cap only. */
+export function checkX402DailySpendCap(amountAtomic, maxSpendPerDayUsdcAtomic) {
+    const day = todayKey();
+    const spentToday = x402Spend.day === day ? x402Spend.spentAtomic : 0n;
+    if (spentToday + amountAtomic > maxSpendPerDayUsdcAtomic) {
+        throw new Error(`x402 daily spend cap reached (${formatUsdcAtomic(maxSpendPerDayUsdcAtomic)} USDC per day, ${formatUsdcAtomic(spentToday)} USDC already spent). Adjust MOLPHA_X402_MAX_SPEND_PER_DAY_USDC or wait until tomorrow.`);
+    }
+}
+/**
+ * Checks a proposed x402 round's price against the per-round and daily
+ * spend caps, without recording the spend (call {@link recordX402Spend}
+ * once the round actually settles/funds).
+ */
+export function checkX402SpendCap(priceAtomic, maxPriceUsdcAtomic, maxSpendPerDayUsdcAtomic) {
+    checkX402PerRoundCap(priceAtomic, maxPriceUsdcAtomic);
+    checkX402DailySpendCap(priceAtomic, maxSpendPerDayUsdcAtomic);
+}
+/** Records an actual x402 spend against the daily cap after funding succeeds. */
+export function recordX402Spend(priceAtomic) {
+    const day = todayKey();
+    if (x402Spend.day !== day) {
+        x402Spend.day = day;
+        x402Spend.spentAtomic = 0n;
+    }
+    x402Spend.spentAtomic += priceAtomic;
+}
+export function previewWrite(action, summary) {
+    return { dryRun: true, action, summary };
+}

package/dist/src/hex.js

@@ -0,0 +1,45 @@
+/**
+ * The gateway's REST surface (e.g. subscription round execute) expects a
+ * bare hex feedId with no `0x` prefix, but feedIds are handed back to callers
+ * (feed derivation output, on-chain reads) with the prefix attached. Passing a
+ * prefixed feedId straight through causes the gateway to 400 on that lookup.
+ *
+ * Normalize once at the tool boundary so callers can pass either form.
+ */
+export function normalizeFeedId(feedId) {
+    return feedId.startsWith("0x") || feedId.startsWith("0X") ? feedId.slice(2) : feedId;
+}
+/**
+ * The gateway emits fixed-width fields as minimal hex — a one-signer bitmap
+ * comes back as `"4"`, not 32 zero-padded bytes. Every consumer downstream is
+ * strict: the SDK's `toFixedHex`/`toFixedBytes` reject anything whose hex
+ * length is not exactly `bytes * 2` (`signersBitmap: expected 32 bytes, got
+ * 0.5`), and the Solana program reads the bitmap as a fixed 32-byte array
+ * indexed from the end (`bitmap[31 - (bit >> 3)]`).
+ *
+ * Both readings are big-endian, so left-zero-padding is the canonical widening.
+ * Do it at the server boundary — on everything emitted and everything ingested —
+ * rather than making callers memorize a width the server already knows.
+ */
+export function toCanonicalHex(value, bytes, label) {
+    const clean = stripQuotes(String(value))
+        .replace(/^0[xX]/, "")
+        .toLowerCase();
+    if (clean.length === 0) {
+        throw new Error(`${label}: expected ${bytes} bytes of hex, got an empty value`);
+    }
+    if (!/^[0-9a-f]+$/.test(clean)) {
+        throw new Error(`${label}: expected hex, got "${value}"`);
+    }
+    // Over-width is corruption (wrong field, wrong encoding), not a format nit.
+    if (clean.length > bytes * 2) {
+        throw new Error(`${label}: expected at most ${bytes} bytes (${bytes * 2} hex chars), got ${clean.length / 2}`);
+    }
+    return `0x${clean.padStart(bytes * 2, "0")}`;
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    const quoted = (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+        (trimmed.startsWith('"') && trimmed.endsWith('"'));
+    return quoted ? trimmed.slice(1, -1).trim() : trimmed;
+}

package/dist/src/mcp.js

@@ -0,0 +1,82 @@
+import { normalizeError } from "./errors.js";
+export function jsonResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: stringifyToolJson(value)
+            }
+        ]
+    };
+}
+export function errorResult(error) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: stringifyToolJson(normalizeError(error))
+            }
+        ]
+    };
+}
+export function toolHandler(handler) {
+    return async (args) => {
+        try {
+            return jsonResult(await handler(args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    };
+}
+export function stringifyToolJson(value) {
+    return JSON.stringify(toJsonSafe(value), null, 2) ?? "null";
+}
+function toJsonSafe(value, seen = new WeakSet()) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return bytesToHex(value);
+    }
+    if (isPublicKeyLike(value)) {
+        return value.toBase58();
+    }
+    if (isBnLike(value)) {
+        return value.toString(10);
+    }
+    if (seen.has(value)) {
+        return "[Circular]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const out = value.map((item) => toJsonSafe(item, seen));
+        seen.delete(value);
+        return out;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = toJsonSafe(item, seen);
+    }
+    seen.delete(value);
+    return out;
+}
+function isPublicKeyLike(value) {
+    return value.constructor.name === "PublicKey" && "toBase58" in value && typeof value.toBase58 === "function";
+}
+function isBnLike(value) {
+    return (value.constructor.name === "BN" &&
+        "toString" in value &&
+        typeof value.toString === "function" &&
+        "words" in value);
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/src/sdk.js

@@ -0,0 +1,12 @@
+import * as MolphaSdkModule from "@molpha-oracle/sdk";
+export const MolphaSdk = MolphaSdkModule;
+export function getSdkExport(name) {
+    return MolphaSdk[name];
+}
+export function requireSdkExport(name) {
+    const value = getSdkExport(name);
+    if (value === undefined || value === null) {
+        throw new Error(`@molpha-oracle/sdk does not export ${name}`);
+    }
+    return value;
+}

package/dist/src/server.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import "./env.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools/index.js";
+const server = new McpServer({
+    name: "molpha-mcp",
+    version: "0.1.0"
+});
+registerTools(server);
+try {
+    await server.connect(new StdioServerTransport());
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+}