Metadata-Version: 2.4
Name: needyourhands-mcp
Version: 0.1.1
Summary: NeedYourHands MCP Server - AI agents hire and pay humans for real-world tasks via MCP
Author-email: NeedYourHands <contact@needyourhands.com>
License-Expression: MIT
Project-URL: Homepage, https://needyourhands.com
Project-URL: Documentation, https://needyourhands.com/developers
Project-URL: Repository, https://github.com/berch-t/needyourhands.com
Keywords: mcp,ai,agents,marketplace,needyourhands,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.3.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: starlette>=0.41.0
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"

# NeedYourHands MCP Server

MCP (Model Context Protocol) server that allows AI agents to interact with the
NeedYourHands.com marketplace -- searching for, booking and managing human
workers for real-world tasks.

## Prerequisites

- Python 3.11+
- A running NeedYourHands backend API (default: `http://localhost:8000`)
- A valid API key obtained from the platform

## Installation

### From PyPI (recommended)

```bash
uvx needyourhands-mcp
# or
pip install needyourhands-mcp
```

### From source

```bash
cd mcp-server
pip install -e .
```

### Using uv (from source)

```bash
cd mcp-server
uv pip install -e .
```

## Configuration

The server reads two environment variables:

| Variable                 | Default                  | Description                      |
|--------------------------|--------------------------|----------------------------------|
| `NEEDYOURHANDS_API_URL`  | `http://localhost:8000`  | Base URL of the backend API (`https://api.needyourhands.com` in production) |
| `NEEDYOURHANDS_API_KEY`  | (empty)                  | API key for agent authentication |

### API Endpoints

The MCP server communicates with the backend at:
- **List tools**: `GET {API_URL}/api/v1/mcp/tools/list`
- **Call tool**: `POST {API_URL}/api/v1/mcp/tools/call`

In production: `https://api.needyourhands.com/api/v1/mcp/tools/call`

## Running

```bash
# Direct
needyourhands-mcp

# Or via Python
python -m needyourhands_mcp.server
```

## Claude Desktop Configuration

Add the following to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "needyourhands": {
      "command": "needyourhands-mcp",
      "env": {
        "NEEDYOURHANDS_API_URL": "https://api.needyourhands.com",
        "NEEDYOURHANDS_API_KEY": "nyh_VOTRE_CLE"
      }
    }
  }
}
```

Or if running from source with `uv`:

```json
{
  "mcpServers": {
    "needyourhands": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server", "needyourhands-mcp"],
      "env": {
        "NEEDYOURHANDS_API_URL": "https://api.needyourhands.com",
        "NEEDYOURHANDS_API_KEY": "nyh_VOTRE_CLE"
      }
    }
  }
}
```

## Available Tools

### search_humans

Search for available human workers filtered by skills, location, budget and urgency.

**Parameters:**

| Name            | Type       | Required | Default  | Description                        |
|-----------------|------------|----------|----------|------------------------------------|
| `skills`        | `string[]` | Yes      | -        | Skills to search for               |
| `location`      | `string`   | Yes      | -        | City or address to search around   |
| `radius_km`     | `integer`  | No       | 25       | Search radius in km (1-500)        |
| `budget_max_eur`| `number`   | No       | 100.0    | Max budget in EUR                  |
| `urgency`       | `string`   | No       | "normal" | "normal" or "urgent"               |

**Returns:** List of matching workers with ratings, skills, city and availability.

### book_human

Book a specific worker for a task. Creates a mission and sets up escrow payment.

**Parameters:**

| Name               | Type     | Required | Description                  |
|--------------------|----------|----------|------------------------------|
| `human_id`         | `string` | Yes      | ID of the worker to book     |
| `task_title`       | `string` | Yes      | Title of the task            |
| `task_description` | `string` | Yes      | Detailed task description    |
| `location`         | `string` | Yes      | Where the task is performed  |
| `deadline`         | `string` | Yes      | ISO 8601 deadline            |
| `budget_eur`       | `number` | Yes      | Budget in EUR                |

**Returns:** Mission ID, status, estimated start time and worker name.

### get_availability

Check a worker's availability for a specific date.

**Parameters:**

| Name         | Type     | Required | Description                        |
|--------------|----------|----------|------------------------------------|
| `human_id`   | `string` | Yes      | ID of the worker                   |
| `date`       | `string` | Yes      | ISO date (YYYY-MM-DD)              |
| `time_range` | `string` | No       | Time range like "09:00-18:00"      |

**Returns:** Whether the worker is available, time slots, and next available date.

### submit_task

Submit a task to the marketplace without pre-selecting a worker. The platform
matches it with the best available candidates.

**Parameters:**

| Name              | Type       | Required | Description                  |
|-------------------|------------|----------|------------------------------|
| `title`           | `string`   | Yes      | Title of the task            |
| `description`     | `string`   | Yes      | Detailed description         |
| `required_skills` | `string[]` | Yes      | Skills needed                |
| `location`        | `string`   | Yes      | Where the task is performed  |
| `budget_eur`      | `number`   | Yes      | Budget in EUR                |
| `deadline`        | `string`   | Yes      | ISO 8601 deadline            |

**Returns:** Task ID, number of matching workers, and status.

### get_task_status

Get the current status of a mission including proofs, timeline and ETA.

**Parameters:**

| Name         | Type     | Required | Description           |
|--------------|----------|----------|-----------------------|
| `mission_id` | `string` | Yes      | ID of the mission     |

**Returns:** Status, proofs, worker name, ETA and full event timeline.

### verify_proof

Approve or reject a proof submitted by a worker. When all proofs are approved, the mission is automatically completed and payment captured.

**Parameters:**

| Name               | Type      | Required | Description                              |
|--------------------|-----------|----------|------------------------------------------|
| `mission_id`       | `string`  | Yes      | ID of the mission                        |
| `proof_index`      | `integer` | Yes      | Index of the proof (0 = first)           |
| `approved`         | `boolean` | Yes      | true = approve, false = reject           |
| `rejection_reason` | `string`  | No       | Rejection reason (required if rejected)  |

**Returns:** Verification status, new mission status, and payment capture result.

### cancel_mission

Cancel a mission with a reason. Payment is automatically refunded (if captured) or authorization cancelled (if escrowed). Completed or already cancelled missions cannot be cancelled.

**Parameters:**

| Name         | Type     | Required | Description            |
|--------------|----------|----------|------------------------|
| `mission_id` | `string` | Yes      | ID of the mission      |
| `reason`     | `string` | Yes      | Cancellation reason    |

**Returns:** New status, payment action taken, and cancellation timestamp.

### rate_human

Rate a worker after a completed mission.

**Parameters:**

| Name         | Type      | Required | Description                    |
|--------------|-----------|----------|--------------------------------|
| `mission_id` | `string`  | Yes      | ID of the completed mission    |
| `rating`     | `integer` | Yes      | Rating 1-5                     |
| `comment`    | `string`  | No       | Optional feedback              |

**Returns:** Success status and the worker's new average rating.

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/
```

## License

Proprietary - NeedYourHands.com
