nftdata-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nomad07
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# nftdata-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Tool
+
+### `get_collection_data`
+
+Returns OpenSea collection market data in one call.
+
+| Parameter    | Type   | Description                                                                 |
+|--------------|--------|-----------------------------------------------------------------------------|
+| `collection` | string | OpenSea collection slug, from `opensea.io/collection/<slug>` (e.g. `azuki`) |
+
+Returned fields: `name`, `slug`, `contracts`, `floor_price`, `floor_price_currency`, `one_day_sales`, `one_day_volume`, `seven_day_sales`, `seven_day_volume`, `thirty_day_sales`, `thirty_day_volume`, `total_sales`, `total_volume`, `num_owners`, `total_supply`, `created_date`. Volume and price currencies are given in the matching `*_currency` fields (ETH, USDC, HYPE, ...).
+
+Each call costs **$0.002** (USDC on Base, paid via x402).
+
+## Requirements
+
+- Node.js 20+
+- A wallet private key funded with a small amount of USDC on Base
+
+> Use a dedicated wallet with only a small balance. Never use your main wallet.
+
+## 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
+{
+  "mcpServers": {
+    "nftdata": {
+      "command": "npx",
+      "args": ["-y", "nftdata-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+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
+npm install
+```
+
+Set the key for the current shell session only, then start:
+
+```bash
+# macOS / Linux
+export EVM_PRIVATE_KEY=0x...
+npm start
+```
+
+```powershell
+# Windows PowerShell
+$env:EVM_PRIVATE_KEY = "0x..."
+npm start
+```
+
+```bat
+:: Windows cmd
+set EVM_PRIVATE_KEY=0x...
+npm start
+```
+
+The server waits for an MCP client on stdin, so running it by hand just shows no output; it is meant to be launched by an MCP client.
+
+To use a local checkout with Claude Desktop, point `args` to `["tsx", "/absolute/path/to/nftdata-mcp/server.ts"]` with `"command": "npx"`.
+
+## Build
+
+```bash
+npm run build   # compiles server.ts and lib.ts to dist/
+npm test        # offline unit tests, no network and no payments
+```
+
+## Configuration
+
+| Variable               | Required | Default | Description |
+|------------------------|----------|---------|-------------|
+| `EVM_PRIVATE_KEY`      | yes      | –       | Private key (`0x` + 64 hex chars) of the wallet that pays for calls |
+| `NFTDATA_MAX_REQUESTS` | no       | `100`   | Max signed payments per session. Integer 1–1000; any other value stops startup with an error |
+| `NFTDATA_TIMEOUT_MS`   | no       | `15000` | Request timeout in milliseconds (1000–60000) |
+| `NFTDATA_URL`          | no       | `https://www.nftdata.app/api/get-collection-data` | Accepts only the official NFT Data endpoint (`www.nftdata.app` or `nftdata.app`); anything else stops startup |
+
+## Behavior
+
+- 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.
+- 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.
+- Returns generic errors for `400` (invalid slug), `404` (collection not found), `429` (rate limit, with `Retry-After`), timeouts and other failures; server and payment details are not passed to the MCP client.
+
+## Limitations
+
+- Only x402 on Base is supported. Solana and MPP payment methods are not implemented in this wrapper.
+- The expected recipient address is hardcoded in `lib.ts`. If the NFT Data payout address ever changes, update `OFFICIAL_PAY_TO` and release a new version.
+- The payment hook (`server.ts`) depends on the installed `@x402/*` SDK and is not covered by the offline tests.
+- The x402 client libraries change quickly; if imports fail, check the current [x402 docs](https://docs.x402.org/).
+
+## API reference
+
+- OpenAPI: https://www.nftdata.app/openapi.json
+- Docs: https://www.nftdata.app/docs

package/dist/lib.js

@@ -0,0 +1,203 @@
+// Pure logic for nftdata-mcp. No imports from the x402 SDK so it can be tested offline,
+// without network access and without spending anything.
+export const OFFICIAL_ENDPOINT = "https://www.nftdata.app/api/get-collection-data";
+const ALLOWED_ENDPOINTS = new Set([OFFICIAL_ENDPOINT, "https://nftdata.app/api/get-collection-data"]);
+// Base mainnet, USDC (6 decimals). Price is $0.002 = exactly 2000 atomic units.
+export const BASE_MAINNET = "eip155:8453";
+export const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const EXACT_AMOUNT_ATOMIC = 2000n;
+// Official NFT Data payment recipient on Base (lowercase for comparison).
+export const OFFICIAL_PAY_TO = "0x344143199642e87320785823c20c2df107d17534";
+export const MAX_REQUESTS_CEILING = 1000;
+export const DEFAULT_MAX_REQUESTS = 100;
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const CACHE_TTL_MS = 5 * 60 * 1000;
+const CACHE_MAX_ENTRIES = 500;
+function parseIntStrict(name, raw, min, max) {
+    if (!/^\d+$/.test(raw.trim())) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}`);
+    }
+    const n = Number(raw.trim());
+    if (!Number.isSafeInteger(n) || n < min || n > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}`);
+    }
+    return n;
+}
+// NFTDATA_URL is an untrusted override: only the official endpoint is accepted.
+export function resolveEndpoint(override) {
+    if (override === undefined || override.trim() === "")
+        return OFFICIAL_ENDPOINT;
+    let normalized;
+    try {
+        const u = new URL(override.trim());
+        normalized = `${u.protocol}//${u.host}${u.pathname}`;
+        if (u.username || u.password || u.search || u.hash)
+            throw new Error("extra URL parts");
+    }
+    catch {
+        throw new Error("NFTDATA_URL is not an accepted NFT Data endpoint");
+    }
+    if (!ALLOWED_ENDPOINTS.has(normalized)) {
+        throw new Error("NFTDATA_URL is not an accepted NFT Data endpoint");
+    }
+    return normalized;
+}
+export function parseConfig(env) {
+    const maxRaw = env.NFTDATA_MAX_REQUESTS;
+    const timeoutRaw = env.NFTDATA_TIMEOUT_MS;
+    return {
+        endpoint: resolveEndpoint(env.NFTDATA_URL),
+        maxRequests: maxRaw === undefined || maxRaw.trim() === ""
+            ? DEFAULT_MAX_REQUESTS
+            : parseIntStrict("NFTDATA_MAX_REQUESTS", maxRaw, 1, MAX_REQUESTS_CEILING),
+        timeoutMs: timeoutRaw === undefined || timeoutRaw.trim() === ""
+            ? DEFAULT_TIMEOUT_MS
+            : parseIntStrict("NFTDATA_TIMEOUT_MS", timeoutRaw, 1000, 60_000),
+    };
+}
+export function isValidPrivateKey(pk) {
+    return typeof pk === "string" && /^0x[0-9a-fA-F]{64}$/.test(pk);
+}
+// Trim + lowercase, then validate. Returns null if the slug is not acceptable.
+export function normalizeSlug(input) {
+    const s = input.trim().toLowerCase();
+    if (s.length === 0 || s.length > 100)
+        return null;
+    return /^[a-z0-9][a-z0-9_-]*$/.test(s) ? s : null;
+}
+// Returns a refusal reason, or null if the challenge is acceptable.
+export function validateRequirements(req) {
+    if (req.scheme !== "exact")
+        return "unexpected payment scheme";
+    if (req.network !== BASE_MAINNET)
+        return "unexpected payment network";
+    if (typeof req.asset !== "string" || req.asset.toLowerCase() !== USDC_BASE.toLowerCase()) {
+        return "unexpected payment token";
+    }
+    if (typeof req.amount !== "string" || !/^\d+$/.test(req.amount))
+        return "invalid payment amount";
+    if (BigInt(req.amount) !== EXACT_AMOUNT_ATOMIC)
+        return "payment amount does not match the expected price";
+    if (typeof req.payTo !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(req.payTo)) {
+        return "invalid payment recipient";
+    }
+    if (req.payTo.toLowerCase() !== OFFICIAL_PAY_TO)
+        return "unexpected payment recipient";
+    return null;
+}
+// Counts signed payments. Reserve before signing, release if signing fails.
+export class SpendLimiter {
+    reserved = 0;
+    max;
+    constructor(max) {
+        this.max = max;
+    }
+    tryReserve() {
+        if (this.reserved >= this.max)
+            return false;
+        this.reserved++;
+        return true;
+    }
+    release() {
+        if (this.reserved > 0)
+            this.reserved--;
+    }
+    get used() {
+        return this.reserved;
+    }
+}
+export const ok = (text) => ({ content: [{ type: "text", text }] });
+export const fail = (text) => ({ isError: true, content: [{ type: "text", text }] });
+// Cache (5 min per slug) + reuse of in-flight requests so concurrent identical calls
+// produce a single (paid) request. Failures are never cached.
+export class CachedFetcher {
+    cache = new Map();
+    inflight = new Map();
+    load;
+    now;
+    constructor(load, now = Date.now) {
+        this.load = load;
+        this.now = now;
+    }
+    async get(slug) {
+        const hit = this.cache.get(slug);
+        if (hit && this.now() - hit.at < CACHE_TTL_MS)
+            return ok(hit.body);
+        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) {
+                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 });
+            }
+            return res;
+        })
+            .finally(() => {
+            this.inflight.delete(slug);
+        });
+        this.inflight.set(slug, p);
+        return p;
+    }
+}
+// Marker used so refusals raised by our own payment hook can be told apart from other errors.
+export const REFUSAL_PREFIX = "nftdata-mcp policy: ";
+export class TimeoutError extends Error {
+}
+export function withTimeout(run, ms) {
+    const ctrl = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            ctrl.abort();
+            reject(new TimeoutError("timeout"));
+        }, ms);
+    });
+    return Promise.race([run(ctrl.signal), timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+// Maps an HTTP response to a tool result without leaking server or payment details.
+export function mapResponse(status, body, retryAfter) {
+    if (status >= 200 && status < 300) {
+        try {
+            JSON.parse(body);
+        }
+        catch {
+            return fail("The NFT Data API returned an unreadable response.");
+        }
+        return ok(body);
+    }
+    if (status === 400)
+        return fail("Invalid collection slug.");
+    if (status === 404)
+        return fail("Collection not found. Check the slug in the OpenSea collection URL.");
+    if (status === 429) {
+        const secs = retryAfter && /^\d{1,5}$/.test(retryAfter) ? retryAfter : "a few";
+        return fail(`Rate limit exceeded. Retry in ${secs} seconds.`);
+    }
+    if (status === 402)
+        return fail("Payment was not accepted by the NFT Data API.");
+    return fail(`The NFT Data API returned an error (HTTP ${status}).`);
+}
+// Maps a thrown error to a safe message. Never includes err.message of unknown errors.
+export function mapError(err) {
+    if (err instanceof TimeoutError) {
+        return fail("The request timed out. A payment may have been authorized; it was not retried automatically.");
+    }
+    const msg = err instanceof Error ? err.message : "";
+    const i = msg.indexOf(REFUSAL_PREFIX);
+    if (i >= 0) {
+        const reason = msg.slice(i + REFUSAL_PREFIX.length).split(/[\n.]/)[0].slice(0, 120);
+        return fail(`Payment refused by safety policy: ${reason}.`);
+    }
+    return fail("The request failed.");
+}

package/dist/server.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+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 { 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";
+let config;
+try {
+    config = parseConfig(process.env);
+}
+catch (e) {
+    console.error(`Configuration error: ${e.message}`);
+    process.exit(1);
+}
+// Never print or echo the key itself, only whether it has the right shape.
+const pk = process.env.EVM_PRIVATE_KEY?.trim();
+if (!isValidPrivateKey(pk)) {
+    console.error("EVM_PRIVATE_KEY is missing or malformed (expected 0x followed by 64 hex characters; wallet with USDC on Base).");
+    process.exit(1);
+}
+let account;
+try {
+    account = privateKeyToAccount(pk);
+}
+catch {
+    console.error("EVM_PRIVATE_KEY could not be used to create a wallet.");
+    process.exit(1);
+}
+const limiter = new SpendLimiter(config.maxRequests);
+// Only Base mainnet is registered (no "eip155:*" wildcard), so challenges for other
+// EVM networks are rejected before this hook runs: selectPaymentRequirements throws
+// when no registered network/scheme matches, so the hook only fires for eip155:8453.
+// The hook re-checks the selected requirements against our policy before signing.
+//
+// ctx.selectedRequirements is the SDK's PaymentRequirements type:
+//   { scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra }
+// validateRequirements reads scheme/network/asset/amount/payTo — matching that shape.
+const client = new x402Client();
+client.register(BASE_MAINNET, new ExactEvmScheme(account));
+client
+    .onBeforePaymentCreation(async (ctx) => {
+    // Validate all four payment fields before the wallet signs anything.
+    const reason = validateRequirements(ctx.selectedRequirements);
+    if (reason)
+        return { abort: true, reason: `${REFUSAL_PREFIX}${reason}` };
+    // Reserve a slot against the per-session payment limit.
+    if (!limiter.tryReserve()) {
+        return {
+            abort: true,
+            reason: `${REFUSAL_PREFIX}paid request limit (${config.maxRequests}) for this session reached`,
+        };
+    }
+})
+    .onPaymentCreationFailure(async () => {
+    // Signing failed after the slot was reserved; release it so the counter stays accurate.
+    limiter.release();
+});
+// onPaymentResponse is intentionally NOT registered.  The SDK uses it to drive a
+// recovery-retry path (wrapFetchWithPayment calls createPaymentPayload a second time
+// when a hook returns { recovered: true }).  Leaving it unregistered ensures at most
+// one payment-creation attempt per tool call, which is this server's "no retries" policy.
+const payFetch = wrapFetchWithPayment(fetch, client);
+async function load(slug) {
+    try {
+        // No automatic retries: one tool call is at most one payment attempt.
+        const res = await withTimeout(async (signal) => {
+            const r = await payFetch(config.endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ collection: slug }),
+                redirect: "error",
+                signal,
+            });
+            return { status: r.status, body: await r.text(), retryAfter: r.headers.get("Retry-After") };
+        }, config.timeoutMs);
+        return mapResponse(res.status, res.body, res.retryAfter);
+    }
+    catch (e) {
+        return mapError(e);
+    }
+}
+const fetcher = new CachedFetcher(load);
+const server = new McpServer({ name: "nftdata", version: "1.0.0" });
+server.tool("get_collection_data", "Get OpenSea NFT collection market data in one call: name, contracts, floor price, " +
+    "1/7/30-day and lifetime sales and volume, unique owners, total supply, creation date. " +
+    "Costs $0.002 per call (x402). " +
+    "`collection` is the OpenSea slug from the collection URL: opensea.io/collection/<slug> " +
+    "(e.g. 'azuki', 'basedpunks'); it is trimmed and lowercased. " +
+    "Prices are in the currency given in the *_currency fields (ETH, USDC, HYPE...).", {
+    collection: z.string().max(200).describe("OpenSea collection slug, e.g. 'azuki'"),
+}, async ({ collection }) => {
+    const slug = normalizeSlug(collection);
+    if (slug === null) {
+        return fail("Invalid slug: use only letters, digits, '_' and '-' (max 100 characters).");
+    }
+    return fetcher.get(slug);
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "nftdata-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nomad07/nftdata-mcp.git"
+  },
+  "bin": {
+    "nftdata-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx server.ts",
+    "test": "tsx --test lib.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@x402/evm": "^2.5.0",
+    "@x402/fetch": "^2.5.0",
+    "viem": "^2.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  }
+}