task402

# Task402 Agent Evidence Tools

[![CI](https://github.com/xbckz/task402/actions/workflows/ci.yml/badge.svg)](https://github.com/xbckz/task402/actions/workflows/ci.yml)
[![Live MCP endpoint](https://img.shields.io/badge/MCP-live%20on%20task402.xyz-47d9b3)](https://task402.xyz/mcp)
[![x402 payments](https://img.shields.io/badge/payments-x402%20USDC%20on%20Base-79e7ff)](https://task402.xyz/v1/pricing)
[![Smithery](https://smithery.ai/badge/martin00207/task402)](https://smithery.ai/servers/martin00207/task402)

Give agents bounded evidence from PDFs, public webpages, OpenAPI contracts, and Base chain data. Connect to the hosted **20-tool MCP service** at `https://task402.xyz/mcp`; no local server, API key, or wallet is needed for discovery. Paid calls use x402 v2 USDC on Base. Connecting an MCP host does not automatically give it a payment signer.

## Connect your agent

For Cursor, merge [`examples/cursor.mcp.json`](examples/cursor.mcp.json) into `.cursor/mcp.json`. For VS Code, merge [`examples/vscode.mcp.json`](examples/vscode.mcp.json) into `.vscode/mcp.json`. Other Streamable HTTP clients can use:

```json
{
  "mcpServers": {
    "task402": { "url": "https://task402.xyz/mcp" }
  }
}
```

Initialize the connection and run `tools/list` to inspect executable schemas. With Node.js 24 and this repository's dependencies installed, `npm run discover` performs discovery through the official MCP SDK and prints tool names only. It never calls a paid tool or signs a payment.

Every hosted tool advertises a tool-specific output schema, parameter descriptions, and MCP safety annotations. Agents can therefore plan the result shape and retry behavior from `tools/list` before approving any x402 payment.

| Tools | Billing at the 12 October 2026 live check |
| --- | --- |
| `generate_pdf` | $0.01 per PDF |
| `web_evidence` | $0.005 per public HTTPS page |
| `inspect_openapi` | $0.001 per specification |
| `plan_api_request`, `diff_openapi` | $0.002 per call |
| `get_chain_balance`, `get_chain_transaction`, `get_erc20_balance` | $0.001 per read |
| `get_pdf_job` | Included with generation; requires the job capability |
| `inspect_pdf`, `get_document_map`, `search_document`, `batch_search_document`, `prepare_document_context`, `extract_document_fields`, `read_document`, `verify_document_citation`, `compare_pdfs`, `validate_pdf_text`, `render_pdf_page_region` | Included after paid PDF indexing; requires document capabilities |

PDF indexing is the separate REST operation `POST /v1/documents` ($0.01 per PDF); binary upload is not an MCP tool. Generated PDF download is also REST-only. Read [`/v1/pricing`](https://task402.xyz/v1/pricing) and the payment challenge for current terms before approving payment. Native-text PDF tools do not provide OCR or verify factual truth.

Start with [`docs/FIRST-PAID-CALL.md`](docs/FIRST-PAID-CALL.md) for a challenge, signed retry, and result workflow. Use [`docs/PUBLISHING.md`](docs/PUBLISHING.md) to publish the repository and remote MCP metadata.

## Service architecture

This project converts Markdown into paginated PDF files through one shared service used by REST and MCP. The local runner uses Playwright Chromium and SQLite; the Cloudflare Worker adapter uses Browser Run Quick Actions, D1, and R2. The live payment path uses the official x402 SDK facilitator client, verifies before rendering, and settles only after a PDF artifact is stored.

The paid operations are `generate_pdf`, `ingest_document`, `web_evidence`, OpenAPI inspection/planning/diffing, and fixed-method Base chain reads. Retrieval, citation, batch search, bounded context preparation, and explicit-label field matching are included after indexing. Web evidence is public HTTPS HTML/text only, OpenAPI tools accept caller-supplied JSON and local references only, and chain tools never sign or submit transactions. Input HTML is not executed, remote images and other external resources are omitted or blocked, and hyperlinks are preserved in generated PDFs but never fetched during rendering.

Distribution metadata, conversion guidance, and channel-ready copy live in [`docs/MARKETING.md`](docs/MARKETING.md) and [`docs/LAUNCH-KIT.md`](docs/LAUNCH-KIT.md); the public MCP directory metadata is in [`server.json`](server.json), [`glama.json`](glama.json), and [`lhm.plugin.json`](lhm.plugin.json) for LobeHub.

The detailed agent, discovery, operations, deployment, operator-stats, and security guide is [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md).

## Use the hosted MCP server

No local process is required. Add the Streamable HTTP endpoint to an MCP-compatible client:

```json
{
  "mcpServers": {
    "task402": {
      "type": "http",
      "url": "https://task402.xyz/mcp"
    }
  }
}
```

The server is discoverable without payment. Paid operations return an x402 v2 challenge; the client must inspect the network, USDC asset, recipient, amount, resource, and timeout, obtain explicit wallet approval, then retry the same request with the signed payment. Task402 never receives a private key and never signs or submits transactions for the caller. Start with the [first paid call](https://task402.xyz/docs#first-paid-call), then use [`examples/agent-flow.ts`](./examples/agent-flow.ts) for a complete injected-signer flow.

### What is included

| Capability | Payment | Interface |
| --- | ---: | --- |
| Generate a paginated PDF from Markdown | $0.01 | REST, MCP |
| Index one native-text PDF | $0.01 | REST |
| Search, cite, compare, validate, map, read, extract fields, prepare context, and render | Included after indexing | REST, MCP |
| Bounded public-page evidence | $0.005 | REST, MCP |
| OpenAPI inspect, request plan, and diff | $0.001–$0.002 | REST, MCP |
| Read-only Base balance, transaction, and ERC-20 data | $0.001 | REST, MCP |

Prices, limits, schemas, and payment terms are machine-readable at [`/v1/pricing`](https://task402.xyz/v1/pricing). The service does not provide OCR, JavaScript page rendering, arbitrary API execution, transaction signing, or visual/legal PDF redlining.

The remote MCP server metadata is version `0.3.2` in [`server.json`](./server.json). In the 2026-10-12 audit, the official Registry served `0.2.0`; publishing the new metadata requires the domain publisher proof key, which is intentionally not stored in this workspace. Recheck the live Registry record before claiming the release is published. Paid REST and MCP challenges include x402 Bazaar discovery metadata, and the production facilitator is `https://facilitator.openx402.ai`.

Public discovery pages are available at [`https://task402.xyz/`](https://task402.xyz/), [`/docs#first-paid-call`](https://task402.xyz/docs#first-paid-call), [`/llms.txt`](https://task402.xyz/llms.txt), [`/demo`](https://task402.xyz/demo), [`/v1/tools`](https://task402.xyz/v1/tools), [`/openapi.json`](https://task402.xyz/openapi.json), [`/v1/pricing`](https://task402.xyz/v1/pricing), [`/.well-known/x402.json`](https://task402.xyz/.well-known/x402.json), [`/.well-known/mcp/server-card.json`](https://task402.xyz/.well-known/mcp/server-card.json), [`/.well-known/ai-plugin.json`](https://task402.xyz/.well-known/ai-plugin.json), and [`/sitemap.xml`](https://task402.xyz/sitemap.xml). They give agents and directory crawlers a clear entry point without requiring payment or an operator credential. Registry publication improves discoverability for clients that sync the MCP Registry; it does not create synthetic traffic or guarantee calls.

The public quickstart includes focused workflows for [citation verification](https://task402.xyz/docs/citation-verification), [PDF revision comparison](https://task402.xyz/docs/compare-pdfs), and [reducing PDF context before model calls](https://task402.xyz/docs/reduce-pdf-context). Copy-paste client files are in [`examples/agent-flow.ts`](./examples/agent-flow.ts), [`examples/cursor.mcp.json`](./examples/cursor.mcp.json), and [`examples/vscode.mcp.json`](./examples/vscode.mcp.json). The TypeScript example obtains unsigned generation and indexing challenges and exposes explicit retry methods for a separately approved wallet payload; it never signs or submits a payment automatically.

When you are ready for one controlled live payment, follow [`docs/TEST-TRANSACTION.md`](./docs/TEST-TRANSACTION.md). It requires an external wallet signer and never asks for a private key.

For a disposable local test wallet, the repository also includes a guarded terminal helper: `npm run test:live`. It validates the live Base/USDC challenge before signing, requires `TASK402_CONFIRM=YES`, downloads the PDF, and never prints the payment payload or capability. See the terminal section of the test guide for setup and cleanup.

To reproduce an MCP agent exactly, use `npm run test:agent`; it performs discovery, receives the structured x402 challenge, signs through the official EVM client, retries with `_meta["x402/payment"]`, checks the job through `get_pdf_job`, and downloads the result.

## Local development

Use Node.js 24 or newer (verified with Node 24.13; local durable state uses `node:sqlite`). From this directory:

```powershell
npm ci
Copy-Item .dev.vars.example .dev.vars
npm run setup:browser
npm run dev
```

The local server binds only to `127.0.0.1:8787` and accepts only the matching loopback/localhost Host authority (plus the configured public authority in live mode). The local web-evidence adapter resolves every hostname before fetching and rejects private, loopback, link-local, and reserved DNS destinations; the hosted Worker relies on its platform egress boundary plus the same URL checks. The example `.dev.vars` enables an explicit no-payment development bypass, and the bypass exists only in `src/local.ts`; `src/worker.ts` rejects it unconditionally. If `.dev.vars` is absent, the server starts with payments unconfigured and paid generation fails closed. Local jobs and artifacts are durable under `.data/` and are ignored by Git.

If Playwright cannot find its pinned Chromium downloa