wickedapi-mcp 0.3.0 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 WickedAPI
+Copyright (c) 2026 choaticpixels
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,10 +17,14 @@ MCP server for the whole [Wicked](https://wickedapi.com) suite — trading data,
 | [Wicked Memory](https://memory.wickedapi.com) | 8 (`memory_prepare`, `memory_store`, `memory_search`, …) | wallet signature on every call; only search is metered |
 | [x402 Paywall](https://paywall.wickedapi.com) | 8 (`paywall_*`) | `paywall_signup` is open; the rest need the tenant key |
 
-Plus **6 resources** (the platform directory, `llms.txt`, and each service's live endpoint catalog) and **3 prompts** (`rug_check`, `vet_dependency`, `morning_briefing`) that chain tools together the way the [cookbook](../cookbooks/wickedapi-cookbook.md) does.
+Plus **6 resources** (the platform directory, `llms.txt`, and each service's live endpoint catalog) and **7 prompts** (`rug_check`, `vet_dependency`, `morning_briefing`, `fact_check`, `verify_agent`, `find_reliable_tool`, `agent_memory_guide`) that chain tools together the way the [cookbook](../cookbooks/wickedapi-cookbook.md) does.
 
 These tools never sign anything or hold a key. Identity, Registry registration and Memory take a signature you produce with your own wallet (`identity_get_nonce` / `memory_prepare` return the exact message to sign). Calls that need x402 payment return the real `402` challenge (decoded under `payment_required` for x402 v2) rather than auto-paying — `WICKEDAPI_PAYER_PRIVATE_KEY` auto-pay applies to the Trading, Protocol Health, Token Risk and Broker Sync tools.
 
+## Remote endpoint (no install)
+
+The same 70 tools are served over streamable HTTP at **`https://mcp.wickedapi.com/mcp`** (stateless, rate-limited per IP; the public deployment carries no personal keys, so paid calls return the x402 challenge). Point any streamable-HTTP MCP client at it. To self-host, build the `Dockerfile` (or `npm run build && npm run start:http`); see `.env.example` for `RATE_LIMIT_PER_MINUTE`, `ALLOWED_HOSTS` and `TRUSTED_CLIENT_IP_HEADER`.
+
 ## No signup required
 
 Every tool hits a real endpoint gated by [x402](https://x402.org) (HTTP-native pay-per-call, USDC on Base) with an API-key fallback — and the Token Risk Oracle tool is free no matter what:
@@ -71,6 +75,15 @@ Read without calling a tool — useful for a client that surfaces resources in i
 - `wickedapi://platform/llms` — the platform's `llms.txt`
 - `wickedapi://trading/status`, `wickedapi://protocol_health/status`, `wickedapi://token_risk/status`, `wickedapi://broker_sync/status` — each service's live endpoint catalog
 
+## Quick start
+
+```bash
+claude mcp add --transport http wicked https://mcp.wickedapi.com/mcp   # Claude Code, no install
+npx -y wickedapi-mcp                                                    # local stdio
+```
+
+Claude Desktop / Cursor / VS Code config and per-framework starters: see the [cookbooks](https://github.com/choaticpixels/api_services/tree/main/cookbooks). The remote also serves a landing page at `/`, `/llms.txt`, an MCP server card at `/.well-known/mcp/server-card.json`, and aggregate per-tool call counts at `/stats` (counts only; no arguments or IPs).
+
 ## Prompts
 
 One-click workflows that chain real tool calls (Claude Desktop and other prompt-aware clients surface these directly):
@@ -78,6 +91,10 @@ One-click workflows that chain real tool calls (Claude Desktop and other prompt-
 - **`rug_check`** (`address`, `chain`, optional `symbol`) — token risk check + market sentiment + optional momentum read, before buying.
 - **`vet_dependency`** (`slug`, optional `token_address`, `chain`) — protocol health + optional contract-level risk check, before building on a DeFi protocol.
 - **`morning_briefing`** (optional `symbol`) — macro calendar + earnings calendar + sentiment + momentum verdict, as one digest.
+- **`fact_check`** (`output`, optional `source`) — split an answer into claims and verify each with Wicked Sanity.
+- **`verify_agent`** (`wallet`) — Identity assertion + Reputation stake/tier before you transact with an agent.
+- **`find_reliable_tool`** (`need`, optional `category`, `min_score`) — Registry search by real uptime/latency/schema scores.
+- **`agent_memory_guide`** (`wallet`, `task`) — the two-step signed Memory flow, explained to the model.
 
 ## Environment variables
 
@@ -100,8 +117,9 @@ If neither `WICKEDAPI_API_KEY` nor `WICKEDAPI_PAYER_PRIVATE_KEY` is set, paid ca
 
 ```bash
 npm install
-npm run build
-node dist/index.js
+npm test            # builds, then unit + end-to-end tests (e2e needs network)
+node dist/index.js  # stdio
+node dist/http.js   # streamable HTTP on $PORT (default 8080)
 ```
 
 ## What this is not

package/dist/clientIp.js

@@ -0,0 +1,67 @@
+// Who is calling, for rate limiting. Ported from the Python http_app.py so
+// behaviour is unchanged after the cutover.
+//
+// Behind Railway's edge proxy the TCP peer is always an internal address, so
+// the limiter keys on the proxy-set X-Real-IP header instead. That is only
+// safe because the proxy sets the header itself; set TRUSTED_CLIENT_IP_HEADER
+// to empty to fall back to the TCP peer when running without a proxy, or to
+// cf-connecting-ip if the domain is ever proxied through Cloudflare.
+import { isIP } from "node:net";
+const TRUSTED_HEADER = (process.env.TRUSTED_CLIENT_IP_HEADER ?? "x-real-ip").trim().toLowerCase();
+function expandIPv6(ip) {
+    let s = ip.split("%")[0];
+    let tail = [];
+    const v4 = s.match(/(\d+\.\d+\.\d+\.\d+)$/);
+    if (v4) {
+        const o = v4[1].split(".").map(Number);
+        tail = [(o[0] << 8) | o[1], (o[2] << 8) | o[3]];
+        s = s.slice(0, -v4[1].length) + "0:0";
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const rest = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const fill = 8 - head.length - rest.length;
+    if ((halves.length === 1 && fill !== 0) || fill < 0)
+        return null;
+    const groups = [...head, ...Array(halves.length === 2 ? fill : 0).fill("0"), ...rest].map((g) => parseInt(g, 16));
+    if (groups.length !== 8 || groups.some((g) => Number.isNaN(g)))
+        return null;
+    if (tail.length) {
+        groups[6] = tail[0];
+        groups[7] = tail[1];
+    }
+    return groups;
+}
+/** Canonical rate-limit key, or null if `raw` isn't an IP. IPv4-mapped IPv6
+ *  collapses to the IPv4 address; IPv6 is grouped by /64 so rotating addresses
+ *  inside one prefix can't dodge the limit. */
+export function normalizeIp(raw) {
+    const s = raw.trim();
+    const kind = isIP(s);
+    if (kind === 4)
+        return s;
+    if (kind !== 6)
+        return null;
+    const g = expandIPv6(s);
+    if (!g)
+        return null;
+    if (g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff) {
+        return `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+    }
+    return `${g.slice(0, 4).map((x) => x.toString(16)).join(":")}::/64`;
+}
+export function clientKey(req) {
+    if (TRUSTED_HEADER) {
+        const raw = req.headers[TRUSTED_HEADER];
+        const value = Array.isArray(raw) ? raw[0] : raw;
+        if (value) {
+            const key = normalizeIp(value);
+            if (key)
+                return key;
+        }
+    }
+    const peer = req.socket.remoteAddress ?? "unknown";
+    return normalizeIp(peer) ?? peer;
+}

package/dist/http.js

@@ -0,0 +1,100 @@
+// Streamable-HTTP entry point for the public remote at https://mcp.wickedapi.com/mcp.
+// Stateless: every request gets its own McpServer + transport (specs are
+// loaded once at boot), so it scales and restarts without session loss.
+// Public-endpoint additions over the stdio build: a per-IP rate limit and a
+// Host allowlist (DNS-rebinding protection). Tools and upstream calls are
+// identical.
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { clientKey } from "./clientIp.js";
+import { rateLimited } from "./rateLimit.js";
+import { landingHtml, llmsTxt, serverCard } from "./landing.js";
+import { knownTools, usageHooks, usageSnapshot } from "./usage.js";
+import { buildServer, loadWorld, SERVER_VERSION } from "./server.js";
+const PORT = Number(process.env.PORT || 8080);
+const RATE_LIMIT_PER_MINUTE = Number(process.env.RATE_LIMIT_PER_MINUTE || 30);
+const MAX_BODY_BYTES = 1_000_000;
+const ALLOWED_HOSTS = (process.env.ALLOWED_HOSTS || "mcp.wickedapi.com,wicked-mcp-production.up.railway.app,localhost:8080,127.0.0.1:8080")
+    .split(",")
+    .map((h) => h.trim().toLowerCase())
+    .filter(Boolean);
+function send(res, status, body, headers = {}) {
+    res.writeHead(status, { "content-type": "application/json", ...headers });
+    res.end(JSON.stringify(body));
+}
+function sendText(res, contentType, body) {
+    res.writeHead(200, { "content-type": `${contentType}; charset=utf-8`, "cache-control": "public, max-age=300" });
+    res.end(body);
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw Object.assign(new Error("payload too large"), { status: 413 });
+        chunks.push(chunk);
+    }
+    if (!chunks.length)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw Object.assign(new Error("invalid JSON"), { status: 400 });
+    }
+}
+async function main() {
+    const world = await loadWorld();
+    const { summary } = buildServer(world, { onRegister: usageHooks.onRegister });
+    const tools = [...knownTools];
+    const http = createServer(async (req, res) => {
+        const url = new URL(req.url || "/", "http://x");
+        if (url.pathname === "/health")
+            return send(res, 200, { status: "ok", version: SERVER_VERSION });
+        const host = (req.headers.host || "").toLowerCase();
+        if (!ALLOWED_HOSTS.includes(host))
+            return send(res, 421, { error: "Invalid Host header" });
+        if (req.method === "GET" || req.method === "HEAD") {
+            if (url.pathname === "/")
+                return sendText(res, "text/html", landingHtml(tools, SERVER_VERSION));
+            if (url.pathname === "/llms.txt")
+                return sendText(res, "text/plain", llmsTxt(tools, SERVER_VERSION));
+            if (url.pathname === "/.well-known/mcp/server-card.json" || url.pathname === "/.well-known/mcp.json") {
+                return send(res, 200, serverCard(tools, SERVER_VERSION), { "cache-control": "public, max-age=300" });
+            }
+            if (url.pathname === "/stats")
+                return send(res, 200, usageSnapshot());
+        }
+        if (url.pathname !== "/mcp")
+            return send(res, 404, { error: "Not found. The MCP endpoint is /mcp." });
+        if (req.method !== "POST") {
+            return send(res, 405, { jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed (stateless server: POST only)." }, id: null }, { allow: "POST" });
+        }
+        if (rateLimited(clientKey(req), RATE_LIMIT_PER_MINUTE)) {
+            return send(res, 429, { error: `Rate limit exceeded: ${RATE_LIMIT_PER_MINUTE} requests/minute per IP. Run this server locally (npx wickedapi-mcp) for unlimited use.` }, { "retry-after": "60" });
+        }
+        try {
+            const body = await readJson(req);
+            const { server } = buildServer(world, usageHooks);
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on("close", () => {
+                void transport.close();
+                void server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            const status = err.status ?? 500;
+            if (!res.headersSent) {
+                send(res, status, { jsonrpc: "2.0", error: { code: -32603, message: err.message }, id: null });
+            }
+        }
+    });
+    http.listen(PORT, "0.0.0.0", () => console.error(`[wickedapi-mcp] http on :${PORT}/mcp - ${summary}.`));
+}
+main().catch((err) => {
+    console.error("[wickedapi-mcp] fatal:", err);
+    process.exit(1);
+});

package/dist/index.js

@@ -1,330 +1,11 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+// stdio entry point: `npx wickedapi-mcp` for Claude Desktop, Cursor, .mcpb, etc.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { registerSuiteTools } from "./suite.js";
-function envUrl(name, fallback) {
-    return (process.env[name] || fallback).replace(/\/$/, "");
-}
-const SERVICES = [
-    { id: "trading", name: "Trading Data API", baseUrl: envUrl("WICKEDAPI_BASE_URL", "https://api.wickedapi.com") },
-    { id: "protocol_health", name: "Protocol Health Oracle", baseUrl: envUrl("WICKEDAPI_PROTOCOL_HEALTH_URL", "https://protocol-health-oracle.wickedapi.com") },
-    { id: "token_risk", name: "Token Risk Oracle", baseUrl: envUrl("WICKEDAPI_TOKEN_RISK_URL", "https://token-risk-oracle.wickedapi.com") },
-    { id: "broker_sync", name: "Broker Sync API", baseUrl: envUrl("WICKEDAPI_BROKER_SYNC_URL", "https://broker-sync-api.wickedapi.com") },
-];
-const SHOWCASE_URL = envUrl("WICKEDAPI_SHOWCASE_URL", "https://wickedapi.com");
-const API_KEY = process.env.WICKEDAPI_API_KEY;
-const PAYER_KEY = process.env.WICKEDAPI_PAYER_PRIVATE_KEY;
-// A few auto-generated tool names collide or read badly (e.g. GET and POST
-// both hitting /v1/protocols) — override just those, keyed by
-// "METHOD /openapi/path/{param}".
-const TOOL_NAME_OVERRIDES = {
-    protocol_health: {
-        "GET /v1/protocols": "protocol_health_list_protocols",
-        "POST /v1/protocols": "protocol_health_track_protocol",
-        "GET /v1/health/{slug}": "protocol_health_score",
-        "POST /v1/refresh": "protocol_health_refresh_all",
-        "POST /v1/ingest": "protocol_health_sync_universe",
-    },
-    broker_sync: {
-        "POST /v1/users": "broker_sync_register_user",
-    },
-};
-// If a funded Base-mainnet wallet key is provided, every call auto-pays the
-// x402 402 challenge in USDC — no API key or signup needed at all. Loaded
-// lazily so a plain API-key setup never has to pull in viem/x402-fetch.
-async function buildFetcher() {
-    if (!PAYER_KEY)
-        return fetch;
-    let deps;
-    try {
-        deps = await Promise.all([import("viem"), import("viem/accounts"), import("viem/chains"), import("x402-fetch")]);
-    }
-    catch {
-        console.error("[wickedapi-mcp] WICKEDAPI_PAYER_PRIVATE_KEY is set, but the wallet-payment dependencies " +
-            "(viem, x402-fetch) aren't installed in this distribution. Falling back to plain fetch — " +
-            "calls without an API key will surface the 402 challenge instead of auto-paying. " +
-            "Use `npx wickedapi-mcp` for full auto-pay support.");
-        return fetch;
-    }
-    const [{ createWalletClient, http }, { privateKeyToAccount }, { base }, { wrapFetchWithPayment }] = deps;
-    const account = privateKeyToAccount(PAYER_KEY);
-    const wallet = createWalletClient({ account, chain: base, transport: http() });
-    console.error(`[wickedapi-mcp] x402 auto-pay enabled — wallet ${account.address}`);
-    // x402-fetch's Signer type expects a client extended with viem's public
-    // actions; the proven pattern in scripts/x402-bot-test.mjs passes a plain
-    // wallet client the same way — cast rather than pull in publicActions.
-    return wrapFetchWithPayment(fetch, wallet);
-}
-function pathSlug(openapiPath) {
-    return openapiPath
-        .replace(/^\/v1\//, "")
-        .replace(/[{}]/g, "")
-        .replace(/[\/\-]+/g, "_");
-}
-function toolNameFor(service, method, openapiPath) {
-    const override = TOOL_NAME_OVERRIDES[service.id]?.[`${method.toUpperCase()} ${openapiPath}`];
-    if (override)
-        return override;
-    const slug = pathSlug(openapiPath);
-    if (service.id === "trading")
-        return slug; // legacy naming, already published
-    return slug === service.id ? service.id : `${service.id}_${slug}`;
-}
-function zodFor(p) {
-    const base = p.type === "number" || p.type === "integer"
-        ? z.coerce.number()
-        : p.type === "boolean"
-            ? z.coerce.boolean()
-            : z.string();
-    const described = p.description ? base.describe(p.description) : base;
-    return p.required ? described : described.optional();
-}
-async function loadServiceSpec(service) {
-    try {
-        const res = await fetch(`${service.baseUrl}/openapi.json`);
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-        return (await res.json());
-    }
-    catch (err) {
-        console.error(`[wickedapi-mcp] WARNING: couldn't load ${service.name} spec (${service.baseUrl}/openapi.json): ` +
-            `${err.message} — its tools are unavailable this session, the rest load normally.`);
-        return null;
-    }
-}
-function registerServiceTools(server, service, doc, doFetch) {
-    let registered = 0;
-    for (const [openapiPath, methods] of Object.entries(doc.paths)) {
-        if (!openapiPath.startsWith("/v1/") || openapiPath === "/v1/status")
-            continue; // /v1/status is a resource instead
-        if (openapiPath.includes("webhook"))
-            continue; // called by a third party, never by an agent
-        for (const [method, op] of Object.entries(methods)) {
-            const pathParamNames = [];
-            const queryParamNames = [];
-            const bodyPropNames = [];
-            const shape = {};
-            for (const p of op.parameters ?? []) {
-                if (p.in === "path") {
-                    pathParamNames.push(p.name);
-                    shape[p.name] = zodFor({ type: p.schema?.type, required: true, description: p.description });
-                }
-                else if (p.in === "query") {
-                    queryParamNames.push(p.name);
-                    shape[p.name] = zodFor({ type: p.schema?.type, required: p.required, description: p.description });
-                }
-            }
-            const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
-            if (bodySchema) {
-                const required = new Set(bodySchema.required ?? []);
-                for (const [name, prop] of Object.entries(bodySchema.properties ?? {})) {
-                    bodyPropNames.push(name);
-                    shape[name] = zodFor({ type: prop.type, required: required.has(name), description: prop.description });
-                }
-            }
-            const name = toolNameFor(service, method, openapiPath);
-            server.registerTool(name, {
-                description: `[${service.name}] ${[op.summary, op.description].filter(Boolean).join(" — ")}`.slice(0, 1000),
-                inputSchema: shape,
-            }, async (args) => {
-                let urlPath = openapiPath;
-                for (const p of pathParamNames)
-                    urlPath = urlPath.replace(`{${p}}`, encodeURIComponent(String(args[p])));
-                const url = new URL(service.baseUrl + urlPath);
-                for (const p of queryParamNames) {
-                    const v = args[p];
-                    if (v !== undefined && v !== null)
-                        url.searchParams.set(p, String(v));
-                }
-                const headers = {};
-                if (API_KEY)
-                    headers["x-api-key"] = API_KEY;
-                const init = { method: method.toUpperCase(), headers };
-                if (bodyPropNames.length) {
-                    const bodyObj = {};
-                    for (const p of bodyPropNames)
-                        if (args[p] !== undefined)
-                            bodyObj[p] = args[p];
-                    headers["content-type"] = "application/json";
-                    init.body = JSON.stringify(bodyObj);
-                }
-                const r = await doFetch(url.toString(), init);
-                const text = await r.text();
-                let body;
-                try {
-                    body = JSON.parse(text);
-                }
-                catch {
-                    body = text;
-                }
-                return {
-                    isError: !r.ok,
-                    content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
-                };
-            });
-            registered++;
-        }
-    }
-    return registered;
-}
-// --- Resources -----------------------------------------------------------
-// Reference material an agent can read without invoking a tool: the
-// platform-wide directory/llms.txt, and each service's live endpoint
-// catalog (the /v1/status we deliberately excluded from becoming a tool).
-function registerResources(server) {
-    server.registerResource("platform-services", "wickedapi://platform/services", {
-        title: "WickedAPI service directory",
-        description: "Every live WickedAPI service — URL, category, one-line description, auth modes, and links to each one's own OpenAPI spec/docs/llms.txt.",
-        mimeType: "application/json",
-    }, async (uri) => {
-        const r = await fetch(`${SHOWCASE_URL}/services.json`);
-        if (!r.ok)
-            throw new Error(`Failed to load service directory: HTTP ${r.status}`);
-        return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
-    });
-    server.registerResource("platform-llms-txt", "wickedapi://platform/llms", {
-        title: "WickedAPI llms.txt",
-        description: "Terse, platform-wide summary for agents deciding what to call — auth modes, free vs. paid endpoints.",
-        mimeType: "text/plain",
-    }, async (uri) => {
-        const r = await fetch(`${SHOWCASE_URL}/llms.txt`);
-        if (!r.ok)
-            throw new Error(`Failed to load llms.txt: HTTP ${r.status}`);
-        return { contents: [{ uri: uri.toString(), mimeType: "text/plain", text: await r.text() }] };
-    });
-    for (const service of SERVICES) {
-        server.registerResource(`${service.id}-status`, `wickedapi://${service.id}/status`, {
-            title: `${service.name} — live catalog`,
-            description: `Live endpoint catalog for ${service.name} (${service.baseUrl}), fetched fresh on every read.`,
-            mimeType: "application/json",
-        }, async (uri) => {
-            const r = await fetch(`${service.baseUrl}/v1/status`);
-            if (!r.ok)
-                throw new Error(`Failed to load ${service.name} status: HTTP ${r.status}`);
-            return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
-        });
-    }
-}
-// --- Prompts ---------------------------------------------------------------
-// The "compound recipes" from the WickedAPI cookbook, turned into one-click
-// prompts: each just tells the assistant which real tools to call and how
-// to read the results — no fabricated synthesis, every number cited comes
-// from an actual tool call made during the conversation.
-function registerPrompts(server) {
-    server.registerPrompt("rug_check", {
-        title: "Rug-check before buying",
-        description: "Real on-chain risk signals for a token contract, plus market sentiment (and momentum, if it's a covered asset) before you decide whether to buy.",
-        argsSchema: {
-            address: z.string().describe("The token contract address (EVM) or mint address (Solana)."),
-            chain: z.string().describe("ethereum, bsc, base, polygon, arbitrum, optimism, avalanche, fantom, zksync, linea, scroll, or solana."),
-            symbol: z.string().optional().describe("If this token maps to a covered momentum-score asset (BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA), pass it to also pull a real momentum verdict."),
-        },
-    }, ({ address, chain, symbol }) => ({
-        description: "Rug-check workflow",
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Before I consider buying this token, run a real risk check — don't guess or assume anything:\n\n` +
-                        `1. Call the \`token_risk\` tool with address="${address}" and chain="${chain}". Report the exact ` +
-                        `risk_score, risk_tier, and every real flag it returns (honeypot, mint/ownership authority, holder ` +
-                        `and LP concentration, buy/sell tax, trust-list status) — cite the actual values, don't summarize ` +
-                        `away the specifics or invent ones that weren't returned.\n` +
-                        `2. Call the \`sentiment\` tool for the current overall crypto market mood.\n` +
-                        (symbol
-                            ? `3. Call the \`momentum_score\` tool with symbol="${symbol}" and timeframe="1h" for a real technical read.\n`
-                            : "") +
-                        `\nThen give a plain verdict: the real risk signals found (listed, not paraphrased), current market ` +
-                        `mood, and — only if applicable — the momentum read. State clearly this is aggregated real signals, ` +
-                        `never a safety guarantee.`,
-                },
-            },
-        ],
-    }));
-    server.registerPrompt("vet_dependency", {
-        title: "Vet a DeFi dependency",
-        description: "Protocol activity/treasury health plus an optional contract-level risk check, before you build on a DeFi protocol.",
-        argsSchema: {
-            slug: z.string().describe('The protocol\'s DefiLlama slug, e.g. "lido".'),
-            token_address: z.string().optional().describe("The protocol's token contract address, if you also want a contract-level risk check."),
-            chain: z.string().optional().describe("Chain for token_address (default ethereum)."),
-        },
-    }, ({ slug, token_address, chain }) => ({
-        description: "Dependency-vetting workflow",
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `Before I integrate this protocol as a dependency, check its real health — don't guess:\n\n` +
-                        `1. Call the \`protocol_health_score\` tool with slug="${slug}". Report the components (GitHub ` +
-                        `activity, TVL trend, treasury) exactly as returned, including any that came back null (never ` +
-                        `filled in).\n` +
-                        (token_address
-                            ? `2. Call the \`token_risk\` tool with address="${token_address}" and chain="${chain || "ethereum"}" ` +
-                                `for a contract-level check on its token.\n`
-                            : "") +
-                        `\nSummarize: is this protocol actively maintained, is its TVL trend healthy, and (if checked) does ` +
-                        `its token carry any real contract-level risk flags. Cite the real numbers.`,
-                },
-            },
-        ],
-    }));
-    server.registerPrompt("morning_briefing", {
-        title: "Morning briefing",
-        description: "One daily digest from macro calendar, earnings calendar, sentiment, and a momentum verdict — all free or a fraction of a cent.",
-        argsSchema: {
-            symbol: z.string().optional().describe("Asset for the momentum verdict (default BTC). One of BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA."),
-        },
-    }, ({ symbol }) => {
-        const sym = symbol || "BTC";
-        return {
-            description: "Morning briefing workflow",
-            messages: [
-                {
-                    role: "user",
-                    content: {
-                        type: "text",
-                        text: `Compile my morning briefing from real, current data — call each tool, don't estimate:\n\n` +
-                            `1. \`macro_calendar\` with days=7 — upcoming FOMC/CPI/jobs events.\n` +
-                            `2. \`earnings_calendar\` with days=3 — upcoming earnings reports.\n` +
-                            `3. \`sentiment\` — current crypto Fear & Greed reading.\n` +
-                            `4. \`momentum_score\` with symbol="${sym}" and timeframe="1D" — today's technical verdict.\n\n` +
-                            `Then write one concise digest combining all four, citing the real values from each call.`,
-                    },
-                },
-            ],
-        };
-    });
-}
+import { buildServer, loadWorld } from "./server.js";
 async function main() {
-    const server = new McpServer({ name: "wickedapi", version: "0.3.0" });
-    const doFetch = await buildFetcher();
-    let totalTools = 0;
-    const loaded = [];
-    for (const service of SERVICES) {
-        const doc = await loadServiceSpec(service);
-        if (!doc)
-            continue;
-        totalTools += registerServiceTools(server, service, doc, doFetch);
-        loaded.push(service.name);
-    }
-    if (totalTools === 0) {
-        throw new Error("No service specs loaded — check network access and WICKEDAPI_*_URL overrides.");
-    }
-    // Reputation, Registry, Identity, Sanity, Memory and Paywall use hand-written
-    // tools (non-/v1 paths, wallet-signature auth) — registered unconditionally.
-    const suiteTools = registerSuiteTools(server);
-    totalTools += suiteTools;
-    loaded.push("Reputation, Registry, Identity, Sanity, Memory, Paywall");
-    registerResources(server);
-    registerPrompts(server);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`[wickedapi-mcp] ready — ${totalTools} tools across ${loaded.length} service(s) (${loaded.join(", ")}), ` +
-        `${2 + SERVICES.length} resources, 3 prompts.`);
+    const { server, summary } = buildServer(await loadWorld());
+    await server.connect(new StdioServerTransport());
+    console.error(`[wickedapi-mcp] ready - ${summary}.`);
 }
 main().catch((err) => {
     console.error("[wickedapi-mcp] fatal:", err);

package/dist/landing.js

@@ -0,0 +1,96 @@
+// Discovery surfaces served by the HTTP deployment: a human landing page,
+// /llms.txt for crawlers and agents, and an MCP server card. All three are
+// generated from the tools actually registered, so they cannot drift from
+// what the server exposes.
+const SITE = "https://mcp.wickedapi.com";
+const GROUPS = [
+    { id: "protocol_health", label: "Protocol Health Oracle", prefix: "protocol_health_", blurb: "Score any DeFi protocol before you integrate it." },
+    { id: "token_risk", label: "Token Risk Oracle", prefix: "token_risk", blurb: "Free rug / honeypot check for EVM and Solana tokens." },
+    { id: "broker_sync", label: "Broker Sync", prefix: "broker_sync_", blurb: "Positions and balances across 30+ brokerages." },
+    { id: "reputation", label: "Wicked Reputation", prefix: "reputation_", blurb: "On-chain agent stake, tiers and slashing history. Free." },
+    { id: "registry", label: "Wicked Registry", prefix: "registry_", blurb: "Real uptime, latency and schema scores for x402/MCP tools." },
+    { id: "identity", label: "Wicked Identity", prefix: "identity_", blurb: "Know-Your-Agent verification with signed assertions." },
+    { id: "sanity", label: "Wicked Sanity", prefix: "sanity_", blurb: "Hallucination check against your source or live web evidence." },
+    { id: "memory", label: "Wicked Memory", prefix: "memory_", blurb: "Persistent, wallet-scoped agent memory with semantic search." },
+    { id: "paywall", label: "x402 Paywall", prefix: "paywall_", blurb: "Put any endpoint behind pay-per-call USDC." },
+];
+export const PROMPT_NAMES = ["rug_check", "vet_dependency", "morning_briefing", "fact_check", "verify_agent", "find_reliable_tool", "agent_memory_guide"];
+function grouped(tools) {
+    const claimed = new Set();
+    const out = GROUPS.map((g) => {
+        const names = tools.filter((t) => t.startsWith(g.prefix));
+        names.forEach((n) => claimed.add(n));
+        return { ...g, tools: names };
+    });
+    const trading = tools.filter((t) => !claimed.has(t));
+    return [{ id: "trading", label: "Trading Data API", blurb: "Prices, OHLCV, indicators, funding/OI, macro, prediction markets, momentum score.", tools: trading }, ...out];
+}
+export function llmsTxt(tools, version) {
+    const g = grouped(tools);
+    return [
+        "# Wicked MCP",
+        "",
+        `> One MCP server for the whole Wicked suite: ${tools.length} tools across ${g.length} services - market data, DeFi and token risk, brokerage sync, agent identity, reputation, tool registry, hallucination checks, persistent memory and x402 paywalls. Version ${version}.`,
+        "",
+        "## Connect",
+        `- Remote (streamable HTTP, no install): ${SITE}/mcp`,
+        "- Local (stdio): `npx -y wickedapi-mcp`",
+        "- Claude Code: `claude mcp add --transport http wicked " + SITE + "/mcp`",
+        "- No signup needed. Priced calls return a real x402 payment challenge (USDC on Base); set WICKEDAPI_API_KEY or a payer wallet locally for free-tier / auto-pay.",
+        "- The public remote is rate limited per IP; run it locally with `npx` for unlimited use.",
+        "",
+        "## Services and tools",
+        ...g.map((s) => `- ${s.label} (${s.tools.length}): ${s.blurb} Tools: ${s.tools.join(", ")}`),
+        "",
+        "## Workflow prompts",
+        ...PROMPT_NAMES.map((p) => `- ${p}`),
+        "",
+        "## Links",
+        "- Platform: https://wickedapi.com (service directory at https://wickedapi.com/services.json)",
+        "- Source: https://github.com/choaticpixels/wicked-mcp",
+        "- npm: https://www.npmjs.com/package/wickedapi-mcp",
+        "- Registry: io.github.choaticpixels/wicked-mcp on https://registry.modelcontextprotocol.io",
+        "- Server card: " + SITE + "/.well-known/mcp/server-card.json",
+        "",
+        "Wallet-signed tools (identity, memory, registry registration) never sign for you: you supply the signature from your own wallet.",
+        "",
+    ].join("\n");
+}
+export function serverCard(tools, version) {
+    return {
+        $schema: "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
+        version: "1.0",
+        protocolVersion: "2025-06-18",
+        serverInfo: { name: "io.github.choaticpixels/wicked-mcp", title: "Wicked MCP", version },
+        description: `The whole Wicked suite for agents: ${tools.length} tools across market data, DeFi/token risk, identity, reputation, registry, sanity checks, memory and paywalls. x402-native.`,
+        documentationUrl: "https://github.com/choaticpixels/wicked-mcp",
+        transport: { type: "streamable-http", endpoint: "/mcp" },
+        capabilities: { tools: { listChanged: false }, resources: {}, prompts: {} },
+        authentication: { required: false, note: "Optional keys unlock free tiers; otherwise paid calls return an x402 challenge." },
+        packages: [{ registry: "npm", name: "wickedapi-mcp", transport: "stdio" }],
+        tools: tools.map((name) => ({ name })),
+    };
+}
+const esc = (s) => s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+export function landingHtml(tools, version) {
+    const g = grouped(tools);
+    const rows = g
+        .map((s) => `<details><summary><b>${esc(s.label)}</b> <span>${s.tools.length} tools</span><em>${esc(s.blurb)}</em></summary><code>${s.tools.map(esc).join(" &middot; ")}</code></details>`)
+        .join("\n");
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Wicked MCP</title><meta name="description" content="One MCP server for the whole Wicked suite: ${tools.length} tools for agents.">
+<style>:root{color-scheme:light dark;--bg:#fff;--fg:#14171f;--mut:#5b6472;--card:#f4f6fa;--acc:#6d28d9}@media(prefers-color-scheme:dark){:root{--bg:#0e1117;--fg:#e8ebf2;--mut:#98a2b3;--card:#181d27;--acc:#a78bfa}}
+body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.55 system-ui,sans-serif}main{max-width:760px;margin:0 auto;padding:32px 16px}h1{margin:0 0 4px}p.l{color:var(--mut);margin-top:0}
+pre{background:var(--card);padding:12px 14px;border-radius:8px;overflow:auto;font-size:14px}details{background:var(--card);border-radius:8px;padding:10px 14px;margin:8px 0}summary{cursor:pointer}summary span{color:var(--acc);margin:0 8px;font-size:14px}summary em{display:block;color:var(--mut);font-style:normal;font-size:14px}
+code{display:block;margin-top:8px;font-size:13px;color:var(--mut);word-break:break-word}a{color:var(--acc)}footer{color:var(--mut);font-size:14px;margin-top:24px}</style></head><body><main>
+<h1>Wicked MCP</h1><p class="l">${tools.length} tools. ${g.length} services. One server for agents. v${esc(version)}</p>
+<h3>Connect in one line</h3>
+<pre>claude mcp add --transport http wicked ${SITE}/mcp</pre>
+<pre>{ "mcpServers": { "wicked": { "url": "${SITE}/mcp" } } }</pre>
+<pre>npx -y wickedapi-mcp   # local, stdio - unlimited, supports your API key or payer wallet</pre>
+<p>No signup. Priced calls return a real x402 payment challenge (USDC on Base). The public endpoint is rate limited per IP.</p>
+<h3>What's inside</h3>
+${rows}
+<footer><a href="https://wickedapi.com">wickedapi.com</a> &middot; <a href="https://github.com/choaticpixels/wicked-mcp">GitHub</a> &middot; <a href="https://www.npmjs.com/package/wickedapi-mcp">npm</a> &middot; <a href="/llms.txt">llms.txt</a> &middot; <a href="/.well-known/mcp/server-card.json">server card</a> &middot; <a href="/stats">usage</a></footer>
+</main></body></html>`;
+}

package/dist/prompts.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+const text = (t) => ({ role: "user", content: { type: "text", text: t } });
+export function registerSuitePrompts(server) {
+    server.registerPrompt("fact_check", {
+        title: "Fact-check before acting",
+        description: "Split an answer into claims and verify each against your source text (or live web evidence) with Wicked Sanity before you rely on it.",
+        argsSchema: {
+            output: z.string().describe("The text to check - an AI answer, summary or report."),
+            source: z.string().optional().describe("The source text the output must be faithful to. Omit to check against live web evidence instead."),
+        },
+    }, ({ output, source }) => ({
+        description: "Fact-check workflow",
+        messages: [
+            text(`Verify the following output before I act on it. Don't judge it yourself - use the tools.\n\n` +
+                `1. Split it into individual factual claims (one sentence each).\n` +
+                `2. Call \`sanity_check_batch\` once with all claims, ` +
+                (source
+                    ? `mode="grounded" and context set to the source text below.\n`
+                    : `mode="open" (no source supplied, so check against live web evidence).\n`) +
+                `3. Report every claim with its exact verdict (supported / contradicted / unsupported / insufficient_evidence) ` +
+                `and the evidence returned. Treat unsupported and insufficient_evidence as UNVERIFIED, and contradicted as wrong.\n` +
+                `4. If the response has http_status 402, 429 or another error, say so plainly - do not guess verdicts.\n\n` +
+                `OUTPUT TO CHECK:\n${output}\n` +
+                (source ? `\nSOURCE:\n${source}\n` : "")),
+        ],
+    }));
+    server.registerPrompt("verify_agent", {
+        title: "Check an agent's trust",
+        description: "Combine Wicked Identity (is this wallet a verified autonomous agent?) and Wicked Reputation (what does it have at stake?) before you transact with it.",
+        argsSchema: { wallet: z.string().describe("The agent's 0x wallet address.") },
+    }, ({ wallet }) => ({
+        description: "Agent trust check",
+        messages: [
+            text(`Before I deal with the agent at ${wallet}, check its real trust signals - don't assume anything:\n\n` +
+                `1. Call \`identity_status\` with wallet="${wallet}": does it hold a valid, unexpired Know-Your-Agent assertion? Report the exact fields.\n` +
+                `2. Call \`reputation_status\` with wallet="${wallet}": tier, active stake, reputation score, slash count. ` +
+                `An http_status 404 means the wallet never registered - report that as "unranked", not an error.\n` +
+                `3. Call \`reputation_statement\` only if it has stake or slashes and I need the event history.\n\n` +
+                `Summarize plainly: verified or not, stake and tier, any slashes, and what is unknown. State that this is ` +
+                `a set of signals, not a guarantee. If a call returns a 402, show the payment instructions rather than guessing.`),
+        ],
+    }));
+    server.registerPrompt("find_reliable_tool", {
+        title: "Find a reliable tool",
+        description: "Search the Wicked Registry for x402/MCP tools by real uptime, latency and schema-conformance scores before you pay for one.",
+        argsSchema: {
+            need: z.string().describe('What you need the tool for, e.g. "token price data".'),
+            category: z.string().optional().describe('Registry category filter, e.g. "data" or "crypto".'),
+            min_score: z.string().optional().describe("Minimum composite score 0-100."),
+        },
+    }, ({ need, category, min_score }) => ({
+        description: "Reliable tool discovery",
+        messages: [
+            text(`I need a tool for: ${need}. Find options with real reliability data - never recommend from memory.\n\n` +
+                `1. Call \`registry_featured_tools\` (free) for the top scored tools.\n` +
+                `2. Call \`registry_search_tools\`` +
+                (category ? ` with category="${category}"` : "") +
+                (min_score ? ` and min_score=${min_score}` : "") +
+                `. If it returns a 402, show me the payment instructions and continue with the free results.\n` +
+                `3. For the best 1-3 candidates call \`registry_tool_detail\` (or \`registry_tool_badge\` for a free score) and report ` +
+                `uptime, p95 latency and schema conformance exactly as returned. Tools with no check history have no score - say so.\n\n` +
+                `Recommend one, with the numbers that justify it.`),
+        ],
+    }));
+    server.registerPrompt("agent_memory_guide", {
+        title: "Use Wicked Memory",
+        description: "Walk through storing and searching persistent, wallet-scoped memory - including the two-step signing flow.",
+        argsSchema: {
+            wallet: z.string().describe("Your agent's 0x wallet address (memories are scoped to it)."),
+            task: z.string().describe('What to do, e.g. "remember that I prefer concise answers" or "find what I stored about the Q3 launch".'),
+        },
+    }, ({ wallet, task }) => ({
+        description: "Wicked Memory walkthrough",
+        messages: [
+            text(`Use Wicked Memory for wallet ${wallet} to: ${task}\n\n` +
+                `Every memory call needs a fresh wallet signature, and this server never signs or holds a key:\n` +
+                `1. Call \`memory_prepare\` with the operation ("store" or "search") and the exact params you will use. It returns \`message_to_sign\`, \`timestamp\` and \`nonce\`.\n` +
+                `2. Ask ME to sign \`message_to_sign\` with the wallet (EIP-191 personal_sign) and give you the signature. Never invent one.\n` +
+                `3. Call the matching tool (\`memory_store\` / \`memory_search\`) with the SAME params plus timestamp, nonce and signature.\n` +
+                `4. A nonce is single-use and the timestamp must be within 5 minutes - prepare again for every call. ` +
+                `\`memory_search\` is metered: if it returns http_status 402, show me the payment instructions; the same signed request can be retried with a payment_signature.\n\n` +
+                `Report exactly what the tools returned.`),
+        ],
+    }));
+}

package/dist/rateLimit.js

@@ -0,0 +1,22 @@
+const WINDOW_MS = 60_000;
+const PRUNE_ABOVE_ENTRIES = 1000;
+// In-memory fixed-window limiter; fine for the single instance this runs as.
+// Move the counters to shared storage before running more than one instance.
+const hits = new Map();
+let lastPrune = 0;
+export function rateLimited(key, limit = Number(process.env.RATE_LIMIT_PER_MINUTE || 30), now = Date.now()) {
+    if (hits.size >= PRUNE_ABOVE_ENTRIES && now - lastPrune > 30_000) {
+        lastPrune = now;
+        for (const [k, h] of hits)
+            if (!h.length || now - h[h.length - 1] > WINDOW_MS)
+                hits.delete(k);
+    }
+    const bucket = (hits.get(key) ?? []).filter((t) => now - t <= WINDOW_MS);
+    if (bucket.length >= limit) {
+        hits.set(key, bucket);
+        return true;
+    }
+    bucket.push(now);
+    hits.set(key, bucket);
+    return false;
+}

package/dist/server.js

@@ -0,0 +1,337 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { registerSuiteTools } from "./suite.js";
+import { registerSuitePrompts } from "./prompts.js";
+import { instrument } from "./usage.js";
+function envUrl(name, fallback) {
+    return (process.env[name] || fallback).replace(/\/$/, "");
+}
+const SERVICES = [
+    { id: "trading", name: "Trading Data API", baseUrl: envUrl("WICKEDAPI_BASE_URL", "https://api.wickedapi.com") },
+    { id: "protocol_health", name: "Protocol Health Oracle", baseUrl: envUrl("WICKEDAPI_PROTOCOL_HEALTH_URL", "https://protocol-health-oracle.wickedapi.com") },
+    { id: "token_risk", name: "Token Risk Oracle", baseUrl: envUrl("WICKEDAPI_TOKEN_RISK_URL", "https://token-risk-oracle.wickedapi.com") },
+    { id: "broker_sync", name: "Broker Sync API", baseUrl: envUrl("WICKEDAPI_BROKER_SYNC_URL", "https://broker-sync-api.wickedapi.com") },
+];
+const SHOWCASE_URL = envUrl("WICKEDAPI_SHOWCASE_URL", "https://wickedapi.com");
+const API_KEY = process.env.WICKEDAPI_API_KEY;
+const PAYER_KEY = process.env.WICKEDAPI_PAYER_PRIVATE_KEY;
+// A few auto-generated tool names collide or read badly (e.g. GET and POST
+// both hitting /v1/protocols) — override just those, keyed by
+// "METHOD /openapi/path/{param}".
+const TOOL_NAME_OVERRIDES = {
+    protocol_health: {
+        "GET /v1/protocols": "protocol_health_list_protocols",
+        "POST /v1/protocols": "protocol_health_track_protocol",
+        "GET /v1/health/{slug}": "protocol_health_score",
+        "POST /v1/refresh": "protocol_health_refresh_all",
+        "POST /v1/ingest": "protocol_health_sync_universe",
+    },
+    broker_sync: {
+        "POST /v1/users": "broker_sync_register_user",
+    },
+};
+// If a funded Base-mainnet wallet key is provided, every call auto-pays the
+// x402 402 challenge in USDC — no API key or signup needed at all. Loaded
+// lazily so a plain API-key setup never has to pull in viem/x402-fetch.
+async function buildFetcher() {
+    if (!PAYER_KEY)
+        return fetch;
+    let deps;
+    try {
+        deps = await Promise.all([import("viem"), import("viem/accounts"), import("viem/chains"), import("x402-fetch")]);
+    }
+    catch {
+        console.error("[wickedapi-mcp] WICKEDAPI_PAYER_PRIVATE_KEY is set, but the wallet-payment dependencies " +
+            "(viem, x402-fetch) aren't installed in this distribution. Falling back to plain fetch — " +
+            "calls without an API key will surface the 402 challenge instead of auto-paying. " +
+            "Use `npx wickedapi-mcp` for full auto-pay support.");
+        return fetch;
+    }
+    const [{ createWalletClient, http }, { privateKeyToAccount }, { base }, { wrapFetchWithPayment }] = deps;
+    const account = privateKeyToAccount(PAYER_KEY);
+    const wallet = createWalletClient({ account, chain: base, transport: http() });
+    console.error(`[wickedapi-mcp] x402 auto-pay enabled — wallet ${account.address}`);
+    // x402-fetch's Signer type expects a client extended with viem's public
+    // actions; the proven pattern in scripts/x402-bot-test.mjs passes a plain
+    // wallet client the same way — cast rather than pull in publicActions.
+    return wrapFetchWithPayment(fetch, wallet);
+}
+function pathSlug(openapiPath) {
+    return openapiPath
+        .replace(/^\/v1\//, "")
+        .replace(/[{}]/g, "")
+        .replace(/[\/\-]+/g, "_");
+}
+function toolNameFor(service, method, openapiPath) {
+    const override = TOOL_NAME_OVERRIDES[service.id]?.[`${method.toUpperCase()} ${openapiPath}`];
+    if (override)
+        return override;
+    const slug = pathSlug(openapiPath);
+    if (service.id === "trading")
+        return slug; // legacy naming, already published
+    return slug === service.id ? service.id : `${service.id}_${slug}`;
+}
+function zodFor(p) {
+    const base = p.type === "number" || p.type === "integer"
+        ? z.coerce.number()
+        : p.type === "boolean"
+            ? z.coerce.boolean()
+            : z.string();
+    const described = p.description ? base.describe(p.description) : base;
+    return p.required ? described : described.optional();
+}
+async function loadServiceSpec(service) {
+    try {
+        const res = await fetch(`${service.baseUrl}/openapi.json`);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return (await res.json());
+    }
+    catch (err) {
+        console.error(`[wickedapi-mcp] WARNING: couldn't load ${service.name} spec (${service.baseUrl}/openapi.json): ` +
+            `${err.message} — its tools are unavailable this session, the rest load normally.`);
+        return null;
+    }
+}
+function registerServiceTools(server, service, doc, doFetch) {
+    let registered = 0;
+    for (const [openapiPath, methods] of Object.entries(doc.paths)) {
+        if (!openapiPath.startsWith("/v1/") || openapiPath === "/v1/status")
+            continue; // /v1/status is a resource instead
+        if (openapiPath.includes("webhook"))
+            continue; // called by a third party, never by an agent
+        for (const [method, op] of Object.entries(methods)) {
+            const pathParamNames = [];
+            const queryParamNames = [];
+            const bodyPropNames = [];
+            const shape = {};
+            for (const p of op.parameters ?? []) {
+                if (p.in === "path") {
+                    pathParamNames.push(p.name);
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: true, description: p.description });
+                }
+                else if (p.in === "query") {
+                    queryParamNames.push(p.name);
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: p.required, description: p.description });
+                }
+            }
+            const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+            if (bodySchema) {
+                const required = new Set(bodySchema.required ?? []);
+                for (const [name, prop] of Object.entries(bodySchema.properties ?? {})) {
+                    bodyPropNames.push(name);
+                    shape[name] = zodFor({ type: prop.type, required: required.has(name), description: prop.description });
+                }
+            }
+            const name = toolNameFor(service, method, openapiPath);
+            server.registerTool(name, {
+                description: `[${service.name}] ${[op.summary, op.description].filter(Boolean).join(" — ")}`.slice(0, 1000),
+                inputSchema: shape,
+            }, async (args) => {
+                let urlPath = openapiPath;
+                for (const p of pathParamNames)
+                    urlPath = urlPath.replace(`{${p}}`, encodeURIComponent(String(args[p])));
+                const url = new URL(service.baseUrl + urlPath);
+                for (const p of queryParamNames) {
+                    const v = args[p];
+                    if (v !== undefined && v !== null)
+                        url.searchParams.set(p, String(v));
+                }
+                const headers = {};
+                if (API_KEY)
+                    headers["x-api-key"] = API_KEY;
+                const init = { method: method.toUpperCase(), headers };
+                if (bodyPropNames.length) {
+                    const bodyObj = {};
+                    for (const p of bodyPropNames)
+                        if (args[p] !== undefined)
+                            bodyObj[p] = args[p];
+                    headers["content-type"] = "application/json";
+                    init.body = JSON.stringify(bodyObj);
+                }
+                const r = await doFetch(url.toString(), init);
+                const text = await r.text();
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = text;
+                }
+                return {
+                    isError: !r.ok,
+                    content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+                };
+            });
+            registered++;
+        }
+    }
+    return registered;
+}
+// --- Resources -----------------------------------------------------------
+// Reference material an agent can read without invoking a tool: the
+// platform-wide directory/llms.txt, and each service's live endpoint
+// catalog (the /v1/status we deliberately excluded from becoming a tool).
+function registerResources(server) {
+    server.registerResource("platform-services", "wickedapi://platform/services", {
+        title: "WickedAPI service directory",
+        description: "Every live WickedAPI service — URL, category, one-line description, auth modes, and links to each one's own OpenAPI spec/docs/llms.txt.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const r = await fetch(`${SHOWCASE_URL}/services.json`);
+        if (!r.ok)
+            throw new Error(`Failed to load service directory: HTTP ${r.status}`);
+        return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
+    });
+    server.registerResource("platform-llms-txt", "wickedapi://platform/llms", {
+        title: "WickedAPI llms.txt",
+        description: "Terse, platform-wide summary for agents deciding what to call — auth modes, free vs. paid endpoints.",
+        mimeType: "text/plain",
+    }, async (uri) => {
+        const r = await fetch(`${SHOWCASE_URL}/llms.txt`);
+        if (!r.ok)
+            throw new Error(`Failed to load llms.txt: HTTP ${r.status}`);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/plain", text: await r.text() }] };
+    });
+    for (const service of SERVICES) {
+        server.registerResource(`${service.id}-status`, `wickedapi://${service.id}/status`, {
+            title: `${service.name} — live catalog`,
+            description: `Live endpoint catalog for ${service.name} (${service.baseUrl}), fetched fresh on every read.`,
+            mimeType: "application/json",
+        }, async (uri) => {
+            const r = await fetch(`${service.baseUrl}/v1/status`);
+            if (!r.ok)
+                throw new Error(`Failed to load ${service.name} status: HTTP ${r.status}`);
+            return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
+        });
+    }
+}
+// --- Prompts ---------------------------------------------------------------
+// The "compound recipes" from the WickedAPI cookbook, turned into one-click
+// prompts: each just tells the assistant which real tools to call and how
+// to read the results — no fabricated synthesis, every number cited comes
+// from an actual tool call made during the conversation.
+function registerPrompts(server) {
+    server.registerPrompt("rug_check", {
+        title: "Rug-check before buying",
+        description: "Real on-chain risk signals for a token contract, plus market sentiment (and momentum, if it's a covered asset) before you decide whether to buy.",
+        argsSchema: {
+            address: z.string().describe("The token contract address (EVM) or mint address (Solana)."),
+            chain: z.string().describe("ethereum, bsc, base, polygon, arbitrum, optimism, avalanche, fantom, zksync, linea, scroll, or solana."),
+            symbol: z.string().optional().describe("If this token maps to a covered momentum-score asset (BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA), pass it to also pull a real momentum verdict."),
+        },
+    }, ({ address, chain, symbol }) => ({
+        description: "Rug-check workflow",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Before I consider buying this token, run a real risk check — don't guess or assume anything:\n\n` +
+                        `1. Call the \`token_risk\` tool with address="${address}" and chain="${chain}". Report the exact ` +
+                        `risk_score, risk_tier, and every real flag it returns (honeypot, mint/ownership authority, holder ` +
+                        `and LP concentration, buy/sell tax, trust-list status) — cite the actual values, don't summarize ` +
+                        `away the specifics or invent ones that weren't returned.\n` +
+                        `2. Call the \`sentiment\` tool for the current overall crypto market mood.\n` +
+                        (symbol
+                            ? `3. Call the \`momentum_score\` tool with symbol="${symbol}" and timeframe="1h" for a real technical read.\n`
+                            : "") +
+                        `\nThen give a plain verdict: the real risk signals found (listed, not paraphrased), current market ` +
+                        `mood, and — only if applicable — the momentum read. State clearly this is aggregated real signals, ` +
+                        `never a safety guarantee.`,
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("vet_dependency", {
+        title: "Vet a DeFi dependency",
+        description: "Protocol activity/treasury health plus an optional contract-level risk check, before you build on a DeFi protocol.",
+        argsSchema: {
+            slug: z.string().describe('The protocol\'s DefiLlama slug, e.g. "lido".'),
+            token_address: z.string().optional().describe("The protocol's token contract address, if you also want a contract-level risk check."),
+            chain: z.string().optional().describe("Chain for token_address (default ethereum)."),
+        },
+    }, ({ slug, token_address, chain }) => ({
+        description: "Dependency-vetting workflow",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Before I integrate this protocol as a dependency, check its real health — don't guess:\n\n` +
+                        `1. Call the \`protocol_health_score\` tool with slug="${slug}". Report the components (GitHub ` +
+                        `activity, TVL trend, treasury) exactly as returned, including any that came back null (never ` +
+                        `filled in).\n` +
+                        (token_address
+                            ? `2. Call the \`token_risk\` tool with address="${token_address}" and chain="${chain || "ethereum"}" ` +
+                                `for a contract-level check on its token.\n`
+                            : "") +
+                        `\nSummarize: is this protocol actively maintained, is its TVL trend healthy, and (if checked) does ` +
+                        `its token carry any real contract-level risk flags. Cite the real numbers.`,
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("morning_briefing", {
+        title: "Morning briefing",
+        description: "One daily digest from macro calendar, earnings calendar, sentiment, and a momentum verdict — all free or a fraction of a cent.",
+        argsSchema: {
+            symbol: z.string().optional().describe("Asset for the momentum verdict (default BTC). One of BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA."),
+        },
+    }, ({ symbol }) => {
+        const sym = symbol || "BTC";
+        return {
+            description: "Morning briefing workflow",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Compile my morning briefing from real, current data — call each tool, don't estimate:\n\n` +
+                            `1. \`macro_calendar\` with days=7 — upcoming FOMC/CPI/jobs events.\n` +
+                            `2. \`earnings_calendar\` with days=3 — upcoming earnings reports.\n` +
+                            `3. \`sentiment\` — current crypto Fear & Greed reading.\n` +
+                            `4. \`momentum_score\` with symbol="${sym}" and timeframe="1D" — today's technical verdict.\n\n` +
+                            `Then write one concise digest combining all four, citing the real values from each call.`,
+                    },
+                },
+            ],
+        };
+    });
+}
+export const SERVER_VERSION = "0.4.0";
+export async function loadWorld() {
+    const doFetch = await buildFetcher();
+    const specs = [];
+    for (const service of SERVICES) {
+        const doc = await loadServiceSpec(service);
+        if (doc)
+            specs.push({ service, doc });
+    }
+    if (specs.length === 0) {
+        throw new Error("No service specs loaded - check network access and WICKEDAPI_*_URL overrides.");
+    }
+    return { doFetch, specs };
+}
+export function buildServer(world, hooks) {
+    const server = new McpServer({ name: "wickedapi", version: SERVER_VERSION });
+    if (hooks)
+        instrument(server, hooks);
+    let totalTools = 0;
+    const loaded = [];
+    for (const { service, doc } of world.specs) {
+        totalTools += registerServiceTools(server, service, doc, world.doFetch);
+        loaded.push(service.name);
+    }
+    // Reputation, Registry, Identity, Sanity, Memory and Paywall use hand-written
+    // tools (non-/v1 paths, wallet-signature auth), registered unconditionally.
+    totalTools += registerSuiteTools(server);
+    loaded.push("Reputation, Registry, Identity, Sanity, Memory, Paywall");
+    registerResources(server);
+    registerPrompts(server);
+    registerSuitePrompts(server);
+    return {
+        server,
+        summary: `${totalTools} tools across ${loaded.length} group(s) (${loaded.join(", ")}), ${2 + SERVICES.length} resources, 7 prompts`,
+    };
+}

package/dist/usage.js

@@ -0,0 +1,46 @@
+const startedAt = Date.now();
+const counts = new Map();
+export const knownTools = new Set();
+export const usageHooks = {
+    onRegister: (name) => knownTools.add(name),
+    onToolCall: (name, ms, isError) => {
+        const c = counts.get(name) ?? { calls: 0, errors: 0, totalMs: 0 };
+        c.calls++;
+        c.totalMs += ms;
+        if (isError)
+            c.errors++;
+        counts.set(name, c);
+        console.log(JSON.stringify({ evt: "tool_call", tool: name, error: isError, ms }));
+    },
+};
+export function usageSnapshot() {
+    const tools = [...counts.entries()]
+        .map(([tool, c]) => ({ tool, calls: c.calls, errors: c.errors, avg_ms: Math.round(c.totalMs / c.calls) }))
+        .sort((a, b) => b.calls - a.calls);
+    return {
+        since: new Date(startedAt).toISOString(),
+        note: "In-memory since last deploy; durable history is in the service logs.",
+        total_calls: tools.reduce((n, t) => n + t.calls, 0),
+        tools,
+    };
+}
+// Wrap server.registerTool so every handler reports to the hooks. Must run
+// before any tools are registered.
+export function instrument(server, hooks) {
+    const original = server.registerTool.bind(server);
+    server.registerTool = (name, config, handler) => {
+        hooks.onRegister?.(name);
+        return original(name, config, async (...args) => {
+            const t0 = Date.now();
+            let isError = true;
+            try {
+                const result = await handler(...args);
+                isError = Boolean(result?.isError);
+                return result;
+            }
+            finally {
+                hooks.onToolCall?.(name, Date.now() - t0, isError);
+            }
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickedapi-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for the whole Wicked suite — trading data, DeFi protocol health, token safety, brokerage sync, agent identity, reputation, tool registry, hallucination checks, persistent memory, and x402 paywalls. 70 tools, 6 resources, 3 prompts. No signup required: pay per call in USDC via x402, or use a partner API key.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "node": ">=20"
   },
   "license": "MIT",
-  "homepage": "https://api.wickedapi.com",
+  "homepage": "https://mcp.wickedapi.com",
   "bugs": {
     "url": "https://api.wickedapi.com"
   },
@@ -22,7 +22,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "start:http": "node dist/http.js",
+    "test": "npm run build && node --test \"test/*.test.mjs\""
   },
   "keywords": [
     "mcp",
@@ -51,5 +53,10 @@
   "devDependencies": {
     "@types/node": "^22.20.1",
     "typescript": "^5.9.3"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/choaticpixels/wicked-mcp.git"
+  },
+  "mcpName": "io.github.choaticpixels/wicked-mcp"
 }