# @dm2233/agent-data-mcp

A verification and market-data companion for AI agents, over
[MCP](https://modelcontextprotocol.io). Give it a claim to check, a price to
look up, or a page to read — it answers. No API key, pay-per-call in USDC on
Base via [x402](https://x402.org), and safe to install with zero setup: until
you fund a wallet, every call just tells you what it would have cost.

Where most tool servers hand an agent a long list of narrow endpoints and
expect it to pick the right one, this one exposes five things an agent
actually reaches for:

- **`verify_fact`** — is this claim checkable? A Wikipedia topic, a GitHub
  repo's real stats, an npm package's version and downloads, a domain's DNS
  records, or whether a domain is actually registered.
- **`check_market`** — what's the number? A token's price, DeFi TVL, the best
  yield right now, stablecoin supply, an FX rate.
- **`check_chain`** — what's happening on-chain? Current gas price, the
  latest block, on Base or Ethereum.
- **`search_web`** — go find out. Google results, semantic search with an AI
  answer, a clean read of any page, structured extraction from a page, or
  what's trending on Hacker News.
- **`ai_task`** — do something with this text. Summarize, translate,
  classify, or extract structured fields.

Each tool decides internally which of the underlying paid endpoints to call
based on the arguments you give it — you never need to know there are 33 of
them under the hood, and you never pick a tool by memorizing a route name.

This is an independent, from-scratch MCP server: it calls the existing
[x402-seller](https://x402-seller-0ay3.onrender.com) API over plain HTTP,
the same way any other client would. It shares no code with that project's
own `x402-seller-mcp` package (which instead exposes one tool per endpoint,
generated live from the server's discovery document) — this one is a
different, opinionated shape over the same underlying API.

## Two modes

- **No wallet configured (default)** — calling a tool fetches the endpoint
  it routed to, gets back the real `402 Payment Required` challenge, and
  returns a plain-language explanation (price, network, how to enable
  payment) instead of the actual data. Safe to try with zero setup.
- **Wallet configured** (`BUYER_PRIVATE_KEY` set) — calls are paid
  automatically over x402 (via
  [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch)) and return the
  real result plus the settlement receipt (payer address, transaction hash).

## Install

```bash
npx @dm2233/agent-data-mcp
```

That's the whole install — nothing to clone, build, or configure to try it in
explain-only mode.

## Claude Desktop

Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "agent-data": {
      "command": "npx",
      "args": ["-y", "@dm2233/agent-data-mcp"]
    }
  }
}
```

To enable automatic payments, add an `env` block (see **Enabling payments** below):

```json
{
  "mcpServers": {
    "agent-data": {
      "command": "npx",
      "args": ["-y", "@dm2233/agent-data-mcp"],
      "env": {
        "BUYER_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Cursor

Cursor uses the same `mcpServers` shape — add the same block to
`~/.cursor/mcp.json` (or your project's `.cursor/mcp.json`), then reload the
MCP servers from Settings → MCP.

## Enabling payments

⚠️ **Use a throwaway wallet, never a wallet holding significant funds.** The
private key you set here can sign USDC transfers on Base up to whatever
price each call costs (every tool here costs between $0.005 and $0.05 per
call) — but any process with the key in its environment can, in principle,
use it. Generate a fresh wallet dedicated to this MCP server and fund it
with a few dollars of USDC on Base, nothing more.

1. Generate a wallet (any EVM wallet works — e.g. with
   [viem](https://viem.sh):
   `node -e "const {generatePrivateKey,privateKeyToAccount}=require('viem/accounts');const k=generatePrivateKey();console.log(k, privateKeyToAccount(k).address)"`,
   or MetaMask/any wallet app export).
2. Send a small amount of USDC on **Base** (the network this server settles
   on) to that wallet's address — a few dollars covers hundreds of calls at
   these prices.
3. Set `BUYER_PRIVATE_KEY` to that wallet's private key (the `0x...`-prefixed
   hex string) in your MCP client's config (see examples above) or in your
   shell environment if running the server directly.
4. Restart the MCP server (or your MCP client). Tool calls will now pay
   automatically and return real results.

## Configuration

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `BUYER_PRIVATE_KEY` | No | _(unset)_ | EVM private key used to pay for tool calls. Unset = explain-only mode. |
| `X402_ORIGIN` | No | `https://x402-seller-0ay3.onrender.com` | Which x402 server backs these tools — point this at a different x402-compatible server (or a local dev instance) if needed. |

## The five tools, and what each one routes to

Every tool takes a small discriminant field (`source`, `metric`, `mode`, or
`task`) that picks the underlying endpoint, plus whatever arguments that
branch needs. Run `tools/list` against the server for the exact input schema
of each — this table is the map from "what you ask for" to "what actually
gets called":

### `verify_fact` — $0.005 per check

| `source` | Underlying endpoint |
|---|---|
| `wikipedia` | `GET /api/wiki/summary` |
| `github_repo` | `GET /api/github/repo` |
| `npm_package` | `GET /api/npm/package` |
| `dns_records` | `GET /api/dns/lookup` |
| `domain_registration` | `GET /api/rdap/domain` |

### `check_market` — $0.005 per check, $0.05 for any yields metric

| `metric` | Underlying endpoint |
|---|---|
| `crypto_price` | `GET /api/price/{btc,eth,sol}-usd` for a well-known symbol, else `GET /api/defi/price` |
| `usdc_supply` | `GET /api/price/usdc-supply` |
| `top_stablecoins` | `GET /api/defi/stablecoins` |
| `protocol_tvl` | `GET /api/defi/tvl` |
| `chain_tvl` | `GET /api/defi/tvl-chain` |
| `top_protocols` | `GET /api/defi/protocols` |
| `yields` | `GET /api/defi/yields` |
| `top_yields` | `GET /api/defi/yields/top` |
| `yields_by_chain` | `GET /api/defi/yields/by-chain` |
| `yields_by_token` | `GET /api/defi/yields/by-token` |
| `yield_pool_detail` | `GET /api/defi/yields/pool` |
| `fx_rate` | `GET /api/fx/rates` |

### `check_chain` — $0.005 per check

| `metric` | Underlying endpoint |
|---|---|
| `gas_price` | `GET /api/gas/base` or `GET /api/gas/ethereum` |
| `latest_block` | `GET /api/chain/block` |

`GET /api/chain/gas` is a documented, unwired alias: its schema only ever
accepts `chain=base\|ethereum`, so it returns exactly the same data as the
two dedicated gas routes above and adds no reachable coverage of its own.

### `search_web` — $0.005 (search_google, read_page, trending_hn), $0.01 (search_semantic), $0.02 (extract_from_page)

| `mode` | Underlying endpoint |
|---|---|
| `search_google` | `POST /api/search/serp` |
| `search_semantic` | `POST /api/search/web` |
| `read_page` | `POST /api/web/read` |
| `extract_from_page` | `POST /api/web/extract` |
| `trending_hn` | `GET /api/hn/top` |

### `ai_task` — $0.01 (summarize, translate, classify), $0.02 (extract)

| `task` | Underlying endpoint |
|---|---|
| `summarize` | `POST /api/ai/summarize` |
| `translate` | `POST /api/ai/translate` |
| `classify` | `POST /api/ai/classify` |
| `extract` | `POST /api/ai/extract` |

That's all 33 endpoints of the underlying catalog, reached through 5 tools.

## Related

This server wraps the same 33 x402-seller endpoints as
[`x402-seller-mcp`](https://www.npmjs.com/package/x402-seller-mcp) (npm), but
groups them into 5 general-purpose tools instead of one tool per endpoint. If
you want the full endpoint-by-endpoint catalog — every route as its own MCP
tool, generated live from the origin's discovery document — use
`x402-seller-mcp` instead.

## Development

```bash
git clone <this repo>
cd agent-data-mcp
npm install
node server.js          # runs on stdio, waits for a client
```

Two test scripts, both run by `npm test`:

- `test/routing-test.mjs` — pure unit test, no network: calls every tool's
  internal router directly and asserts the exact URL/method/body it builds,
  for one case per underlying endpoint. This is the definitive proof of the
  tool → endpoint mapping above.
- `test/manual-test.mjs` — spawns the real server over stdio (exactly like
  an MCP client would) and calls each tool for real, in unpaid mode, against
  the live origin — free, since no wallet is configured. Set
  `RUN_PAID_TEST=1` with `BUYER_PRIVATE_KEY` set to also run one real paid
  call (~$0.005 on Base).

## License

MIT