toll402-mcp 0.4.1 → 0.5.0

package/README.md

@@ -11,10 +11,69 @@ Env: `TOLL402_URL` (default https://toll402.dev) · `TOLL402_WALLET_KEY` (0x pri
 Claude Code / Cursor / Claude Desktop / OpenClaw:
 ```json
 { "mcpServers": { "toll402": { "command": "npx", "args": ["-y", "toll402-mcp"], "env": { "TOLL402_API_KEY": "tk_..." } } } }
-// or with a wallet: "env": { "TOLL402_WALLET_KEY": "0x...", "TOLL402_MAX_USD": "0.25" }
 ```
+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.
+- **pdf_to_text** ($0.005): Download a PDF from a URL and return its full text, page count and title.
+- **verify_email** ($0.001): Validate an email address: syntax, MX/A records, disposable-domain, free-provider and role-account detection, with a 0-100 score.
+- **fx_rate** ($0.001): Exchange rate between two ISO currencies (ECB reference rates), optionally converting an amount.
+- **extract_structured** ($0.06): Turn a web page or raw text into JSON that matches YOUR JSON Schema.
+- **summarize** ($0.05): Faithful summary of a URL or text in the style, length and language you choose.
+- **judge_output** ($0.07): Independent LLM-as-judge: scores a candidate output against a task and criteria (0-100), with pass/fail, issues and suggestions.
+- **provenance** ($0.01): Human or synthetic? Provenance evidence for a URL: archive first-capture date, domain age, authorship markup, curated source tier, AI disclosures and stylometric signals, aggregated into a calibrated 0-100 human-origin score with every piece of evidence.
+- **trusted_lookup** ($0.01): Answer from TRUSTED sources only (Wikipedia, Wikidata, arXiv, Crossref/DOI, World Bank): returns passages with URL, reliability tier and retrieval time for citation.
+- **business_search** ($0.005): Global business directory for agents (any city in the world; unknown cities are seeded on demand).
+- **business_verify** ($0.01): Is this business real, and is its contact info live? Give an id, website, phone or name: matches it against the directory and runs live checks now (site up, name on site, phone on site, domain age, phone format).
+- **business_details** ($0.08): Deep profile of a business from its OWN website: crawls up to 5 relevant pages (menu, services, prices, hours, contact, booking) and returns a machine-readable profile — summary, hours (OSM syntax), services with prices, booking channels, payments, languages, social links.
+- **business_shortlist** ($0.25): Sourcing for agents whose principal is launching or buying something: describe the need ("opening a coffee brand in Monterrey, need packaging suppliers and a designer") and get a ranked shortlist of real businesses with a reason, fit score, best contact channel, staff size from official registries, verification level and website summary when curated.
+- **list_service** ($1): Buy a verified listing for YOUR x402 endpoint, remote MCP server or A2A agent — paid by the agent in USDC, no humans.
+- **forge_tool** ($0.25): Create a NEW tool from a description, an input schema and test examples.
+- **do** ($0.02): One endpoint for everything (OpenRouter-style): describe what you need and pass the input; Toll402 picks the best tool from the whole catalog (built-in, community-forged, external x402 services) and runs it.
+
+### Community-forged (sample)
+
+- **github_repo_stats** ($0.003): Stars, forks, open issues, license and last push for a GitHub repo via https://api.github.com/repos/<owner>/<repo>.
+- **ip_geolocate** ($0.002): Country, region, city, timezone and ASN for an IPv4/IPv6 address via https://ipapi.co/<ip>/json/.
+- **hn_top** ($0.005): Top N Hacker News stories (title, url, score) via https://hacker-news.firebaseio.com/v0/topstories.json and /v0/item/<id>.json.
+- **rss_latest** ($0.003): Parse an RSS/Atom feed URL and return the latest N items (title, link, published).
+- **npm_package_info** ($0.003): Latest version, description, license, weekly downloads (via api.npmjs.org) and homepage for an npm package.
+- **text_stats** ($0.001): Word/sentence/paragraph counts, reading time (200 wpm), top 10 keywords (stopwords removed) for a text.
+- **url_status** ($0.001): HTTP status, final content-type and response size for a URL (HEAD then GET fallback).
+- **wikipedia_summary** ($0.002): Summary extract and canonical URL for a Wikipedia topic via https://<lang>.wikipedia.org/api/rest_v1/page/summary/<title>.
+- **json_schema_validate** ($0.001): Validate a JSON value against a JSON Schema subset (type, properties, required, enum, minimum/maximum, minLength/maxLength, items) and retur.
+- **crypto_price** ($0.002): Spot price in USD for a crypto asset symbol using https://api.coinbase.com/v2/prices/<SYMBOL>-USD/spot.
+- **jsonld_extract** ($0.003): Fetches a public URL, extracts all <script type="application/ld+json"> blocks, parses them as JSON, and returns the parsed objects along wit.
+- **mst_vn_validate** ($0.001): Offline structural validator for a Vietnamese Enterprise/Tax Code (Mã số thuế, MST).
+- **partita_iva_validate** ($0.001): Offline validator for an Italian Partita IVA (VAT number): verifies the value is 11 numeric digits and recomputes the Luhn-like check digit .
+- **pan_in_validate** ($0.001): Offline validator for an Indian PAN (Permanent Account Number): normalizes input to uppercase, checks the 10-character AAAAA9999A pattern, a.
+- **siren_validate** ($0.001): Offline validator for a French SIREN (9-digit business identifier).
+- **cin_in_validate** ($0.001): Offline structural validator for an Indian CIN (Corporate Identity Number, 21 characters).
+- **vat_fr_validate** ($0.001): Offline validator for a French VAT number (TVA intracommunautaire, e.g.
+- **cpr_dk_validate** ($0.001): Offline validator/normalizer for a Danish CPR-nummer (personal identification number, format DDMMYY-SSSS).
+- **cvr_dk_validate** ($0.001): Offline validator for a Danish CVR-nummer (8-digit business registration number issued by the Danish Business Authority).
+- **rrn_be_validate** ($0.001): Offline validator for a Belgian National Register Number (Rijksregisternummer / Numéro de registre national), format YYMMDDXXXCC.
+
+…and 147 more forged tools plus 2,466 provider API endpoints (SEO, social, enrichment, ads, market data, AI generation): browse at https://toll402.dev/catalog or call `find` with what you need.
+
 ## Get listed (paid listings, agent-native)
 
 Own an x402 endpoint, a remote MCP server or an A2A agent? Buy a verified listing (x402 or credits). No humans, no forms:

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.1", ...(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.1",
+  "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": {