mpp32-mcp-server 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.2.3] - 2026-05-11
+
+### Fixed
+
+* **Solana-only users were being pushed to EVM and failing.** When a third-
+  party x402 v2 challenge advertised both an EVM and an SVM entry in
+  `accepts[]`, 1.2.2's `pickRequirements` preferred EVM unconditionally —
+  so a user who had only set `MPP32_SOLANA_PRIVATE_KEY` got a "no EVM key
+  set" error instead of a successful Solana payment. The picker now:
+  - Honors `MPP32_PREFERRED_NETWORK` if set (accepts `solana`, `base`,
+    `evm`, `ethereum`, or a full CAIP-2 like `solana:5eykt...`).
+  - Otherwise, if only one key is configured, prefers that network.
+  - Otherwise, when both keys are configured, prefers EVM (Base settles
+    faster and is the dominant chain across providers).
+  - Otherwise falls back to the first `accepts[]` entry so the per-network
+    signer can surface a precise "you need MPP32_X_PRIVATE_KEY" error.
+
+### Added
+
+* **`MPP32_PREFERRED_NETWORK` env var.** Explicit override for the network
+  picker. Useful when both keys are configured but the user wants every
+  payment to go through one specific chain.
+* **`debug_mpp32` tool (alias of `get_mpp32_diagnostics`).** Several
+  external docs and skills already reference this name; the alias keeps
+  them working without a documentation churn.
+
+### Changed
+
+* **`get_mpp32_diagnostics` now probes the API live.** In addition to
+  reporting which env vars the process loaded, it issues a 5-second
+  `GET /api/agent/protocols` against the configured `MPP32_API_URL` and
+  reports `OK / Reachable but {status} / UNREACHABLE: {reason}`. Adds a
+  single `Ready to pay end-to-end: YES/NO` line so users do not need to
+  cross-reference three separate fields to know whether payments will
+  work. Windows-specific guidance (no surrounding quotes inside the JSON
+  string) is now called out explicitly — this tripped multiple users in
+  1.2.1/1.2.2.
+
 ## [1.2.2] - 2026-05-11
 
 ### Fixed

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.2";
+const SERVER_VERSION = "1.2.3";
 // ── 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
@@ -121,6 +121,22 @@ const SOLANA_PRIVATE_KEY = (() => {
     }
     return v;
 })();
+// Optional override: when both an EVM and a Solana key are configured, this
+// decides which network to use for mixed challenges. Accepts:
+//   "solana" (or any "solana:*" CAIP-2), "base", "evm", "ethereum".
+// Defaults to undefined — pickRequirements then falls back to its own rules.
+const PREFERRED_NETWORK = (() => {
+    const v = readEnv("MPP32_PREFERRED_NETWORK");
+    if (!v)
+        return undefined;
+    const lower = v.toLowerCase();
+    const allowed = ["solana", "base", "evm", "ethereum"];
+    if (!allowed.some((a) => lower === a || lower.startsWith(a))) {
+        console.error(`[mpp32] MPP32_PREFERRED_NETWORK="${v}" not recognized. Allowed: ${allowed.join(", ")} (or full CAIP-2 like solana:5eykt...). Ignoring.`);
+        return undefined;
+    }
+    return lower;
+})();
 // Wrap fetch with a default timeout. AbortSignal.timeout exists in Node 20+,
 // but we ship for Node 18+, so we build the signal ourselves.
 async function fetchWithTimeout(url, init) {
@@ -197,12 +213,29 @@ function describeEnvVarStatus(name, value) {
         : `${value.slice(0, 6)}…${value.slice(-4)} (${value.length} chars)`;
     return `${name}: SET (${fingerprint})`;
 }
-server.tool("get_mpp32_diagnostics", "Report what the mpp32-mcp-server detected at startup: version, API URL, and which env vars (MPP32_AGENT_KEY, MPP32_SOLANA_PRIVATE_KEY, MPP32_PRIVATE_KEY) were loaded into this process. Use this FIRST if payments fail with 'no key configured' even though you set one in claude_desktop_config.json — it confirms whether your env vars actually reached the MCP process or got dropped by a typo / wrong file / stale restart.", {}, async () => {
+server.tool("get_mpp32_diagnostics", "Report what the mpp32-mcp-server detected at startup: version, API URL, env vars (MPP32_AGENT_KEY, MPP32_SOLANA_PRIVATE_KEY, MPP32_PRIVATE_KEY, MPP32_PREFERRED_NETWORK), and a live API connectivity check. Use this FIRST if payments fail with 'no key configured' even though you set one in claude_desktop_config.json.", {}, async () => {
+    // Live connectivity probe so the user knows whether the *backend* is
+    // reachable too — not just whether their env loaded.
+    let apiReachable;
+    try {
+        const probe = await fetchWithTimeout(`${API_URL}/api/agent/protocols`, {
+            timeoutMs: 5_000,
+        });
+        apiReachable = probe.ok
+            ? `OK (${probe.status})`
+            : `Reachable but returned ${probe.status}`;
+    }
+    catch (err) {
+        apiReachable = `UNREACHABLE: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const haveAnyKey = !!(SOLANA_PRIVATE_KEY || PRIVATE_KEY);
+    const readyToPay = !!AGENT_KEY && haveAnyKey;
     const lines = [
         `**mpp32-mcp-server diagnostics**`,
         ``,
         `Version: ${SERVER_VERSION}`,
         `API URL: ${API_URL}`,
+        `API reachable: ${apiReachable}`,
         `Timeout: ${TIMEOUT_MS}ms`,
         `Node: ${process.version} on ${process.platform}/${process.arch}`,
         ``,
@@ -211,26 +244,56 @@ server.tool("get_mpp32_diagnostics", "Report what the mpp32-mcp-server detected
         describeEnvVarStatus("MPP32_AGENT_KEY", AGENT_KEY),
         describeEnvVarStatus("MPP32_SOLANA_PRIVATE_KEY", SOLANA_PRIVATE_KEY),
         describeEnvVarStatus("MPP32_PRIVATE_KEY", PRIVATE_KEY),
+        `MPP32_PREFERRED_NETWORK: ${PREFERRED_NETWORK ?? "not set (auto: prefer the only key you have)"}`,
         ``,
         `**Capabilities:**`,
         `- Catalog browsing: yes (always available)`,
         `- Federated service execution: ${AGENT_KEY ? "yes" : "no — set MPP32_AGENT_KEY"}`,
         `- x402 (USDC on Solana) payment: ${SOLANA_PRIVATE_KEY ? "yes" : "no — set MPP32_SOLANA_PRIVATE_KEY"}`,
-        `- Tempo (pathUSD on Eth L2) payment: ${PRIVATE_KEY ? "yes" : "no — set MPP32_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."}`,
         ``,
-        `If a variable shows NOT SET but you put it in claude_desktop_config.json:`,
-        `1. Confirm the file path Claude Desktop actually reads from:`,
-        `   - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json`,
+        `**If a variable shows NOT SET but you set it in claude_desktop_config.json:**`,
+        `1. Confirm the file path Claude Desktop actually reads:`,
+        `   - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json`,
         `   - Windows: %APPDATA%\\Claude\\claude_desktop_config.json`,
-        `2. The 'env' block must sit INSIDE the server entry, alongside 'command' and 'args' — not at the top level.`,
-        `3. Fully quit Claude Desktop (Cmd+Q on Mac, right-click tray → Quit on Windows). Closing the window is not enough.`,
-        `4. Re-open Claude Desktop. The new MCP process inherits the env from the JSON.`,
-        `5. Call get_mpp32_diagnostics again — if it still shows NOT SET, the JSON did not load (check for a syntax error).`,
+        `2. The 'env' block must sit INSIDE the server entry, beside 'command' and 'args' — not at the top level.`,
+        `3. Validate the JSON: a single missing comma silently throws the whole file out.`,
+        `4. Fully quit Claude Desktop:`,
+        `   - macOS: Cmd+Q (or Claude menu → Quit)`,
+        `   - Windows: right-click the system-tray icon → Quit (closing the window is NOT enough)`,
+        `5. Re-open Claude Desktop. The new MCP child process inherits env from the JSON.`,
+        `6. Call get_mpp32_diagnostics again. If it STILL shows NOT SET, the JSON did not load — check the Claude Desktop log for a parse error.`,
+        ``,
+        `**On Windows specifically:** the value must NOT include surrounding quotes inside the JSON string. Bad: "\\"mpp32_agent_abc...\\"". Good: "mpp32_agent_abc...".`,
     ];
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };
 });
+// Back-compat alias. Older docs and skills say `debug_mpp32`.
+server.tool("debug_mpp32", "Alias for get_mpp32_diagnostics. Reports env-var detection, API connectivity, and ready-to-pay status.", {}, async () => {
+    let apiReachable;
+    try {
+        const probe = await fetchWithTimeout(`${API_URL}/api/agent/protocols`, { timeoutMs: 5_000 });
+        apiReachable = probe.ok ? `OK (${probe.status})` : `Reachable but returned ${probe.status}`;
+    }
+    catch (err) {
+        apiReachable = `UNREACHABLE: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const readyToPay = !!AGENT_KEY && !!(SOLANA_PRIVATE_KEY || PRIVATE_KEY);
+    const lines = [
+        `mpp32-mcp-server v${SERVER_VERSION} (${process.platform}/${process.arch}, Node ${process.version})`,
+        `API: ${API_URL} — ${apiReachable}`,
+        describeEnvVarStatus("MPP32_AGENT_KEY", AGENT_KEY),
+        describeEnvVarStatus("MPP32_SOLANA_PRIVATE_KEY", SOLANA_PRIVATE_KEY),
+        describeEnvVarStatus("MPP32_PRIVATE_KEY", PRIVATE_KEY),
+        `MPP32_PREFERRED_NETWORK: ${PREFERRED_NETWORK ?? "not set"}`,
+        `Ready to pay: ${readyToPay ? "YES" : "NO"}`,
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
 // ── Tool 1: list_mpp32_services ─────────────────────────────────────────────
 server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+ machine-payable APIs and data services. Includes native MPP32 services (callable end-to-end through this MCP), the x402 Bazaar (USDC on Solana), curated free APIs (DexScreener, Jupiter, CoinGecko health, httpbin, etc.), and the public MCP Registry (npx-installable servers; listing-only). Each result indicates whether it is callable through `call_mpp32_endpoint` or listing-only. The catalog is large (~4,500 entries) — by default a single call returns up to 100 results and the response will tell you the true total and whether the page was truncated. Use `q` (free-text search), `category`, `source`, or `protocol` to narrow down, or raise `limit` (max 500) for broader pages.", {
     category: z
@@ -1063,6 +1126,7 @@ async function completeX402Payment(paymentRequiredHeader, keys) {
         solanaKey: keys.solana,
         evmKey: keys.evm,
         solanaRpcUrl,
+        preferredNetwork: PREFERRED_NETWORK,
     });
     return {
         xPaymentHeader: result.xPaymentHeader,

package/dist/x402-signers.d.ts

@@ -32,6 +32,7 @@ export interface SignX402Args {
     solanaKey?: string;
     evmKey?: string;
     solanaRpcUrl?: string;
+    preferredNetwork?: string;
 }
 export interface SignX402Result {
     xPaymentHeader: string;

package/dist/x402-signers.js

@@ -279,21 +279,55 @@ function normalizeRequirements(raw) {
         extra: raw.extra,
     };
 }
-// Pick the first entry in `accepts` we can actually sign. Preference order:
-//   1. EVM entries when an EVM key is available (Base is the dominant chain).
-//   2. SVM entries when a Solana key is available.
-// If no entry matches the keys we hold, fall back to the first entry and let
-// the per-network signer throw a precise "you need MPP32_X_PRIVATE_KEY" error.
-function pickRequirements(accepts, haveSvm, haveEvm) {
+// Pick the first entry in `accepts` we can actually sign.
+//
+// Preference rules (in order):
+//   1. If MPP32_PREFERRED_NETWORK env var matches a `network` field, use it.
+//   2. If only one key is configured, prefer that network (this is the most
+//      common real-world case — a Solana-only user offered a mixed challenge
+//      previously got signed EVM and failed with "no EVM key set". Now they
+//      get signed SVM.).
+//   3. If both keys are configured, prefer EVM (Base is the dominant chain
+//      and tends to settle faster).
+//   4. Otherwise fall back to the first accepted entry and let the per-network
+//      signer throw a precise "you need MPP32_X_PRIVATE_KEY" error.
+function pickRequirements(accepts, haveSvm, haveEvm, preferredNetwork) {
     if (accepts.length === 0) {
         throw new Error("x402 v2 challenge has empty `accepts` array — nothing to pay.");
     }
-    if (haveEvm) {
+    // Explicit preference wins.
+    if (preferredNetwork) {
+        const want = preferredNetwork.toLowerCase();
+        const explicit = accepts.find((a) => {
+            const n = a.network.toLowerCase();
+            if (n === want)
+                return true;
+            if (want === "solana" && isSvmNetwork(a.network))
+                return true;
+            if ((want === "base" || want === "evm") && isEvmNetwork(a.network))
+                return true;
+            return false;
+        });
+        if (explicit)
+            return explicit;
+    }
+    // Solana-only user: prefer SVM.
+    if (haveSvm && !haveEvm) {
+        const svm = accepts.find((a) => isSvmNetwork(a.network));
+        if (svm)
+            return svm;
+    }
+    // EVM-only user: prefer EVM.
+    if (haveEvm && !haveSvm) {
         const evm = accepts.find((a) => isEvmNetwork(a.network));
         if (evm)
             return evm;
     }
-    if (haveSvm) {
+    // Both keys configured: prefer EVM (Base is the dominant chain).
+    if (haveEvm && haveSvm) {
+        const evm = accepts.find((a) => isEvmNetwork(a.network));
+        if (evm)
+            return evm;
         const svm = accepts.find((a) => isSvmNetwork(a.network));
         if (svm)
             return svm;
@@ -317,7 +351,7 @@ export async function signX402Payment(args) {
         const accepts = decoded.accepts
             .filter((a) => !!a && typeof a === "object")
             .map(normalizeRequirements);
-        requirements = pickRequirements(accepts, !!args.solanaKey, !!args.evmKey);
+        requirements = pickRequirements(accepts, !!args.solanaKey, !!args.evmKey, args.preferredNetwork);
         echoedVersion = decoded.x402Version || 2;
     }
     else if (decoded && typeof decoded === "object") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpp32-mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "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",