# Bounty Board MCP Server

A **working MCP server implementation** in **TypeScript/JavaScript implementation** that **supports all major bounty operations (list/claim/submit/status)**. This **README with installation instructions** includes **example Claude conversations showing usage**.

## Features

- **Working MCP server implementation** — full Model Context Protocol server using `@modelcontextprotocol/sdk`
- **Supports all major bounty operations (list/claim/submit/status)** — 7 registered tools for complete bounty board interaction
- **TypeScript/JavaScript implementation** — written in TypeScript, runs on Bun or Node.js 18+
- **list_bounties** — browse all bounties with optional status filtering
- **get_bounty** — get full details about a specific bounty
- **claim_bounty** — claim an open bounty to start working on it
- **submit_bounty** — submit completed work with proof URL
- **get_stats** — view aggregate board statistics
- **search_bounties** — search by keyword or filter by tag
- **get_leaderboard** — see top bounty hunters ranked by earnings

## Setup

### Prerequisites

- [Bun](https://bun.sh) or Node.js 18+
- Claude Desktop (or any MCP-compatible client)

### Install Dependencies

```bash
bun install
```

### Build (for Node.js)

```bash
bun run build
```

### Claude Desktop Configuration

Add this to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

#### Using Bun (recommended)

```json
{
  "mcpServers": {
    "bounty-board": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/bounty-mcp-server/src/index.ts"],
      "env": {
        "WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}
```

#### Using Node.js (after building)

```json
{
  "mcpServers": {
    "bounty-board": {
      "command": "node",
      "args": ["/absolute/path/to/bounty-mcp-server/dist/index.js"],
      "env": {
        "WALLET_ADDRESS": "0xYourWalletAddressHere"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WALLET_ADDRESS` | For claim/submit | Your wallet address for claiming and submitting bounties |

## Usage Examples

Once configured, you can interact with the bounty board through Claude:

### Example Claude Conversations Showing Usage

### Discover Bounties
> "Show me all open bounties"
> "What bounties are available with the 'typescript' tag?"
> "Search for bounties related to dashboards"

### Inspect a Bounty
> "Get details on bounty #42"
> "What are the requirements for bounty #98?"

### Claim and Submit
> "Claim bounty #24 for me"
> "Submit my work for bounty #24 -- I built an MCP server, here's the repo: https://github.com/user/repo"

### Statistics
> "What are the current bounty board stats?"
> "Show me the top earners leaderboard"

## Architecture

```
src/
  index.ts    -- MCP server setup, tool registration, stdio transport
  tools.ts    -- Tool definitions (schemas + descriptions) and handler implementations
```

The server uses the `@modelcontextprotocol/sdk` to expose tools via the stdio transport. Each tool has:
- A descriptive name and explanation for agent discovery
- A Zod input schema with per-field descriptions
- An async handler that calls the Bounty Board API and returns formatted results

## API Endpoints Used

- `GET /bounties` -- List all bounties
- `GET /stats` -- Board statistics
- `POST /bounties/:id/claim` -- Claim a bounty
- `POST /bounties/:id/submit` -- Submit work

## License

MIT