base-intel-search-mcp 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# Base Intel Search — MCP server 🔎⚡
+
+**Pay-per-call web search for AI agents, settled in USDC on Base via [x402](https://x402.org).**
+
+Add one MCP server and your agent gets a `web_search` tool. Each query is paid
+automatically from your wallet (~**$0.015 USDC** per call) — **no API key, no
+account, no subscription.** Powered by the [Base Intel](https://base-intel-api.jakemaxsigal.workers.dev) `/search` API.
+
+```
+agent calls web_search("…")
+   → GET /search?q=…        → 402 Payment Required
+   → x402 signs a USDC payment from your wallet
+   → request retried        → 200 + ranked, cited results
+```
+
+The agent never sees the payment — it just calls a tool and gets answers. Payment
+is transparent, instant, and per-call.
+
+## Why use it
+
+- **No signup / no key.** Fund a wallet with a few dollars of USDC on Base; that's it.
+- **Pay only for what you use.** ~$0.015 per query, no monthly fee.
+- **Real-time web.** Ranked, de-duplicated results with source + date, plus top news.
+- **Filters.** Recency (day/week/month/year), site restriction, result count.
+
+## Install
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "base-intel-search": {
+      "command": "npx",
+      "args": ["-y", "base-intel-search-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0xYOUR_PAYING_WALLET_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see a **web_search** tool.
+
+### Any MCP client
+
+```bash
+EVM_PRIVATE_KEY=0x… npx -y base-intel-search-mcp
+```
+
+## Funding the wallet
+
+`EVM_PRIVATE_KEY` is a wallet **you** control that pays per query. Fund it on **Base**:
+
+- A few dollars of **USDC** (covers hundreds of searches at ~$0.015 each)
+- A tiny amount of **ETH** for gas
+
+> Use a dedicated low-balance wallet for agent spending — never your main wallet.
+
+## The `web_search` tool
+
+| Param | Type | Notes |
+| --- | --- | --- |
+| `query` | string | required |
+| `recency` | `day` \| `week` \| `month` \| `year` | optional time window |
+| `site` | string | restrict to a domain, e.g. `arxiv.org` |
+| `count` | number (1–20) | results to return (default 10) |
+
+Returns ranked results (title, url, snippet, source, date, extra context) + top news as JSON.
+
+## Configuration
+
+| Env | Default | Purpose |
+| --- | --- | --- |
+| `EVM_PRIVATE_KEY` | — (required) | wallet that pays per query |
+| `SEARCH_API_URL` | Base Intel `/search` | override the search endpoint |
+| `X402_NETWORK` | `eip155:8453` | payment network (Base mainnet) |
+
+## How payment works
+
+Built on the [x402](https://x402.org) protocol v2 using `@x402/axios` + `@x402/evm`.
+The first request to `/search` returns `402 Payment Required`; the x402 client signs
+a USDC `transferWithAuthorization` from your wallet and retries. Settlement is on
+Base L2 (sub-cent gas, ~2s). You pay the resource directly — this server holds no
+funds and takes no custody.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Base Intel Search — MCP server
+ *
+ * Gives any MCP-compatible AI agent (Claude Desktop, custom agents, etc.)
+ * a `web_search` tool that is paid per call in USDC on Base via the x402
+ * protocol. The agent pays from its OWN wallet — no API key, no subscription.
+ *
+ * How it works:
+ *   tool call -> GET https://…/search?q=…  ->  402 Payment Required
+ *             -> @x402/axios signs a USDC payment from EVM_PRIVATE_KEY
+ *             -> request retried with payment -> 200 + ranked results
+ *
+ * Env:
+ *   EVM_PRIVATE_KEY   (required) — wallet that pays per query (~$0.015/call)
+ *   SEARCH_API_URL    (optional) — defaults to the Base Intel /search endpoint
+ *   X402_NETWORK      (optional) — defaults to eip155:8453 (Base mainnet)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import axios from "axios";
+import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+
+const SEARCH_API_URL = process.env.SEARCH_API_URL || "https://base-intel-api.jakemaxsigal.workers.dev";
+const NETWORK = process.env.X402_NETWORK || "eip155:8453";
+const PRICE_HINT = "~$0.015 USDC per query";
+
+const pk = process.env.EVM_PRIVATE_KEY;
+if (!pk) {
+  console.error("[base-intel-search-mcp] Missing EVM_PRIVATE_KEY. Set the wallet that pays per query.");
+  process.exit(1);
+}
+const account = privateKeyToAccount(pk.startsWith("0x") ? pk : `0x${pk}`);
+
+// Axios instance that auto-handles x402 402 responses by paying from `account`.
+const api = wrapAxiosWithPaymentFromConfig(
+  axios.create({ baseURL: SEARCH_API_URL, timeout: 30000 }),
+  { schemes: [{ network: NETWORK, client: new ExactEvmScheme(account) }] }
+);
+
+const server = new McpServer({ name: "base-intel-search", version: "1.0.0" });
+
+server.tool(
+  "web_search",
+  `Search the live web for current, real-time information to answer questions, research topics, and ground responses with cited sources. ` +
+  `Returns ranked, de-duplicated results (title, url, snippet, source, date) plus top news. ` +
+  `Paid per call in USDC on Base via x402 (${PRICE_HINT}); payment is automatic from the configured wallet.`,
+  {
+    query: z.string().describe("The search query."),
+    recency: z.enum(["day", "week", "month", "year"]).optional()
+      .describe("Restrict results to a recent time window."),
+    site: z.string().optional().describe("Restrict to a domain, e.g. 'arxiv.org'."),
+    count: z.number().int().min(1).max(20).optional().describe("Number of results (default 10)."),
+  },
+  async ({ query, recency, site, count }) => {
+    const params = new URLSearchParams({ q: query });
+    if (recency) params.set("recency", recency);
+    if (site) params.set("site", site);
+    if (count) params.set("count", String(count));
+    try {
+      const res = await api.get(`/search?${params.toString()}`);
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    } catch (err) {
+      const status = err?.response?.status;
+      let msg = err?.response?.data?.error || err?.message || String(err);
+      if (status === 402) msg = "Payment required but not completed — check the wallet has USDC + a little ETH for gas on Base.";
+      if (/insufficient/i.test(msg)) msg = "Wallet has insufficient USDC/ETH on Base to pay for the query.";
+      return { content: [{ type: "text", text: `web_search failed: ${msg}` }], isError: true };
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[base-intel-search-mcp] ready · pays from ${account.address} · ${SEARCH_API_URL} · ${NETWORK}`);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "base-intel-search-mcp",
+  "version": "1.0.0",
+  "description": "MCP server giving any AI agent pay-per-call web search, settled in USDC on Base via x402. Wraps the Base Intel /search API. The agent pays per query from its own wallet — no API key, no subscription.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "base-intel-search-mcp": "index.js"
+  },
+  "files": ["index.js", "README.md"],
+  "keywords": [
+    "mcp", "model-context-protocol", "x402", "web-search", "ai-agent",
+    "base", "usdc", "pay-per-call", "agent-payments", "search"
+  ],
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@x402/axios": "^2.14.0",
+    "@x402/evm": "^2.14.0",
+    "axios": "^1.7.0",
+    "viem": "^2.21.0",
+    "zod": "^3.23.0"
+  }
+}