wickedapi-mcp 0.3.1 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ 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.
 
@@ -75,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):
@@ -82,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
 

package/dist/http.js

@@ -8,6 +8,8 @@ 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);
@@ -20,6 +22,10 @@ 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;
@@ -40,7 +46,8 @@ async function readJson(req) {
 }
 async function main() {
     const world = await loadWorld();
-    const { summary } = buildServer(world);
+    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")
@@ -48,6 +55,17 @@ async function main() {
         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") {
@@ -58,7 +76,7 @@ async function main() {
         }
         try {
             const body = await readJson(req);
-            const { server } = buildServer(world);
+            const { server } = buildServer(world, usageHooks);
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
             res.on("close", () => {
                 void transport.close();

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/server.js

@@ -1,6 +1,8 @@
 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(/\/$/, "");
 }
@@ -297,7 +299,7 @@ function registerPrompts(server) {
         };
     });
 }
-export const SERVER_VERSION = "0.3.1";
+export const SERVER_VERSION = "0.4.0";
 export async function loadWorld() {
     const doFetch = await buildFetcher();
     const specs = [];
@@ -311,8 +313,10 @@ export async function loadWorld() {
     }
     return { doFetch, specs };
 }
-export function buildServer(world) {
+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) {
@@ -325,8 +329,9 @@ export function buildServer(world) {
     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, 3 prompts`,
+        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.1",
+  "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": {