toll402-mcp 0.4.2 → 0.5.0

package/README.md

@@ -16,12 +16,20 @@ Or with a wallet (x402):
 ```json
 { "mcpServers": { "toll402": { "command": "npx", "args": ["-y", "toll402-mcp"], "env": { "TOLL402_WALLET_KEY": "0x...", "TOLL402_MAX_USD": "0.25" } } } }
 ```
+Remote, no install: `https://toll402.dev/mcp` (send `x-toll402-key` as a header, `?key=tk_…` in the URL for clients without headers, or x402 headers). Per-client setup for Claude Code, Cursor, Codex, ChatGPT, Windsurf, VS Code, Gemini CLI, Hermes, OpenClaw and more: https://toll402.dev/#connect
+
 You are charged only when a call succeeds (2xx). Catalog and prices: https://toll402.dev/v1/catalog · Docs for agents: https://toll402.dev/llms.txt
 
 ## Tools
 
 16 first-party tools, 167 community-forged tools and 2,466 provider API endpoints, all exposed as MCP tools (the provider endpoints through `find` and `do`). Prices are per call; charged only on success.
 
+### Account tools (free, need `TOLL402_API_KEY`)
+
+- **toll402_review**: rate a paid call you just used (`callId`, `useful`, optional `reason`). Reviews move tool ranking for every agent.
+- **toll402_job**: check an image or video generation task by `jobId`; returns the result URLs when done. Failed tasks are refunded.
+- **toll402_history**: this key's recent paid calls with cost, input summary and links to the stored answers (24 h).
+
 ### First-party
 
 - **read_url** ($0.002): Fetch any public web page (or PDF) and return clean, LLM-ready Markdown with title, metadata and links.

package/dist/mcp.js

@@ -7,6 +7,7 @@
  *   TOLL402_URL         base URL of the Toll402 server (default https://toll402.dev)
  *   TOLL402_WALLET_KEY  0x-prefixed EVM private key holding USDC on Base (omit for free instances)
  *   TOLL402_MAX_USD     max USD per single payment (default 0.25)
+ *   TOLL402_API_KEY     prepaid-credits key (tk_…) instead of a wallet; enables toll402_review, toll402_job, toll402_history
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -38,21 +39,38 @@ async function main() {
     else {
         console.error("toll402-mcp: TOLL402_WALLET_KEY not set — calls will fail with 402 unless the server is free");
     }
-    const server = new Server({ name: "toll402", version: "0.3.5" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const server = new Server({ name: "toll402", version: "0.5.0" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const META = [
+        { name: "toll402_review", description: "Rate a paid Toll402 call you just used: was the answer useful? Reviews move tool ranking for every agent. Free. Needs TOLL402_API_KEY.", inputSchema: { type: "object", properties: { callId: { type: "number", description: "The call id shown after a charged call" }, useful: { type: "boolean" }, reason: { type: "string" } }, required: ["callId", "useful"] } },
+        { name: "toll402_job", description: "Check an async Toll402 task (image or video generation) by job id: status, and result URLs when done. Free. Poll every 30-60 s.", inputSchema: { type: "object", properties: { jobId: { type: "string" } }, required: ["jobId"] } },
+        { name: "toll402_history", description: "Recent paid Toll402 calls of this key with cost, input summary and links to stored answers (24 h). Free.", inputSchema: { type: "object", properties: { days: { type: "number" }, tool: { type: "string" }, limit: { type: "number" } } } },
+    ];
+    const keyed = (path, init = {}) => fetch(`${BASE}${path}`, { ...init, headers: { "content-type": "application/json", "user-agent": "toll402-mcp/0.5.0", ...(API_KEY ? { "x-toll402-key": API_KEY } : {}) } });
+    const meta = async (name, a) => {
+        if (!API_KEY)
+            return { isError: true, content: [{ type: "text", text: `${name} needs TOLL402_API_KEY (prepaid credits from ${BASE}/credits).` }] };
+        const r = name === "toll402_review" ? await keyed(`/v1/calls/${encodeURIComponent(String(a.callId ?? ""))}/review`, { method: "POST", body: JSON.stringify({ useful: a.useful, reason: a.reason }) })
+            : name === "toll402_job" ? await keyed(`/v1/jobs/${encodeURIComponent(String(a.jobId ?? ""))}`)
+                : await keyed(`/v1/calls?${new URLSearchParams(Object.entries({ days: a.days, tool: a.tool, limit: a.limit ?? 20 }).filter(([, v]) => v !== undefined && v !== null && v !== "").map(([k, v]) => [k, String(v)]))}`);
+        const t = await r.text();
+        return { isError: !r.ok, content: [{ type: "text", text: r.ok ? t.slice(0, 20_000) : `HTTP ${r.status}: ${t.slice(0, 800)}` }] };
+    };
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: catalog.tools.map((t) => ({
-            name: t.name,
-            description: `[${t.kind ?? "tool"}] ${t.description} (costs ${t.price} per call, paid automatically: from your wallet via x402 or from prepaid credits (API key))`,
-            inputSchema: t.inputSchema,
-        })),
+        tools: [...META, ...catalog.tools.map((t) => ({
+                name: t.name,
+                description: `[${t.kind ?? "tool"}] ${t.description} (costs ${t.price} per call, paid automatically: from your wallet via x402 or from prepaid credits (API key))`,
+                inputSchema: t.inputSchema,
+            }))],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        if (req.params.name.startsWith("toll402_"))
+            return meta(req.params.name, (req.params.arguments ?? {}));
         const t = byName.get(req.params.name);
         if (!t)
             return { isError: true, content: [{ type: "text", text: `Unknown tool ${req.params.name}` }] };
         const r = await paidFetch(`${BASE}${t.path}`, {
             method: "POST",
-            headers: { "content-type": "application/json", "user-agent": "toll402-mcp/0.4.2", ...(API_KEY ? { "x-toll402-key": API_KEY } : {}), ...(process.env.TOLL402_REF ? { "x-toll402-ref": process.env.TOLL402_REF } : {}), ...(KEY ? { "x-toll402-agent": privateKeyToAccount(KEY).address } : {}) },
+            headers: { "content-type": "application/json", "user-agent": "toll402-mcp/0.5.0", ...(API_KEY ? { "x-toll402-key": API_KEY } : {}), ...(process.env.TOLL402_REF ? { "x-toll402-ref": process.env.TOLL402_REF } : {}), ...(KEY ? { "x-toll402-agent": privateKeyToAccount(KEY).address } : {}) },
             body: JSON.stringify(req.params.arguments ?? {}),
         });
         const text = await r.text();
@@ -66,7 +84,15 @@ async function main() {
         catch {
             /* leave as-is */
         }
-        const paid = r.headers.get("payment-response") ? `\n\n[paid ${t.price} via x402]` : r.headers.get("x-toll402-charged") ? `\n\n[charged $${r.headers.get("x-toll402-charged")} from credits · balance $${r.headers.get("x-toll402-balance")}]` : "";
+        const callId = r.headers.get("x-toll402-call-id");
+        let jobHint = "";
+        try {
+            const jid = JSON.parse(text).result?.job?.id;
+            if (jid)
+                jobHint = `\n[async task: check it with toll402_job {"jobId": "${jid}"} in about 60 s]`;
+        }
+        catch { /* not JSON */ }
+        const paid = (r.headers.get("payment-response") ? `\n\n[paid ${t.price} via x402]` : r.headers.get("x-toll402-charged") ? `\n\n[charged $${r.headers.get("x-toll402-charged")} from credits · balance $${r.headers.get("x-toll402-balance")}${callId ? ` · call id ${callId}: after using the answer, rate it with toll402_review` : ""}]` : "") + jobHint;
         return { content: [{ type: "text", text: out + paid }] };
     });
     await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toll402-mcp",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "MCP server for Toll402: 2,600+ pay-per-call tools for AI agents (web, PDF, provenance, verified business directory, ID validators, SEO/social/enrichment/ads/market-data provider APIs). Pay per call with USDC via x402 (no account) or with prepaid credits bought by card (API key). Charged only on success.",
   "type": "module",
   "bin": {