mpp32-mcp-server 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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.1.4] - 2026-05-11
+
+### Added
+
+* **`get_mpp32_diagnostics` MCP tool.** Reports server version, API URL,
+  and per-variable detection state for `MPP32_AGENT_KEY`,
+  `MPP32_SOLANA_PRIVATE_KEY`, and `MPP32_PRIVATE_KEY` — without ever
+  echoing the secret. The single most common payment failure has been
+  "I set the key but the MCP server doesn't see it" (wrong
+  `claude_desktop_config.json` file, `env` block at the wrong level in
+  the JSON, typo, or stale process from an incomplete restart). This
+  tool turns that into a one-call diagnosis.
+* **Per-variable startup banner lines.** The stderr banner now prints
+  one `[mpp32] MPP32_X: SET (fingerprint) / NOT SET` line per managed
+  env var, so users who can find their MCP log file can see the same
+  diagnosis without calling a tool.
+
+## [1.1.3] - 2026-05-11
+
+### Fixed
+
+* **x402 payments actually work now.** `completeX402Payment` previously
+  dynamically imported `@solana/web3.js`, `bs58`, and `tweetnacl`, but
+  none of those packages were declared in `dependencies`. On a clean
+  `npx mpp32-mcp-server` install they were missing from `node_modules`,
+  the import threw, the catch block returned a misleading "check wallet
+  balance" message, and Claude paraphrased that as "no funded Solana
+  wallet configured" even when `MPP32_SOLANA_PRIVATE_KEY` was set.
+* **Dropped `@solana/web3.js` entirely.** Adding it to `dependencies`
+  uncovered a second, deeper bug: its transitive `rpc-websockets`
+  bundle is CJS and `require()`s a now ESM-only `uuid`, which throws
+  `ERR_REQUIRE_ESM` on Node 20+ the first time the signer loads. We
+  only ever used `Keypair.fromSecretKey` and `publicKey.toBase58()`,
+  both of which are trivial Ed25519/base58 operations. Signing is now
+  done directly with `tweetnacl` + `bs58`, so the failure mode is gone
+  and the install footprint is ~30 MB smaller.
+* **Properly declared signing dependencies.** `bs58` and `tweetnacl`
+  are now real `dependencies` rather than implicit assumptions.
+* **Better error when a payment dependency genuinely fails to load.**
+  The catch around each dynamic import now tells the user the package
+  ships with `mpp32-mcp-server` and directs them to upgrade to
+  `@latest` instead of suggesting a manual `npm install` that won't
+  stick across `npx` runs.
+* **32-byte seed Solana keys now accepted** in addition to 64-byte
+  expanded keys (previously `Keypair.fromSecretKey` rejected seeds).
+
+### Added
+
+* **Catalog total surfaced in `list_mpp32_services`.** The federated
+  catalog has 4,500+ external services but the API returns at most 500
+  per call (default 100). The response now includes
+  `data.totalAvailable` and a `truncated`/`hint` pair so the model
+  knows results were paginated and how to drill in with `q`,
+  `category`, `source`, or `protocol`. The MCP client formats the
+  header as `Found N services (of M total available in catalog)` and
+  prints the hint when applicable.
+
 ## [1.1.2] - 2026-05-10
 
 ### Fixed

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-const SERVER_VERSION = "1.1.2";
+const SERVER_VERSION = "1.1.4";
 // ── 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
@@ -173,8 +173,65 @@ function isHttpCallable(svc) {
         return false;
     return /^https?:\/\//.test(url);
 }
+// ── Tool 0: get_mpp32_diagnostics ───────────────────────────────────────────
+// Lets the user (and Claude) see exactly what the MCP process detected at
+// startup. The single most common failure mode is "I set the env var but it
+// didn't reach the server" — wrong claude_desktop_config.json file edited,
+// `env` block at the wrong level, typo in the variable name, stale process
+// from an incomplete restart. This tool answers all of those without
+// asking the user to dig through MCP log files.
+function describeEnvVarStatus(name, value) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return `${name}: NOT SET (variable absent from MCP process env)`;
+    if (raw.length === 0)
+        return `${name}: EMPTY (set but blank)`;
+    if (value === undefined) {
+        return `${name}: REJECTED (raw length ${raw.length}, but failed validation — check startup log for reason)`;
+    }
+    // Show a short, non-secret fingerprint so the user can confirm it's the
+    // right value without us exfiltrating the key.
+    const fingerprint = value.length <= 12
+        ? `${value.length} chars`
+        : `${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 () => {
+    const lines = [
+        `**mpp32-mcp-server diagnostics**`,
+        ``,
+        `Version: ${SERVER_VERSION}`,
+        `API URL: ${API_URL}`,
+        `Timeout: ${TIMEOUT_MS}ms`,
+        `Node: ${process.version} on ${process.platform}/${process.arch}`,
+        ``,
+        `**Environment variable detection** (values are fingerprinted, never returned in full):`,
+        ``,
+        describeEnvVarStatus("MPP32_AGENT_KEY", AGENT_KEY),
+        describeEnvVarStatus("MPP32_SOLANA_PRIVATE_KEY", SOLANA_PRIVATE_KEY),
+        describeEnvVarStatus("MPP32_PRIVATE_KEY", PRIVATE_KEY),
+        ``,
+        `**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"}`,
+        ``,
+        `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`,
+        `   - 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).`,
+    ];
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
 // ── Tool 1: list_mpp32_services ─────────────────────────────────────────────
-server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 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. Use the `category`, `q`, or `source` filters to narrow down.", {
+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
         .string()
         .optional()
@@ -251,17 +308,24 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of machin
                 .join("\n");
         });
         const counts = json.data.counts;
+        const totalAvailable = json.data.totalAvailable;
         const callableCount = services.filter(isHttpCallable).length;
+        const sourcesLine = totalAvailable
+            ? `**Sources:** ${counts.native} native + ${counts.external} external (of ${totalAvailable.combined} total available in catalog). **Callable through this MCP:** ${callableCount}.`
+            : `**Sources:** ${counts.native} native + ${counts.external} external. **Callable through this MCP:** ${callableCount}.`;
         const header = [
             `# MPP32 Federated Catalog — ${services.length} result${services.length !== 1 ? "s" : ""}`,
             ``,
-            `**Sources:** ${counts.native} native + ${counts.external} external. **Callable through this MCP:** ${callableCount}.`,
+            sourcesLine,
+            json.data.truncated && json.data.hint ? `\n> ⚠️ ${json.data.hint}` : ``,
             ``,
             AGENT_KEY
                 ? `Calls through \`call_mpp32_endpoint\` are tracked in your dashboard at ${API_URL}/agent-console (your X-Agent-Key is set).`
                 : `**Tip:** set \`MPP32_AGENT_KEY\` in your MCP config to track usage at ${API_URL}/agent-console. Get a key at ${API_URL}/agent-console.`,
             ``,
-        ].join("\n");
+        ]
+            .filter((l) => l !== ``)
+            .join("\n");
         return {
             content: [{ type: "text", text: header + "\n" + lines.join("\n\n") }],
         };
@@ -970,40 +1034,70 @@ async function completeX402Payment(paymentRequiredHeader, solanaPrivateKey) {
     catch {
         throw new Error("Could not decode Payment-Required header");
     }
+    // We sign x402 challenges with raw Ed25519 (Solana keys are Ed25519). No
+    // @solana/web3.js needed — it pulls in rpc-websockets which has a
+    // CJS/ESM uuid incompat on Node 20+ that breaks every paid call.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let solanaWeb3;
+    let tweetnacl;
     try {
-        const pkg = "@solana/web3.js";
-        solanaWeb3 = await import(pkg);
+        const pkg = "tweetnacl";
+        tweetnacl = await import(pkg);
     }
-    catch {
-        throw new Error("x402 payment requires @solana/web3.js: npm install @solana/web3.js");
+    catch (err) {
+        throw new Error(`x402 signing requires tweetnacl, which ships with mpp32-mcp-server. ` +
+            `If you're seeing this on a clean npx install, upgrade to mpp32-mcp-server@latest. ` +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let keypair;
+    let bs58;
+    try {
+        const pkg = "bs58";
+        bs58 = await import(pkg);
+    }
+    catch (err) {
+        throw new Error(`x402 signing requires bs58, which ships with mpp32-mcp-server. ` +
+            `Upgrade to mpp32-mcp-server@latest. ` +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const bs58Decode = bs58.default?.decode ?? bs58.decode;
+    const bs58Encode = bs58.default?.encode ?? bs58.encode;
+    const naclSign = tweetnacl.default?.sign ?? tweetnacl.sign;
+    let rawKey;
     try {
         if (solanaPrivateKey.startsWith("[")) {
-            keypair = solanaWeb3.Keypair.fromSecretKey(new Uint8Array(JSON.parse(solanaPrivateKey)));
+            rawKey = new Uint8Array(JSON.parse(solanaPrivateKey));
         }
         else if (/^[0-9a-fA-F]+$/.test(solanaPrivateKey) && solanaPrivateKey.length % 2 === 0) {
-            keypair = solanaWeb3.Keypair.fromSecretKey(new Uint8Array(Buffer.from(solanaPrivateKey, "hex")));
+            rawKey = new Uint8Array(Buffer.from(solanaPrivateKey, "hex"));
         }
         else {
-            const bs58Pkg = "bs58";
-            const bs58 = await import(bs58Pkg);
-            keypair = solanaWeb3.Keypair.fromSecretKey(bs58.default.decode(solanaPrivateKey));
+            rawKey = bs58Decode(solanaPrivateKey);
         }
     }
     catch (err) {
         throw new Error(`Could not decode Solana private key: ${err instanceof Error ? err.message : String(err)}`);
     }
+    let secretKey;
+    let publicKey;
+    if (rawKey.length === 64) {
+        secretKey = rawKey;
+        publicKey = rawKey.slice(32);
+    }
+    else if (rawKey.length === 32) {
+        const kp = naclSign.keyPair.fromSeed(rawKey);
+        secretKey = kp.secretKey;
+        publicKey = kp.publicKey;
+    }
+    else {
+        throw new Error(`Solana private key must be a 32-byte seed or 64-byte expanded key; got ${rawKey.length} bytes.`);
+    }
     const payload = {
         x402Version: 1,
         scheme: requirements.scheme ?? "exact",
         network: requirements.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
         payload: {
             signature: "",
-            from: keypair.publicKey.toBase58(),
+            from: bs58Encode(publicKey),
             amount: requirements.maxAmountRequired,
             asset: requirements.asset,
             payTo: requirements.payTo,
@@ -1012,17 +1106,7 @@ async function completeX402Payment(paymentRequiredHeader, solanaPrivateKey) {
     };
     const message = JSON.stringify(payload.payload);
     const messageBytes = new TextEncoder().encode(message);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let tweetnacl;
-    try {
-        const pkg = "tweetnacl";
-        tweetnacl = await import(pkg);
-    }
-    catch {
-        throw new Error("x402 signing requires tweetnacl: npm install tweetnacl");
-    }
-    const naclSign = tweetnacl.default?.sign ?? tweetnacl.sign;
-    const signed = naclSign.detached(messageBytes, keypair.secretKey);
+    const signed = naclSign.detached(messageBytes, secretKey);
     payload.payload.signature = Buffer.from(signed).toString("base64");
     return Buffer.from(JSON.stringify(payload)).toString("base64");
 }
@@ -1038,6 +1122,13 @@ async function main() {
         .filter(Boolean)
         .join(", ") || "no keys (catalog-only legacy mode)";
     console.error(`[mpp32] MCP server v${SERVER_VERSION} on stdio. API ${API_URL}. Configured: ${features}. Timeout ${TIMEOUT_MS}ms.`);
+    // Per-variable status so a user staring at this log can immediately see
+    // whether their env vars made it through. Values are fingerprinted.
+    const fp = (v) => !v ? "NOT SET" : v.length <= 12 ? `SET (${v.length}c)` : `SET (${v.slice(0, 6)}…${v.slice(-4)}, ${v.length}c)`;
+    console.error(`[mpp32]   MPP32_AGENT_KEY: ${fp(AGENT_KEY)}`);
+    console.error(`[mpp32]   MPP32_SOLANA_PRIVATE_KEY: ${fp(SOLANA_PRIVATE_KEY)}`);
+    console.error(`[mpp32]   MPP32_PRIVATE_KEY: ${fp(PRIVATE_KEY)}`);
+    console.error(`[mpp32] If a key shows NOT SET but you set it in claude_desktop_config.json, call the get_mpp32_diagnostics tool for help, or fully quit Claude Desktop and reopen.`);
 }
 main().catch((err) => {
     console.error("Fatal:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpp32-mcp-server",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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",
@@ -69,6 +69,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "bs58": "^6.0.0",
+    "tweetnacl": "^1.0.3",
     "zod": "^3.23.0"
   },
   "peerDependencies": {