gadgethumans-mcp 1.2.1 → 1.2.3

package/README.md

@@ -1,19 +1,43 @@
 # gadgethumans-mcp
 
-MCP server for the **GadgetHumans API Hub**: 224 tools — web search, page reads and scraping to markdown,
-Base token safety verdicts, prediction markets, OCR, ENS, DNS/WHOIS, crypto prices, geocoding, text/LLM
-utilities — plus a free cross-bazaar x402 search.
+MCP server for the **GadgetHumans API Hub**: one endpoint that answers the small factual questions an
+agent asks constantly — is this email deliverable, who owns this domain, what does this page say, is
+this token a honeypot, did this price move — over 236 tools covering web search and page reads, Base
+token safety, prediction markets, OCR, ENS, DNS/WHOIS/IP, crypto prices, geocoding and text utilities,
+plus a free cross-bazaar x402 search.
+
+The tool list is fetched live from `https://api.gadgethumans.com/mcp` at startup, so every tool arrives
+with its real parameter schema, its real price and its description. `tools/list` returns the **23 routes
+you can actually buy** (priced rows + free tools) rather than all 236 schemas — a planner chooses badly
+from an unbounded menu, and the extra schemas cost context on every turn. The full catalogue is at
+`https://api.gadgethumans.com/mcp?all=1`.
+
+## Use it from Hermes
+
+```yaml
+# ~/.hermes/config.yaml
+mcp_servers:
+  gadgethumans:
+    url: https://api.gadgethumans.com/mcp
+```
 
-The tool list is fetched live from `https://api.gadgethumans.com/mcp` at startup, so it always matches what
-the server actually sells: every tool arrives with its real parameter schema, price and description.
+There is a ready-made skill at
+`https://github.com/gadgethumans-dev/api-hub/blob/main/skills/gadgethumans-api-hub/SKILL.md` — it tells
+an agent which route answers which question, what each costs, and what to check before paying anything.
 
-## Two ways to pay
+## Free first
 
-**1. Prepaid credits — works in any MCP client, no wallet:**
+**25 calls/day per IP, no signup, no key.** The MCP door and the REST door share that trial, so the first
+call of the day just answers. Prices are listed per tool in `tools/list` (`price_usd`), in the OpenAPI
+document, and in the 402 body.
 
-```
-https://api.gadgethumans.com/buy-credits?pack=500   # $5 = 500 calls
-```
+## Two ways to pay once the trial is spent
+
+**1. Card — works in any MCP client, no wallet.** Pick a pack and pay by card:
+
+- `$5` — 500 calls: <https://buy.stripe.com/5kQfZhen07SUbW00Z7abK0Q>
+- `$20` — 2,500 calls: <https://buy.stripe.com/aFaeVd7YCehi8JO6jrabK0R>
+- `$15/month` — 1,500 calls a month: <https://buy.stripe.com/6oUbJ15Qu1uw6BG23babK0S>
 
 The purchase returns an `api_key`. Set it and restart:
 
@@ -21,10 +45,10 @@ The purchase returns an `api_key`. Set it and restart:
 export GADGETHUMANS_API_KEY=gh_...
 ```
 
-**2. x402 — USDC on Base, only if your client can sign the payment itself:**
-
-An unpaid call returns `HTTP 402` with an x402 `accepts[]` challenge (also in the `Payment-Required`
-header). Settle it and retry with an `X-PAYMENT` header. USDC on Base, chainId 8453.
+**2. x402 — USDC on Base, only if your client can sign the payment itself.** Pay a pack URL directly and
+the 200 response returns the key, or pay per call: an unpaid call returns `HTTP 402` with an x402
+`accepts[]` challenge (also in the `Payment-Required` header). Settle it and retry with an `X-PAYMENT`
+header. USDC on Base, chainId 8453.
 
 This package never asks for a wallet private key — it is a proxy, and signing belongs in the client that
 owns the key.
@@ -55,10 +79,20 @@ npx -y gadgethumans-mcp
   "env": { "GADGETHUMANS_API_KEY": "gh_..." } } } }
 ```
 
-## Free tier
+## What it is good for
+
+| Question | Tool | Price |
+|---|---|---|
+| Is this email real / deliverable? | `email_lookup` | `$0.01` |
+| Who owns this domain? | `whois` | `$0.01` |
+| What does this page say? | `get_url` | `$0.01` |
+| Is this token a honeypot? | `token_verdict` | `$0.01` |
+| Did this page/price/DNS change? | `changed` | `$0.01` |
+| DNS records | `dns_lookup` | `$0.01` |
+| Terminal text from an image or PDF | `ocr` | `$0.002` |
 
-The MCP door allows 5 calls/day per IP without payment; the REST door allows 100 requests/day per IP.
-Prices per tool are in `tools/list` (`price_usd`) and in the OpenAPI document.
+`changed` is stateless — you pass back the hash you got last time, so polling costs one call and stores
+nothing server-side.
 
 ## Links
 

package/index.js

@@ -26,7 +26,7 @@ const REST_BASE = process.env.GADGETHUMANS_REST || "https://api.gadgethumans.com
 
 // A 402 is the moment a caller decides whether we are real. Give it a ready-to-run
 // proof call instead of a pricing lecture: most tool names are the REST route's own
-// slug, so the same tool can be answered free (3/day per IP) with ?trial=1.
+// slug, so the same tool can be answered free (25/day per IP) with ?trial=1.
 function trialUrl(name, args) {
   if (!/^[a-z0-9][a-z0-9._-]{0,60}$/i.test(name || "")) return "";
   const qs = new URLSearchParams();
@@ -35,11 +35,14 @@ function trialUrl(name, args) {
     qs.set(k, String(v));
   }
   qs.set("trial", "1");
-  return `${REST_BASE}/${name}?${qs.toString()}`;
+  // MCP tool names use underscores; the paid routes are hyphenated. Without this the "free
+  // proof call" we hand a caller at the 402 moment answers 404 Unknown endpoint.
+  const slug = name.replace(/_/g, "-");
+  return `${REST_BASE}/${slug}?${qs.toString()}`;
 }
 
 const server = new Server(
-  { name: "gadgethumans-mcp", version: "1.2.0" },
+  { name: "gadgethumans-mcp", version: "1.2.3" },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gadgethumans-mcp",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "MCP server for the GadgetHumans API: 226 tools in one install (ocr, ens, token safety, translate, sentiment, whois, hash, geocode, dns, weather, vat, timezone, ip, search, and a free x402 catalogue search ranked by measured 30-day call volume). Prepaid credits key or x402 USDC on Base.",
   "mcpName": "com.gadgethumans/gadgethumans-mcp",
   "type": "module",