nftdata-mcp 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,10 @@
 
 An MCP server that exposes the [NFT Data](https://www.nftdata.app/) API to AI clients (Claude Desktop, Cursor, etc.) as a single tool. It handles the x402 payment flow automatically.
 
+- **npm:** https://www.npmjs.com/package/nftdata-mcp
+- **MCP Registry:** https://registry.modelcontextprotocol.io/?q=nftdata
+- **NFT Data GitHub Repository:** https://github.com/Nomad07/nft-data
+
 ## Tool
 
 ### `get_collection_data`
@@ -25,8 +29,6 @@ Each call costs **$0.002** (USDC on Base, paid via x402).
 
 ## Quick start (npx)
 
-> Works only after the package has been published to npm. Until then, use "Run from source" below.
-
 Add to `claude_desktop_config.json`:
 
 ```json
@@ -45,8 +47,6 @@ Add to `claude_desktop_config.json`:
 
 Restart Claude Desktop, then ask for example: "What is the floor price and 7-day volume of azuki?"
 
-If the package is published under a scope, use that name instead (e.g. `@your-scope/nftdata-mcp`).
-
 ## Run from source
 
 ```bash
@@ -97,7 +97,7 @@ npm test        # offline unit tests, no network and no payments
 
 - Sends `POST /api/get-collection-data` with body `{"collection": "<slug>"}`.
 - The slug is trimmed and lowercased, then must match `^[a-z0-9][a-z0-9_-]*$` (max 100 characters); otherwise no request is made.
-- Only Base mainnet (`eip155:8453`) is registered with the x402 client. Before signing, every payment challenge is checked: scheme `exact`, network Base mainnet, token USDC on Base, amount at most 2000 units ($0.002), and recipient (must be `0x344143199642e87320785823c20c2df107d17534`). Anything else is refused without signing.
+- Only Base mainnet (`eip155:8453`) is registered with the x402 client. Before signing, every payment challenge is checked: scheme `exact`, network Base mainnet, token USDC on Base, amount exactly 2000 atomic units ($0.002), and recipient (must be `0x344143199642e87320785823c20c2df107d17534`). Anything else is refused without signing.
 - Each signed payment counts against `NFTDATA_MAX_REQUESTS`, including payments for requests that later fail or time out.
 - No automatic retries: one tool call makes at most one payment attempt.
 - Caches successful responses for 5 minutes per slug. Concurrent identical calls share a single in-flight request.

package/dist/lib.js

@@ -108,8 +108,27 @@ export class SpendLimiter {
 }
 export const ok = (text) => ({ content: [{ type: "text", text }] });
 export const fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
+// Appends a payment receipt line to a successful tool result.
+// txHash must already be validated (0x + 64 hex chars).
+export function appendPaymentInfo(result, txHash) {
+    if (result.isError)
+        return result;
+    const receipt = `\n\nPayment: ${txHash}` +
+        `\nVerify: https://basescan.org/tx/${txHash}`;
+    return ok(result.content[0].text + receipt);
+}
+// Validates a tx hash string. Returns the hash if it looks like a valid
+// Ethereum tx hash (0x + 64 hex chars), or null otherwise.
+// This function has no x402 imports so it can be tested offline.
+export function validateTxHash(raw) {
+    if (typeof raw !== "string")
+        return null;
+    return /^0x[0-9a-fA-F]{64}$/.test(raw) ? raw : null;
+}
 // Cache (5 min per slug) + reuse of in-flight requests so concurrent identical calls
 // produce a single (paid) request. Failures are never cached.
+// The loader returns { result, txHash }. Only result.content[0].text (the collection
+// body) is cached; txHash is never stored, so cache hits always return txHash: null.
 export class CachedFetcher {
     cache = new Map();
     inflight = new Map();
@@ -122,23 +141,23 @@ export class CachedFetcher {
     async get(slug) {
         const hit = this.cache.get(slug);
         if (hit && this.now() - hit.at < CACHE_TTL_MS)
-            return ok(hit.body);
+            return { result: ok(hit.body), txHash: null };
         if (hit)
             this.cache.delete(slug);
         const pending = this.inflight.get(slug);
         if (pending)
             return pending;
         const p = this.load(slug)
-            .then((res) => {
-            if (!res.isError) {
+            .then((lr) => {
+            if (!lr.result.isError) {
                 if (this.cache.size >= CACHE_MAX_ENTRIES) {
                     const oldest = this.cache.keys().next().value;
                     if (oldest !== undefined)
                         this.cache.delete(oldest);
                 }
-                this.cache.set(slug, { at: this.now(), body: res.content[0].text });
+                this.cache.set(slug, { at: this.now(), body: lr.result.content[0].text });
             }
-            return res;
+            return lr;
         })
             .finally(() => {
             this.inflight.delete(slug);

package/dist/server.js

@@ -2,10 +2,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
+import { x402Client, wrapFetchWithPayment, decodePaymentResponseHeader } from "@x402/fetch";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { privateKeyToAccount } from "viem/accounts";
-import { BASE_MAINNET, CachedFetcher, REFUSAL_PREFIX, SpendLimiter, fail, isValidPrivateKey, mapError, mapResponse, normalizeSlug, parseConfig, validateRequirements, withTimeout, } from "./lib.js";
+import { BASE_MAINNET, CachedFetcher, REFUSAL_PREFIX, SpendLimiter, appendPaymentInfo, fail, isValidPrivateKey, mapError, mapResponse, normalizeSlug, parseConfig, validateRequirements, validateTxHash, withTimeout, } from "./lib.js";
 let config;
 try {
     config = parseConfig(process.env);
@@ -73,12 +73,33 @@ async function load(slug) {
                 redirect: "error",
                 signal,
             });
-            return { status: r.status, body: await r.text(), retryAfter: r.headers.get("Retry-After") };
+            // Extract the payment response header before consuming the body.
+            const paymentHeader = r.headers.get("PAYMENT-RESPONSE") ?? r.headers.get("X-PAYMENT-RESPONSE");
+            return {
+                status: r.status,
+                body: await r.text(),
+                retryAfter: r.headers.get("Retry-After"),
+                paymentHeader,
+            };
         }, config.timeoutMs);
-        return mapResponse(res.status, res.body, res.retryAfter);
+        const result = mapResponse(res.status, res.body, res.retryAfter);
+        // Decode the payment header and extract the tx hash only on success.
+        // Any failure (malformed header, missing field, wrong format) is silently
+        // ignored — the collection result is still returned without payment info.
+        let txHash = null;
+        if (!result.isError && res.paymentHeader) {
+            try {
+                const settle = decodePaymentResponseHeader(res.paymentHeader);
+                txHash = validateTxHash(settle.transaction);
+            }
+            catch {
+                // Malformed header: proceed without payment info.
+            }
+        }
+        return { result, txHash };
     }
     catch (e) {
-        return mapError(e);
+        return { result: mapError(e), txHash: null };
     }
 }
 const fetcher = new CachedFetcher(load);
@@ -95,6 +116,7 @@ server.tool("get_collection_data", "Get OpenSea NFT collection market data in on
     if (slug === null) {
         return fail("Invalid slug: use only letters, digits, '_' and '-' (max 100 characters).");
     }
-    return fetcher.get(slug);
+    const { result, txHash } = await fetcher.get(slug);
+    return txHash ? appendPaymentInfo(result, txHash) : result;
 });
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nftdata-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for the NFT Data API: OpenSea collection market data, paid per call via x402",
   "mcpName": "io.github.Nomad07/nftdata-mcp",
   "type": "module",