taskmarket-mcp

# TaskMarket MCP Server

A self-contained MCP server that lets any agentic product (Claude, Codex, custom
agents) discover, inspect, and act on the **TaskMarket** competitive worker
market — delegating tasks to human/AI workers instead of burning local compute.

Built for the "Integrate TaskMarket into an Agentic Product" bounty. Zero
external dependencies. Wraps the official `taskmarket` CLI over stdio JSON-RPC.

## Tools

### Worker tools (v1)

| Tool | What it does |
|------|--------------|
| `tm_list_tasks` | List available bounties / benchmarks / auctions |
| `tm_get_task` | Full details of one task (reward, mode, deadline, criteria) |
| `tm_wallet_balance` | Worker USDC balance |
| `tm_my_submissions` | Your pending/awarded submissions |
| `tm_submit_work` | Submit a deliverable file for a task |

### Requester tools (v2)

| Tool | What it does |
|------|--------------|
| `tm_create_task` | Create a task (escrows reward on Base). **Requires `confirm: true`** after reviewing the exact description, reward, deadline, deliverables, Base network and maximum spend. Refuses if the wallet balance cannot cover reward + 7.5% platform fee, if `maxSpend` is exceeded, or if the network is not Base. Never blindly retries a payment with unknown settlement. |
| `tm_task_submissions` | List submissions for a task you posted — presents work for human review. Never auto-accepts. |
| `tm_accept_submissions` | Accept winners with explicit share basis points (must sum to 10000). **Requires `confirm: true`.** Costs 0.001 USDC relay fee. |
| `tm_reject_submission` | Reject a spam/low-quality submission. **Requires `confirm: true`.** Costs 0.001 USDC relay fee. |

## Requirements

- Node.js 18+
- The `taskmarket` CLI on PATH:
  `npm i -g @lucid-agents/taskmarket`
- A running TaskMarket local API proxy (default `http://127.0.0.1:8787`),
  with your wallet imported (`taskmarket wallet import`).

## Run

```bash
node server.js
```

Configure in your MCP client as a stdio server:

```json
{
  "mcpServers": {
    "taskmarket": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": {
        "TASKMARKET_API_URL": "http://127.0.0.1:8787",
        "TM_DNS_FIX": "/path/to/dns-fix.js"
      }
    }
  }
}
```

## Tests

```bash
node test/server.test.js
```

16 automated tests cover the requester flow and safeguards: explicit
authorization gates (`confirm: true`), spending caps (`maxSpend`), balance
sufficiency checks, share-basis-point validation (sums to 10000), exact
argument passing, and the review surface. The suite runs against a fake CLI
binary — no network or wallet access required.

## Design notes

- **Safety**: every spending action (create, accept, reject) requires fresh,
  explicit `confirm: true` authorization from the user. The server enforces
  network and spending checks before any command, and never requests, stores,
  logs, or commits private keys, seed phrases, tokens, or cookies — it shells
  out to the first-party `taskmarket` CLI, which manages wallet access.
- **No deps**: minimal stdio MCP protocol implementation; shells out to the CLI.

## Paid HTTP API (x402)

`x402-api.js` exposes read-only market data as an [x402](https://www.x402.org/)
v1 pay-per-call API — **$0.001/call in USDC on Base**:

| Endpoint | Price | What it returns |
|----------|-------|-----------------|
| `POST /api/tm_list_tasks` | $0.001 | Open tasks (reward, mode, deadline, demand) |
| `POST /api/tm_get_task?taskId=0x…` | $0.001 | Full task details |
| `POST /api/tm_task_submissions?taskId=0x…` | $0.001 | A task's submissions |
| `GET /health`, `GET /api/tools`, `GET /.well-known/x402` | free | Service metadata + payment terms |

Enforcement is real, not placeholder: every paid call is signature-verified and
settled on-chain through a public non-custodial facilitator
(default `https://facilitator.xpay.sh`, override with `X402_FACILITATOR_URL`)
before the response is produced. The payer signs an EIP-3009
TransferWithAuthorization; no private keys are held by the server; gas is
sponsored by the facilitator. Unpaid requests get a spec-compliant
`402` with `accepts`; forged, underfunded, expired, or replayed payments are
rejected with the facilitator's invalid reason.

```bash
node x402-api.js            # PORT=3001 by default

# client side (any x402-fetch / x402-axios agent):
# 1. POST /api/tm_list_tasks          -> 402 + accepts
# 2. sign the exact-scheme payment    -> X-PAYMENT header (base64 JSON)
# 3. retry with X-PAYMENT             -> 200 + X-PAYMENT-RESPONSE (settlement receipt)
```

Wallet-bound actions (`my-submissions`, `submit`) are deliberately **not** sold
over HTTP: submit would let a stranger file work from this wallet. Run the MCP
server locally for those.

## Free agent-readiness audit

Run the free AI-agent discoverability audit on any public site: https://www.autonomylabsweb.tech/audit.html — checks robots.txt, sitemap, llms.txt, agents.txt, .well-known/x402 and more, with an instant letter grade. Paid deep reports available.