mpp32-mcp-server 1.2.4 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to `mpp32-mcp-server` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-05-15
+
+### Fixed
+
+* **Diagnostics tool referenced non-existent `query_intelligence`.** The
+  `get_mpp32_diagnostics` "Ready to pay" message told users to try
+  `query_intelligence`, which was never a tool name. Now correctly says
+  `get_solana_token_intelligence`.
+
+* **`protocol` filter missing from `list_mpp32_services`.** The tool
+  description and the backend both support filtering by payment protocol
+  (x402, tempo, acp, ap2, agtp), but the parameter was never wired
+  through. Added `protocol` as an optional enum parameter and forwarded
+  it to the backend query string.
+
+* **`server.json` version stuck at 1.2.2.** The MCP registry manifest
+  was never bumped past 1.2.2, causing the official registry listing to
+  advertise the wrong version. Updated to 1.3.1 with all new env vars.
+
+* **`server.json` missing `MPP32_PREFERRED_NETWORK` and `MPP32_TIMEOUT_MS`
+  environment variables.** Both were supported since 1.2.3 and 1.1.2
+  respectively but never declared in the registry manifest.
+
+### Added
+
+* **README now documents all M32-gated tools.** `get_m32_whale_tracker`,
+  `compare_tokens_m32`, and `scan_portfolio_m32` were live in the server
+  but missing from the README's tools section.
+
+* **README now documents `MPP32_SOLANA_RPC_URL` and `MPP32_TIMEOUT_MS`**
+  in the configuration table.
+
+## [1.3.0] - 2026-05-14
+
+### Added
+
+* **Economic Circuit Breakers — infrastructure-level spending guardrails.**
+  The first MCP payment server with built-in budget enforcement. No more
+  runaway agent bills.
+
+  - **`manage_agent_budget` tool** — new MCP tool to view, set, or reset
+    spending limits directly from Claude, Cursor, or any MCP client.
+    Supports three actions:
+    - `get`: View current budget status (remaining balance, hourly velocity,
+      circuit breaker state, per-service spending breakdown).
+    - `set`: Configure `budgetLimitUsd` (total session cap), `velocityLimitUsd`
+      (hourly max), and `alertThresholdPercent` (warning threshold).
+    - `reset`: Manually clear a tripped circuit breaker so the session can
+      resume spending.
+
+  - **Per-session budget limits** — set a maximum total spend in USD when
+    creating a session or at any time via the new `manage_agent_budget` tool.
+    When the limit is reached, the circuit breaker trips and all paid calls
+    are blocked until manually reset or the budget is increased.
+
+  - **Velocity (hourly) limits** — cap how fast an agent can spend. Prevents
+    infinite-loop scenarios where an agent drains a wallet in minutes.
+
+  - **Automatic circuit breaker** — trips instantly when budget or velocity
+    limits are exceeded. Sticky by design: agents cannot auto-resume spending.
+    Requires explicit reset via the MCP tool or API.
+
+  - **Budget status in every response** — all `call_mpp32_endpoint` and
+    `get_solana_token_intelligence` responses now include remaining budget,
+    utilization percentage, and circuit breaker state when limits are
+    configured.
+
+  - **Circuit breaker error handling** — when a circuit breaker is tripped,
+    the MCP server returns a clear, actionable message explaining what
+    happened and how to resume (via `manage_agent_budget`).
+
+### Changed
+
+* **`formatExecuteSuccess` now includes budget status.** When budget limits
+  are configured, successful responses include a one-line budget summary
+  (remaining balance and utilization %).
+
 ## [1.2.4] - 2026-05-11
 
 ### Fixed

package/README.md

@@ -35,6 +35,7 @@ MPP32 replaces all of that with one MCP server. Your agent asks for a service by
 * Run real time Solana token intelligence with alpha scoring, rug risk, whale flow, and 24 hour pump probability.
 * Track every call, every dollar settled, and every protocol used from a dashboard at mpp32.org.
 * Get an automatic 20 percent or 40 percent discount on native services for holding M32 once your wallet is verified.
+* Access M32-gated exclusive APIs: Whale Tracker (1M M32), Token Comparison (2.5M M32), and Portfolio Scanner (5M M32) — free for holders, unavailable to non-holders.
 
 ## Install
 
@@ -98,6 +99,8 @@ Tip: call the `get_mpp32_diagnostics` tool from inside Claude. It probes the API
 | `MPP32_SOLANA_PRIVATE_KEY` | Paid x402 calls on Solana | Base58 encoded Solana secret key. Used to sign USDC payments locally. Never leaves your machine. |
 | `MPP32_PRIVATE_KEY` | Paid x402 calls on Base | 0x prefixed EVM private key. Used to sign USDC payments on Base when a provider only accepts EVM. |
 | `MPP32_PREFERRED_NETWORK` | Optional override | When both keys are configured and the challenge advertises multiple networks, force one. Accepts `solana`, `base`, `evm`, or a full CAIP-2 string. |
+| `MPP32_SOLANA_RPC_URL` | Optional | Override the Solana RPC endpoint used to fetch recent blockhashes when building x402 transactions. Defaults to `https://api.mainnet-beta.solana.com`. Set this if you hit public rate limits. |
+| `MPP32_TIMEOUT_MS` | Optional | Request timeout in milliseconds for all outbound API calls. Range 1000 to 300000. Defaults to 30000 (30 seconds). |
 | `MPP32_API_URL` | Custom deployments | Override the API base URL. Defaults to `https://mpp32.org`. |
 
 Private keys stay on your machine. They sign payments locally and never travel to MPP32 servers. Provide either or both for paid calls. If both are present and a challenge advertises both networks, EVM is preferred unless `MPP32_PREFERRED_NETWORK` is set; if only one key is configured, that network wins automatically.
@@ -148,7 +151,55 @@ Real time analysis of any Solana token. Pulls live data from DexScreener, Jupite
 { "token": "BONK" }
 ```
 
-M32 holders will get tiered discounts (20 percent at 250k, 40 percent at 1M) once SIWS wallet signature verification ships. The discount path is gated off in production until then so it cannot be claimed by spoofing a wallet header.
+M32 holders get tiered discounts (20 percent at 250k, 40 percent at 1M) once SIWS wallet signature verification ships. The discount path is gated off in production until then so it cannot be claimed by spoofing a wallet header. M32 holders also get exclusive access to three token-gated APIs: Whale Tracker (1M M32), Token Comparison (2.5M M32), and Portfolio Scanner (5M M32) — these are live now and require passing your wallet address via the `X-Wallet-Address` header.
+
+### `get_m32_whale_tracker`
+
+M32-gated whale analysis for any Solana token. Returns top 20 holders, concentration risk, holder distribution, and buy/sell pressure. Requires the caller to hold 1,000,000+ M32 tokens (balance verified on-chain). Free for qualifying holders.
+
+```json
+{ "token": "<mint-address>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `compare_tokens_m32`
+
+M32-gated head-to-head intelligence comparison of two Solana tokens. Returns side-by-side alpha scores, rug risk, whale activity, volume, liquidity, and a winner verdict. Requires 2,500,000+ M32 tokens.
+
+```json
+{ "tokenA": "<mint-A>", "tokenB": "<mint-B>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `scan_portfolio_m32`
+
+M32-gated full wallet portfolio scan. Discovers all SPL tokens in a wallet, runs intelligence on top holdings, and returns per-token analysis with aggregate risk metrics. Requires 5,000,000+ M32 tokens.
+
+```json
+{ "wallet": "<wallet-to-scan>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `manage_agent_budget`
+
+View, set, or reset the economic circuit breaker for your agent session. Prevents runaway spending with infrastructure-level budget enforcement.
+
+```json
+{ "action": "get" }
+```
+
+```json
+{ "action": "set", "budgetLimitUsd": 10.0, "velocityLimitUsd": 1.0, "alertThresholdPercent": 80 }
+```
+
+```json
+{ "action": "reset" }
+```
+
+Three actions:
+
+* **get** returns current budget status: remaining balance, hourly velocity, circuit breaker state, and per-service spending breakdown.
+* **set** configures `budgetLimitUsd` (max total session spend), `velocityLimitUsd` (max spend per hour), and `alertThresholdPercent` (warn at this percentage of budget used). All three are optional and can be set independently.
+* **reset** clears a tripped circuit breaker so the session can resume spending. Circuit breakers trip automatically when limits are exceeded and stay tripped until manually reset.
+
+Budget limits can also be set at session creation time via the agent console at mpp32.org/agent-console or by passing `budgetLimitUsd`, `velocityLimitUsd`, and `alertThresholdPercent` to `POST /api/agent/sessions`.
 
 ## How discovery works
 

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { signX402Payment } from "./x402-signers.js";
-const SERVER_VERSION = "1.2.4";
+const SERVER_VERSION = "1.3.1";
 // ── Env loading: trim and sanitize aggressively ─────────────────────────────
 // Copy-paste from Claude Desktop / Cursor / Windsurf JSON config UIs frequently
 // adds trailing \n, \r, NBSP, BOM, or wraps the value in literal quotes. Any
@@ -252,7 +252,7 @@ server.tool("get_mpp32_diagnostics", "Report what the mpp32-mcp-server detected
         `- x402 (USDC on Solana) payment: ${SOLANA_PRIVATE_KEY ? "yes" : "no — set MPP32_SOLANA_PRIVATE_KEY"}`,
         `- x402 (USDC on Base/EVM) payment: ${PRIVATE_KEY ? "yes" : "no — set MPP32_PRIVATE_KEY"}`,
         ``,
-        `**Ready to pay end-to-end:** ${readyToPay ? "YES — try `query_intelligence` with token=\"M32\" to confirm." : "NO — see the missing items above."}`,
+        `**Ready to pay end-to-end:** ${readyToPay ? "YES — try `get_solana_token_intelligence` with token=\"M32\" to confirm." : "NO — see the missing items above."}`,
         ``,
         `**If a variable shows NOT SET but you set it in claude_desktop_config.json:**`,
         `1. Confirm the file path Claude Desktop actually reads:`,
@@ -308,6 +308,10 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
         .enum(["native", "x402-bazaar", "mcp-registry", "curated", "free"])
         .optional()
         .describe("Filter by catalog source. 'native' = callable end-to-end; 'curated'/'free' = often callable; 'x402-bazaar'/'mcp-registry' = mostly listing-only."),
+    protocol: z
+        .enum(["x402", "tempo", "acp", "ap2", "agtp"])
+        .optional()
+        .describe("Filter by payment protocol (e.g. 'x402' for USDC-settled services)."),
     limit: z
         .number()
         .int()
@@ -315,7 +319,7 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
         .max(500)
         .optional()
         .describe("Max results (default 100, max 500)."),
-}, async ({ category, q, source, limit }) => {
+}, async ({ category, q, source, protocol, limit }) => {
     try {
         const url = new URL("/api/agent/services", API_URL);
         if (category)
@@ -324,6 +328,8 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
             url.searchParams.set("q", q);
         if (source)
             url.searchParams.set("source", source);
+        if (protocol)
+            url.searchParams.set("protocol", protocol);
         url.searchParams.set("limit", String(limit ?? 100));
         const res = await fetchWithTimeout(url.toString(), { headers: buildHeaders() });
         if (!res.ok) {
@@ -460,6 +466,221 @@ server.tool("get_solana_token_intelligence", "Get real-time Solana token intelli
     // Legacy path — direct call to /api/intelligence with manual 402 handling.
     return await legacyIntelligenceCall(token, walletAddress);
 });
+// ── Tool 4: M32-gated Whale Tracker ───────────────────────────────────────
+server.tool("get_m32_whale_tracker", "M32-gated whale analysis for any Solana token. Returns top 20 holders, concentration risk, holder distribution, and buy/sell pressure. Requires the caller to hold 1,000,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders — no payment required. Returns 403 if the wallet holds insufficient M32.", {
+    token: z
+        .string()
+        .describe("Solana token mint address to analyze for whale activity."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 1M+ M32."),
+}, async ({ token, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/whale-tracker`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ token }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Whale Tracker requires holding 1,000,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Whale Tracker** — \`${token}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 5: M32-gated Token Comparison ────────────────────────────────────
+server.tool("compare_tokens_m32", "M32-gated head-to-head intelligence comparison of two Solana tokens. Returns side-by-side alpha scores, rug risk, whale activity, volume, liquidity, market data, and a winner verdict. Requires the caller to hold 2,500,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders. Returns 403 if insufficient M32.", {
+    tokenA: z
+        .string()
+        .describe("First Solana token mint address."),
+    tokenB: z
+        .string()
+        .describe("Second Solana token mint address."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 2.5M+ M32."),
+}, async ({ tokenA, tokenB, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/compare`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ tokenA, tokenB }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Token Comparison requires holding 2,500,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Token Comparison** — \`${tokenA}\` vs \`${tokenB}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 6: M32-gated Portfolio Scanner ───────────────────────────────────
+server.tool("scan_portfolio_m32", "M32-gated full wallet portfolio scan. Discovers all SPL tokens in a Solana wallet, runs intelligence on top holdings, and returns per-token analysis with aggregate portfolio risk metrics. Requires the caller to hold 5,000,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders. Returns 403 if insufficient M32.", {
+    wallet: z
+        .string()
+        .describe("Solana wallet address to scan for token holdings."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 5M+ M32."),
+}, async ({ wallet, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/portfolio`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ wallet }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Portfolio Scanner requires holding 5,000,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Portfolio Scanner** — wallet \`${wallet}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 8: manage_agent_budget ────────────────────────────────────────────
+server.tool("manage_agent_budget", "View, set, or reset the spending circuit breaker for your MPP32 agent session. Use 'get' to check current budget status (remaining budget, hourly velocity, circuit breaker state). Use 'set' to configure spending limits (budget cap in USD, hourly velocity limit, alert threshold percentage). Use 'reset' to manually reset a tripped circuit breaker so the session can resume spending. Circuit breakers trip automatically when budget or velocity limits are exceeded, preventing runaway agent spending.", {
+    action: z.enum(["get", "set", "reset"]).describe("Action: 'get' = view budget status, 'set' = update limits, 'reset' = clear tripped circuit breaker"),
+    budgetLimitUsd: z.number().positive().max(1_000_000).optional().describe("Maximum total session spend in USD. Only used with action='set'."),
+    velocityLimitUsd: z.number().positive().max(1_000_000).optional().describe("Maximum spend per hour in USD. Only used with action='set'."),
+    alertThresholdPercent: z.number().int().min(1).max(100).optional().describe("Budget percentage at which to warn (e.g. 80 = warn at 80% spent). Only used with action='set'."),
+}, async ({ action, budgetLimitUsd, velocityLimitUsd, alertThresholdPercent }) => {
+    if (!AGENT_KEY) {
+        return {
+            content: [{ type: "text", text: "**MPP32_AGENT_KEY not configured.** Set it in your MCP config to manage budgets." }],
+        };
+    }
+    try {
+        if (action === "get") {
+            const res = await fetchWithTimeout(new URL("/api/agent/spending", API_URL).toString(), { headers: buildHeaders() });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error fetching budget: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                `**MPP32 Session Budget Status**`,
+                ``,
+            ];
+            if (data.budgetLimitUsd != null) {
+                lines.push(`Budget: $${data.totalSpentUsd.toFixed(4)} spent of $${data.budgetLimitUsd.toFixed(4)} ($${data.remainingBudgetUsd.toFixed(4)} remaining, ${data.budgetUtilizationPercent}% used)`);
+            }
+            else {
+                lines.push(`Budget: unlimited (no cap set)`);
+                lines.push(`Total spent: $${data.totalSpentUsd.toFixed(4)} across ${data.totalSettledCalls} settled calls`);
+            }
+            if (data.velocityLimitUsd != null) {
+                lines.push(`Velocity: $${data.hourlySpendUsd.toFixed(4)}/hr of $${data.velocityLimitUsd.toFixed(4)}/hr limit (${data.hourlySettledCalls} calls this hour)`);
+            }
+            if (data.circuitBreakerTripped) {
+                lines.push(``);
+                lines.push(`**CIRCUIT BREAKER TRIPPED** — ${data.circuitBreakerReason}`);
+                lines.push(`Tripped at: ${data.circuitBreakerTrippedAt}`);
+                lines.push(`Use action="reset" to resume spending.`);
+            }
+            if (data.byService?.length) {
+                lines.push(``);
+                lines.push(`**Spending by service:**`);
+                for (const s of data.byService) {
+                    lines.push(`- ${s.service}: $${s.totalSpentUsd.toFixed(4)} (${s.count} calls)`);
+                }
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        if (action === "set") {
+            const payload = {};
+            if (budgetLimitUsd !== undefined)
+                payload.budgetLimitUsd = budgetLimitUsd;
+            if (velocityLimitUsd !== undefined)
+                payload.velocityLimitUsd = velocityLimitUsd;
+            if (alertThresholdPercent !== undefined)
+                payload.alertThresholdPercent = alertThresholdPercent;
+            if (Object.keys(payload).length === 0) {
+                return { content: [{ type: "text", text: "Provide at least one of: budgetLimitUsd, velocityLimitUsd, alertThresholdPercent." }] };
+            }
+            const res = await fetchWithTimeout(new URL("/api/agent/budget", API_URL).toString(), {
+                method: "PATCH",
+                headers: buildHeaders({ "Content-Type": "application/json" }),
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error updating budget: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                `**Budget updated successfully.**`,
+                ``,
+                data.budgetLimitUsd != null ? `Budget limit: $${data.budgetLimitUsd.toFixed(4)}` : `Budget limit: unlimited`,
+                data.velocityLimitUsd != null ? `Velocity limit: $${data.velocityLimitUsd.toFixed(4)}/hr` : `Velocity limit: unlimited`,
+                `Total spent: $${data.totalSpentUsd.toFixed(4)}`,
+                data.remainingBudgetUsd != null ? `Remaining: $${data.remainingBudgetUsd.toFixed(4)}` : ``,
+                data.circuitBreakerTripped ? `\n**Note:** Circuit breaker is still tripped. Use action="reset" to resume.` : ``,
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        if (action === "reset") {
+            const res = await fetchWithTimeout(new URL("/api/agent/circuit-breaker/reset", API_URL).toString(), {
+                method: "POST",
+                headers: buildHeaders({ "Content-Type": "application/json" }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error resetting circuit breaker: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                data.previousReason
+                    ? `**Circuit breaker reset.** Previous reason: ${data.previousReason}.`
+                    : `**Circuit breaker was not tripped.** No action needed.`,
+                ``,
+                data.budgetLimitUsd != null ? `Budget: $${data.totalSpentUsd.toFixed(4)} / $${data.budgetLimitUsd.toFixed(4)} ($${data.remainingBudgetUsd.toFixed(4)} remaining)` : ``,
+                `Session can resume spending.`,
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        return { content: [{ type: "text", text: "Unknown action. Use 'get', 'set', or 'reset'." }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
 // ── Core: agent/execute path with 402 sign-and-retry ────────────────────────
 async function callViaAgentExecute(service, method, body, query, path) {
     try {
@@ -637,6 +858,10 @@ function formatExecuteSuccess(resp, protoOverride) {
     else if (meta?.paymentMethod === "unsettled") {
         lines.push(`Service responded but no payment was verified. This should not happen for paid services.`);
     }
+    if (meta?.budget && meta.budget.budgetLimitUsd != null) {
+        const b = meta.budget;
+        lines.push(`Budget: $${b.remainingBudgetUsd.toFixed(4)} remaining (${b.budgetUtilizationPercent}% of $${b.budgetLimitUsd.toFixed(4)} used)`);
+    }
     lines.push("");
     lines.push("```json");
     lines.push(formatted);
@@ -645,6 +870,25 @@ function formatExecuteSuccess(resp, protoOverride) {
 }
 function formatExecuteHardError(status, body) {
     const code = body?.error?.code;
+    if (code === "MPP32_CIRCUIT_BREAKER_TRIPPED" || (status === 429 && body?.error?.budgetStatus)) {
+        const bs = body?.error?.budgetStatus;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `**Circuit breaker tripped** — spending limit reached.`,
+                        ``,
+                        body?.error?.message ?? "Session budget exhausted.",
+                        bs?.budgetLimitUsd != null ? `Budget: $${bs.totalSpentUsd?.toFixed(4) ?? "?"} / $${bs.budgetLimitUsd.toFixed(4)}` : "",
+                        bs?.velocityLimitUsd != null ? `Velocity: $${bs.hourlySpendUsd?.toFixed(4) ?? "?"}/hr of $${bs.velocityLimitUsd.toFixed(4)}/hr limit` : "",
+                        ``,
+                        `To resume: use \`manage_agent_budget\` with action="reset", or increase the budget with action="set".`,
+                    ].filter(Boolean).join("\n"),
+                },
+            ],
+        };
+    }
     if (code === "NOT_HTTP_CALLABLE") {
         return {
             content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpp32-mcp-server",
-  "version": "1.2.4",
+  "version": "1.3.1",
   "mcpName": "io.github.MPP32/mpp32-mcp-server",
   "description": "Payment layer for AI agents. One MCP, five protocols, thousands of paid APIs your agent can call.",
   "type": "module",