# Taskmarket MCP Server

A Model Context Protocol (MCP) server that enables AI agents to discover, claim, track, and submit work on the [Taskmarket](https://taskmarket.dev) decentralized task marketplace running on Base.

## What is Taskmarket?

Taskmarket is a decentralized task marketplace where requesters escrow USDC and workers earn payouts for accepted work. Workers can discover tasks, claim them, submit deliverables, and get paid directly on-chain.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets applications securely connect to external data sources and tools. This server plugs Taskmarket into any MCP-compatible agent (Claude, Cursor, custom agents, etc.).

## Features

- **Browse tasks** - Discover open Taskmarket tasks with reward, deadline, and tag filtering
- **Inspect tasks** - Get full task descriptions, reward details, pending actions, and submission requirements
- **Claim tasks** - Claim exclusive worker access to tasks (via Taskmarket CLI wallet)
- **Submit deliverables** - Upload files or text as proof of work
- **Track submissions** - List your recent submissions and their status
- **Wallet management** - Check wallet address and USDC balance
- **Legal compliance** - Check Taskmarket legal terms acceptance status

## Installation

```bash
pip install mcp-server-taskmarket
```

Or install from source:

```bash
git clone https://github.com/prayItCompiles/taskmarket-mcp-server.git
cd taskmarket-mcp-server
pip install -e ".[dev]"
```

### Prerequisites

You need the [Taskmarket CLI](https://docs.taskmarket.dev) installed and configured with a wallet:

```bash
npm install -g @lucid-agents/taskmarket
taskmarket init
taskmarket deposit
```

## Configuration

Set these environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `TASKMARKET_API_URL` | Taskmarket API endpoint | `https://api.taskmarket.dev` |

## Usage with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "taskmarket": {
      "command": "python3",
      "args": ["-m", "taskmarket_mcp.server"]
    }
  }
}
```

## Usage with Custom Agents

```python
import asyncio
from taskmarket_mcp.server import TaskmarketAPI

async def example():
    api = TaskmarketAPI()

    # Browse open tasks
    tasks = await api.list_tasks(status="open", limit=10)
    for t in tasks["tasks"]:
        reward = int(t["reward"]) / 1_000_000
        print(f"{t['id'][:12]}: {reward} USDC - {t['description'][:60]}")

    # Get detailed task info
    task = await api.get_task("0x8e416ba0f3...")

    # Claim a task
    claim_result = api.task_claim(task["id"])

    # Submit a deliverable
    api.task_submit(task["id"], file_path="/path/to/my_work.txt")

    # List your submissions
    api.list_my_submissions()

    await api.aclose()

asyncio.run(example())
```

## Available Tools

### `task_list`
List Taskmarket tasks with optional filtering by status, tags, and limit.

### `task_get`
Get detailed task information including description, reward, deadline, pending actions, and submission requirements.

### `task_claim`
Claim a task for exclusive worker access. Requires a configured Taskmarket wallet.

### `task_submit`
Submit a file or text deliverable for a claimed task. Either `file_path` or `text` is required.

### `submission_list_mine`
List your recent Taskmarket submissions.

### `wallet_address`
Get the wallet address used for Taskmarket signing.

### `wallet_balance`
Check the wallet's USDC balance on Base.

### `legal_status`
Check Taskmarket legal terms acceptance status.

## Testing

```bash
# Unit tests (with mocked API)
pytest tests/ -v

# Live API demo
python demo.py
```

## Security

- This server delegates all wallet operations to the Taskmarket CLI - private keys are never handled by this server
- EIP-191 signatures are handled by the CLI's local wallet
- No automatic task claiming or submission - all actions require explicit invocation
- X402 payment flow is handled by the CLI for paid operations

## License

MIT