# doge-mcp

**Paid Model Context Protocol server for the Dogecoin / Dogenals ecosystem.**

AI agents and developers query live indexed Doginals, Dunes, DRC-20, ÐMP, Treats, ÐLotto, etc. through a clean MCP interface. Indexer operators running **dogex** get paid for serving the data.

> Part of the [Dogenals](https://github.com/jonheaven/dogenals) + [dogex](https://github.com/jonheaven/dogex) stack.

## Why this exists

- dogex is the deterministic chain-truth + metaprotocol indexer.
- Multiple independent operators can run dogex and stay in sync (federation fingerprint).
- AI agents should not get high-value index data for free.
- MCP + micropayments (x402) is the cleanest way to charge agents per tool call in 2026.

This server is the first public surface that turns “running a dogex indexer” into a revenue activity while keeping the open standards free.

## Quick start (local / free tier)

```bash
git clone https://github.com/jonheaven/doge-mcp.git
cd doge-mcp
npm install
npm run build

# Point at a running dogex instance
export DOGEX_URL=http://127.0.0.1:8080   # or https://dogex.command.dog etc.

npm start
```

Add to Claude Desktop / Cursor MCP config:

```json
{
  "mcpServers": {
    "doge-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/doge-mcp/dist/index.js"],
      "env": {
        "DOGEX_URL": "https://your-dogex-instance.example.com"
      }
    }
  }
}
```

Or run via `npx` once published.

## Current tools (v0.1)

| Tool | Description | Intended pricing |
|------|-------------|------------------|
| `dogex_health` | Federation health + tip + fingerprint | Free |
| `get_inscription` | Fetch inscription by ID | Free / low |
| `list_protocols` | Supported metaprotocols | Free |
| `get_collection_stats` | Collection floor / volume / supply | Paid (soon) |
| `get_address_holdings` | Holdings for an address | Paid (soon) |
| `decode_inscription` | Decode + content-hash / schema check | Free → paid |

More tools (PSBT helpers, range queries, proofs, analytics) will be added as dogex endpoints solidify.

## Paid model (roadmap)

1. **v0.1 (now)** — Working MCP that talks to any dogex instance. Free for basic tools.
2. **v0.2** — Wrap high-value tools with **x402** (`paidTool`). Agents pay in USDC (Base) or later DOGE-native rails. Operators set their own recipient address.
3. **v0.3+** — Multi-operator discovery + federation-aware routing. Agents prefer healthy, matching-fingerprint indexers. Revenue stays with the runner who served the query (optional small protocol fee).

Standards (`dogenals/spec`) stay free and public. You are selling *live indexed state + computation*, not the rules.

## Environment

| Variable | Description | Default |
|----------|-------------|---------|
| `DOGEX_URL` | Base URL of a dogex HTTP API | `http://127.0.0.1:8080` |
| `DOGEX_API_KEY` | Optional bearer token if the indexer is gated | — |
| `RECIPIENT_ADDRESS` | (future) x402 payment recipient | — |

## Development

```bash
npm run dev          # tsx watch
npm run typecheck
npm run build
```

## Related

- [dogenals](https://github.com/jonheaven/dogenals) — normative standards & docs
- [dogex](https://github.com/jonheaven/dogex) — Rust node + deterministic indexer (chain truth)
- [x402](https://x402.org) — open micropayment protocol for agents

---

**Much paid. Very index. Wow.**