Skip to content

Add Revnuvo MCP server — x402-paid domain intelligence tools #4559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
hardeyhemy wants to merge 2 commits into from
+906 −0
Closed

Add Revnuvo MCP server — x402-paid domain intelligence tools #4559

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0a29456
Add Revnuvo MCP server — x402-paid domain intelligence
Jul 28, 2026
fe21bae
fix: resolve TypeScript build errors for CI
Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
338 changes: 338 additions & 0 deletions src/revnuvo/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,338 @@
# Revnuvo x402 MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the **Revnuvo x402 paid APIs** as AI-callable tools. Each tool call transparently
performs the [x402 v2](https://x402.org) payment flow — signing a USDC payment
on Base, retrying the request with the `X-Payment` header, and returning the
unlocked JSON payload.

> **One sentence:** Claude Desktop / Cursor can verify a domain, dump its DNS,
> or run a full domain assessment by paying $0.001–$0.05 in USDC per call,
> without you writing a line of payment code.

---

## Tools Exposed

| Tool | Upstream Endpoint | Price | Returns |
|------|-------------------|-------|---------|
| `verify_domain` | `POST https://revnuvo-resource.revnuvo.workers.dev/domain/verify` | **$0.001** USDC | Reachability + registration metadata |
| `dns_lookup` | `POST https://revnuvo-resource.revnuvo.workers.dev/domain/dns` | **$0.002** USDC | Full DNS record dump (A / AAAA / MX / NS / TXT / CNAME / SOA) |
| `assess_domain` | `POST https://revnuvo-resource.revnuvo.workers.dev/domain/assess` | **$0.005** USDC | Quick trust-score snapshot (verification + DNS + scoring) |
| `assess_domain_full` | `POST https://assess.revnuvo.site/assess/domain` | **$0.05** USDC | Full Revnuvo assessment report (security, email, threat-intel, revenue-intel, recommendations) |

All four tools take a single argument:

```jsonc
{ "domain": "example.com" } // bare hostname, no scheme or path
```

---

## Prerequisites

1. **Node.js ≥ 20** installed locally.
2. **An EVM wallet** that holds USDC on Base. You need the wallet's **private
key** (hex, with or without `0x` prefix). Each tool call deducts the
per-call price from this wallet. To fund a wallet with USDC on Base, see
[Coinbase Wallet](https://wallet.coinbase.com) or any Base-compatible
bridge.
3. **MCP client** — Claude Desktop, Cursor, or any other client that speaks
MCP over stdio.

> **Security note:** Your private key never leaves your machine. All payment
> signing happens locally inside `@revnuvo/x402` using `viem`. The key is
> only used to sign the x402 payment payload; it is never transmitted to
> Revnuvo or to Smithery.

---

## Installation

### Option A — Build from source (recommended for local development)

```bash
# 1. Clone or copy the four files into a working directory:
# revnuvo-mcp-server.ts
# package.json
# smithery.yaml
# README.md

# 2. Install dependencies
npm install

# 3. Compile the TypeScript
npm run build
# -> emits build/index.js

# 4. Verify the binary runs (needs WALLET_PRIVATE_KEY in env)
export WALLET_PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
node build/index.js
# Should print to stderr:
# [revnuvo-mcp] Server started on stdio. Network=base ...
```

### Option B — Install as an npm package (once published)

```bash
npm install -g revnuvo-x402-mcp
```

### Option C — Run on Smithery.ai (zero local install)

Use the `smithery.yaml` in this directory. Push the repo to GitHub, then import
it into Smithery. Smithery will install deps, build, and host the server over
HTTP for you. You'll be prompted for `WALLET_PRIVATE_KEY` in the Smithery UI
(it's marked `secret: true` so it's never logged).

---

## Configure in Claude Desktop

Claude Desktop reads its MCP servers from a JSON config file:

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

Open (or create) that file and add the `revnuvo-x402-mcp` entry:

```jsonc
{
"mcpServers": {
"revnuvo-x402-mcp": {
"command": "node",
"args": ["/absolute/path/to/revnuvo-x402-mcp/build/index.js"],
"env": {
"WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
"REVNUVO_FACILITATOR": "https://facilitator.xpay.sh",
"REVNUVO_NETWORK": "base"
}
}
}
}
```

**Important:** Replace `/absolute/path/to/...` with the real absolute path to
your `build/index.js`. Relative paths will not work.

**Restart Claude Desktop** completely (not just reload). After restart, you
should see four new tools available in any chat:

- `verify_domain`
- `dns_lookup`
- `assess_domain`
- `assess_domain_full`

Try it with a prompt like:

> *"Use the assess_domain_full tool to assess stripe.com and summarize the
> trust score and security posture."*

Claude will invoke the tool, the MCP server will pay $0.05 USDC on Base from
your wallet, and Claude will summarize the returned JSON.

---

## Configure in Cursor

Cursor supports MCP servers via `~/.cursor/mcp.json` (global) or
`.cursor/mcp.json` (per-project):

```jsonc
{
"mcpServers": {
"revnuvo-x402-mcp": {
"command": "node",
"args": ["/absolute/path/to/revnuvo-x402-mcp/build/index.js"],
"env": {
"WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
"REVNUVO_FACILITATOR": "https://facilitator.xpay.sh",
"REVNUVO_NETWORK": "base"
}
}
}
}
```

After saving, open Cursor Settings → MCP → click the refresh icon next to
`revnuvo-x402-mcp`. The four tools become available to Cursor Chat and
Cursor Agent.

---

## Configure in any MCP-compatible client (generic stdio)

The server speaks MCP over stdio. Any client that supports the standard
`command` + `args` + `env` MCP launcher pattern can launch it:

```yaml
# pseudocode
command: node
args:
- /absolute/path/to/build/index.js
env:
WALLET_PRIVATE_KEY: 0x...
REVNUVO_FACILITATOR: https://facilitator.xpay.sh
REVNUVO_NETWORK: base
```

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `WALLET_PRIVATE_KEY` | **Yes** | — | Hex private key of the wallet that pays per call. Accepts `0x`-prefixed or bare hex. |
| `REVNUVO_FACILITATOR` | No | `https://facilitator.xpay.sh` | x402 facilitator URL that verifies payments server-side. Override for testnet or self-hosted facilitators. |
| `REVNUVO_NETWORK` | No | `base` | Settlement network. Use `base` for mainnet or `base-sepolia` for testnet. |

---

## How the x402 Payment Flow Works

Every tool call follows the same five-step dance — handled automatically by
the `@revnuvo/x402` SDK:

```
┌──────────────┐ ┌──────────────────┐
│ MCP client │ │ Revnuvo API │
│ (Claude / │ │ (Cloudflare) │
│ Cursor) │ │ │
└──────┬───────┘ └────────┬─────────┘
│ POST /domain/verify {"domain":"example.com"} │
│ ─────────────────────────────────────────────────>│
│ │
│ 402 Payment Required │
│ WWW-Authenticate: x402 ... │
│<─────────────────────────────────────────────────│
│ │
│ SDK signs USDC payment on Base locally │
│ (no key ever leaves the process) │
│ │
│ POST /domain/verify {"domain":"example.com"} │
│ X-Payment: <signed-payload> │
│ ─────────────────────────────────────────────────>│
│ │
│ Server verifies payment via facilitator │
│ https://facilitator.xpay.sh │
│ │
│ 200 OK + JSON result │
│ X-Payment-Response: <receipt> │
│<─────────────────────────────────────────────────│
│ │
│ Result returned to MCP client as tool output │
```

---

## Development

```bash
# Install deps
npm install

# Watch mode
npm run dev

# Run locally with hot reload (skip the build step)
WALLET_PRIVATE_KEY=0x... npx tsx revnuvo-mcp-server.ts

# Type-check without emitting
npx tsc --noEmit
```

### Project layout

```
revnuvo-x402-mcp/
├── revnuvo-mcp-server.ts # source — single-file MCP server
├── package.json # deps, scripts, MCP launcher metadata
├── smithery.yaml # Smithery.ai deployment config
├── README.md # this file
├── tsconfig.json # (you should add this; see below)
└── build/
└── index.js # emitted by `npm run build`
```

### Recommended `tsconfig.json`

If you don't already have one, drop this in:

```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "build",
"rootDir": ".",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true
},
"include": ["revnuvo-mcp-server.ts"]
}
```

---

## Troubleshooting

**`WALLET_PRIVATE_KEY environment variable is required`**
The server exits immediately if the env var is missing. Set it before
launching the MCP server (in `claude_desktop_config.json` `env` block, in
your shell, or in the Smithery UI).

**`Insufficient USDC balance` / transaction reverts**
Top up your wallet with USDC on Base. Each `assess_domain_full` call costs
$0.05; a $5 USDC balance gives you ~100 calls. Cheaper tools (`verify_domain`
at $0.001) let you stretch that to ~5,000 calls.

**Claude Desktop doesn't see the tools**
1. Confirm the absolute path in `args` is correct.
2. Confirm `build/index.js` actually exists (`npm run build`).
3. Fully quit Claude Desktop (Cmd+Q on macOS) and reopen.
4. Check Claude Desktop's MCP logs at
`~/Library/Logs/Claude/mcp*.log` (macOS).

**Tool returns `402 Payment Required` after retry**
The facilitator may be unreachable. Verify
`curl https://facilitator.xpay.sh/health` returns 200. If you're running
against a custom facilitator, set `REVNUVO_FACILITATOR` accordingly.

**Tool returns `401` / `403` after retry**
The signature is being rejected — most commonly because the wallet address
derived from `WALLET_PRIVATE_KEY` doesn't match the payment sender expected by
the facilitator. Re-check the key.

---

## Privacy & Security

- **Your private key never leaves your machine.** The `@revnuvo/x402` SDK uses
`viem` to sign the x402 payment payload locally; only the signed payload is
transmitted.
- **Domain queries are sent to Revnuvo.** The domain you ask about is
transmitted to the Revnuvo API over HTTPS. Revnuvo logs the query for
billing and abuse prevention.
- **Payments are public on Base.** Every USDC transfer settles on-chain and is
visible on Basescan.

---

## License

MIT © Revnuvo Technologies Ltd. See [LICENSE](./LICENSE).

## Links

- **Website:** https://revnuvo.site
- **x402 protocol:** https://x402.org
- **MCP spec:** https://modelcontextprotocol.io
- **Smithery.ai:** https://smithery.ai
- **Facilitator:** https://facilitator.xpay.sh
Loading
Loading