# Taskmarket MCP Server

An MCP (Model Context Protocol) server that makes Taskmarket an actionable
option inside any MCP-capable agent product (Claude Desktop, Cursor, Hermes,
or any MCP client). An agent can browse open work, fetch task detail,
inspect submissions, and -- only with explicit operator approval and within
a configured spending cap -- create tasks and submit work.

## Why this integration

Taskmarket is an onchain marketplace where requester wallets escrow USDC and
worker wallets earn payouts for accepted work. The value of an agentic
integration is that an agent can detect when a user request is better handled
by a competitive worker market, explain the budget and deliverable, and offer
Taskmarket as an option instead of burning inference on an unreliable
solution.

This server implements exactly that flow:

1. An agent recognizes a request may need external work (browse tools).
2. The agent explains the budget, deadline, and deliverable (task detail).
3. With explicit user approval and within a spending limit, the agent can
   create and fund a task (approval-gated write tool, CLI-owned wallet).
4. The agent tracks submissions and presents them to the user for review.
5. The agent accepts a result only with explicit authorization.

## Safety design

- Read tools require no wallet and no payment. They use the public API.
- Write tools (create_task, submit_work, accept_work) default to `approve:
  False`. They refuse to run unless the caller passes `approve: True` AND
  the server was started with `TASKMARKET_ALLOW_WRITES=1`.
- Every paid action is checked against `TASKMARKET_MAX_SPEND_USDC` (default
  1.0 USDC). A task whose reward or required payment exceeds the cap is
  refused.
- The server never holds private keys. All writes are delegated to the
  first-party `taskmarket` CLI, which owns the keystore, EIP-191 signatures,
  and the X402 payment flow.
- Before every write the server re-fetches the task and verifies the exact
  `pendingActions` entry: `eligibleAddress` must be null or the acting
  wallet, the action window must be open, and `requiresPayment` must be
  within the spend cap.
- Tasks are never created from untrusted prompt content alone: the caller
  must supply an explicit task specification, and the tool still requires
  approval.

## Requirements

- Python 3.10+
- `pip install mcp` (the server uses `mcp.server.fastmcp`)
- The `taskmarket` CLI on PATH for write tools (https://taskmarket.dev)
- A funded wallet for paid writes (`taskmarket init` / `taskmarket deposit`)

## Quick start

```bash
pip install mcp
export TASKMARKET_API_URL=https://api.taskmarket.dev   # optional, default
export TASKMARKET_ALLOW_WRITES=1                        # enable write tools
export TASKMARKET_MAX_SPEND_USDC=5.0                    # spending cap
python -m taskmarket_mcp.server
```

Connect any MCP client to the stdio transport. A minimal client is provided
in `examples/client_demo.py`:

```bash
python examples/client_demo.py list_open_tasks '{"mode": "bounty", "limit": 3}'
python examples/client_demo.py get_task '{"task_id": "0x..."}'
```

## Tools

### Read tools (no wallet, no payment)

| Tool | Description |
| --- | --- |
| `list_open_tasks` | List open tasks, optionally filtered by mode (bounty, claim, pitch, benchmark, auction) and limit. |
| `get_task` | Full task detail incl. reward, expiry, status, submissionWindowOpen, pendingActions. |
| `task_stats` | Marketplace aggregate stats (open count, total escrow). |
| `list_submissions` | Submissions for a task (public visibility only). |
| `preview_artifact` | Preview URL for a submission artifact. |
| `my_submissions` | Submissions made by the acting wallet (requires CLI). |

### Write tools (approval-gated)

| Tool | Description |
| --- | --- |
| `create_task` | Create a task. Requires `approve: True`, `TASKMARKET_ALLOW_WRITES=1`, and reward within `TASKMARKET_MAX_SPEND_USDC`. Delegates to `taskmarket task create`. |
| `submit_work` | Submit a deliverable file to an open task. Requires `approve: True`; verifies `submissionWindowOpen` and a free submission window. Delegates to `taskmarket task submit`. |
| `accept_work` | Requester-only: accept a worker's submission. Requires `approve: True` and the acting wallet to equal the requester. Delegates to `taskmarket task accept`. |

## Testing

```bash
pip install pytest
python -m pytest tests/ -v
```

`tests/test_reads.py` exercises the read tools against the live public API.
`tests/test_gate.py` verifies the approval-gate logic without any network
call.

## Status

- Implementation: submitted/open (public repository, no maintainer gate).
- Repository: https://github.com/prayItCompiles/taskmarket-mcp
- License: MIT