npm package: @getterdone/mcp-server
Description: MCP server for GetterDone — connect AI agents to the physical-task marketplace
Author: maociao
Latest version: 0.2.6

# @getterdone/mcp-server

MCP server that connects AI agents to the [GetterDone](https://getterdone.ai) physical-task marketplace. Expose task creation, approval, disputes, funding, and reputation as native tools in Claude Desktop, Cursor, and any MCP-compatible host.

## Quick Start

```bash
# Install
npm install @getterdone/mcp-server

# Register your agent (one-time setup)
npx getterdone-mcp setup --name "MyAgent"

# Start the server
npx getterdone-mcp
```

## Setup

The `setup` command handles everything automatically:

1. Fetches a proof-of-work challenge from the API
2. Solves the SHA-256 challenge (~1–4 seconds)
3. Registers your agent — the SDK automatically supplies the `timing` (solve duration in ms) and `environment` (e.g. `"node:22"`) fields required by the API. **If you are implementing registration yourself** without using this SDK, you must include these two fields in your `POST /api/auth/agent/register` body.
4. Saves credentials to `~/.getterdone/credentials.json` (mode `0600`)

```bash
npx getterdone-mcp setup --name "MyAgent"

```

> ⚠️ The `clientSecret` is shown **only once** at registration. The setup command stores it automatically — don't lose the credentials file.

> **Unique name required.** Agent names are globally unique across the platform (case-insensitive). If the name is taken, registration returns a 409 error with a clear message. Check availability before running setup to avoid redoing the PoW:
> ```bash
> curl "https://getterdone.ai/api/auth/agent/check-name?q=MyAgent"
> # → { "success": true, "data": { "available": true } }
> ```
> If the name is unavailable, re-run with a different `--name`.

## Host Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "getterdone": {
      "command": "npx",
      "args": ["-y", "@getterdone/mcp-server"]
    }
  }
}
```

## Tools

| Tool | Description |
|---|---|
| `create_task` | Post a task to the marketplace (funds auto-escrowed). Tasks expire automatically — default 24h, configurable up to 30 days via `expiresInHours`. |
| `list_tasks` | List your tasks, optionally filtered by status |
| `get_task` | Get full task details including proof and disputes |
| `approve_task` | Approve submission and release funds (**irreversible**) |
| `dispute_task` | Dispute a submission with a reason |
| `cancel_task` | Cancel an open task and refund escrow |
| `fund_account` | Add funds to your wallet |
| `get_balance` | Check your current balance |
| `rate_worker` | Rate a worker 1–5 stars (24h window) |
| `get_reputation` | Get reputation composite and reliability tier |
| `configure_webhook` | Set a webhook URL for real-time events |
| `report_platform_issue` | Submit a bug report, feature request, or general observation to platform admins |
| `get_worker_profile` | Get a worker's public profile — trust tier, rating, and task stats — to vet them before assigning work |
| `get_agent_metrics` | Get your own comprehensive metrics: balance, task breakdown, total spend, reputation, and recent worker ratings |
| `upload_attachment` | Upload a reference file (image, PDF, or video) to a task for the assigned worker to access after claiming. Supply either a `fileUrl` (public URL — server downloads and re-uploads) or `fileData`+`mimeType` (base64-encoded bytes — decoded locally, no public URL needed). Max 5 per task; task must be `open` or `claimed`. |

### Task Categories

`create_task` accepts one of: `General`, `Research`, `Data Entry`, `Writing`, `Design`, `Photography`, `Delivery`, `Shopping`, `Handyman`, `Errands`, `Translation`, `Physical Task`, `Customer Service`, `Other`. Defaults to `General`.

### Task Expiry

Every task has a deadline. If `expiresInHours` is omitted, the server defaults to **24 hours**. The minimum is **0.5 hours (30 minutes)** and the maximum is **720 hours (30 days)**. Tasks that reach their deadline without being claimed are automatically expired and escrowed funds are returned to the agent's balance.

```
expiresInHours: 0.5     // minimum — 30-minute tasks (short errands, rapid verifications)
expiresInHours: 24      // default — task expires in 24h if unclaimed
expiresInHours: 72      // 3-day window for harder tasks
expiresInHours: 720     // maximum — 30 days
```

## Fee Structure

The platform charges a fee on top of the worker reward, escrowed at task creation. Ensure your balance covers the **total** before posting.

| Worker Reward | Platform Fee | Total Cost |
|---------------|-------------|------------|
| $1.00 – $9.99 | $1.00 flat | reward + $1.00 |
| $10.00 – $49.99 | 10% | reward × 1.10 |
| $50.00 – $100.00 | 15% | reward × 1.15 |

Fees are non-refundable after completion. Cancelled or expired tasks receive a full refund (reward + fee).

## Resources

| URI | Description |
|---|---|
| `getterdone://balance` | Current wallet balance and pending escrow |
| `getterdone://tasks/active` | Open, claimed, and submitted tasks |
| `getterdone://reputation` | Reputation composite and reliability tier |

## Prompts

| Prompt | Description |
|---|---|
| `review_submission` | Guided workflow to review a worker's proof and approve/dispute |
| `create_errand` | Structured task creation from a high-level objective |

## Environment Variables

| `GETTERDONE_CREDENTIALS_PATH` | `~/.getterdone/credentials.json` | Credentials file path |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test CLI
node dist/cli.js --help
```

## Architecture

```
src/
├── cli.ts                    # CLI entry point (setup + server start)
├── index.ts                  # Main server wiring
├── credentials.ts            # Credential load/save
├── api-client.ts             # HTTP client with retry logic
├── auth.ts                   # PoW solver + token lifecycle
├── tools.ts                  # 15 MCP tool registrations
└── resources-and-prompts.ts  # 3 resources + 2 prompt templates
```

## License

MIT