# docconv-mcp

<!-- mcp-name: io.github.nicklee002e/docconv-mcp -->

MCP server for **[Doc_Conv](https://converter.crepe.fund)** — convert PDF / Word / Excel /
PowerPoint documents to **Markdown**, paid **per conversion with USDC on Base** via the
[x402](https://x402.org) protocol (gasless, EIP-3009). No account, no API key: the agent signs a
USDC payment and the service returns Markdown.

Why? Feeding formatted files (PDF/PPT/DOCX) straight into an LLM can cost **5–50× more tokens**
than the same content as Markdown. This lets an agent cheaply pre-convert documents before use.

## Tools

- **`estimate_conversion(file_path)`** — free price quote (`pages`, `credits`, `priceUsdc`,
  `jobId`, `jobToken`). No payment, no side effects.
- **`convert_document(file_path, max_usdc=1.0, poll_seconds=300)`** — pays via x402 (rejects if the
  quote exceeds `max_usdc`) and converts. Returns inline `markdown` for text documents, or a
  `downloadUrl` (zip) when the document contains images.

## Install

Published to PyPI as [`docconv-mcp`](https://pypi.org/project/docconv-mcp/). Run with
[`uvx`](https://docs.astral.sh/uv/) (no install) or `pip install docconv-mcp`.

## Configuration (env)

| Variable | Description | Default |
|---|---|---|
| `DOC_CONV_AGENT_PK` | Private key of the agent's **Base wallet** (must hold USDC). Signs x402 payments. **Secret — never commit or share.** | *(required)* |
| `DOC_CONV_BASE_URL` | Doc_Conv service base URL. Override only if self-hosting. | `https://converter.crepe.fund` |

The wallet needs **USDC on Base**; gas is paid by the service's x402 facilitator (the agent needs
no ETH). Pricing is by document size: 50 pages = 1 credit = 0.2 USDC (call `estimate_conversion`
for the exact amount).

## Claude Desktop / Claude Code (`claude_desktop_config.json` or `.mcp.json`)

```json
{
  "mcpServers": {
    "doc-conv": {
      "command": "uvx",
      "args": ["docconv-mcp"],
      "env": { "DOC_CONV_AGENT_PK": "0x<your-agent-wallet-private-key>" }
    }
  }
}
```

Claude Code one-liner:

```bash
claude mcp add doc-conv -- env DOC_CONV_AGENT_PK=0x<key> uvx docconv-mcp
```

## Example

> "Convert `~/papers/report.pdf` to Markdown."

The agent calls `estimate_conversion` to see the price (e.g. 0.3 USDC), then `convert_document` to
pay via x402 and return the Markdown. If conversion fails, the paid credit is retained on the payer
wallet for reuse.

> ⚠️ `convert_document` spends real USDC. Use `max_usdc` to cap per-call cost.

## Links

- Service: https://converter.crepe.fund
- Agent API (OpenAPI): https://converter.crepe.fund/openapi.json
- x402 discovery: https://converter.crepe.fund/.well-known/x402.json
- Operator: [CREPE Foundation](https://crepe.fund)

## License

MIT © CREPE Foundation