# issuehunt-mcp-server

A Model Context Protocol (MCP) server for the [IssueHunt](https://issuehunt.io) bug bounty platform.
Enables LLMs like Claude to interact with IssueHunt to list organizations, programs, and vulnerability reports, as well as perform triage actions.

## Features

- **Read Tools (Phase 1)**
  - Get authenticated user profile
  - List and inspect organizations
  - View organization statistics and activity logs
  - List and inspect bug bounty and VDP programs
  - List, filter, and read vulnerability reports
  - Read report messages, activities, and internal notes
  - List organization members and your own membership

- **Write Tools (Phase 2)**
  - Update report state (triage, resolve, mark as duplicate, etc.)
  - Update report severity assessment
  - Send messages to researchers
  - Add internal notes to reports

- **MCP Resources**
  - Browse organizations, programs, reports, and stats via `issuehunt://` URIs

## Requirements

- Node.js >= 18
- An IssueHunt API token

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Configure environment variables

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

| Variable | Required | Description |
|---|---|---|
| `ISSUEHUNT_API_TOKEN` | **Yes** | Your IssueHunt Bearer token |
| `ISSUEHUNT_DEFAULT_ORG_ID` | No | Default organization UUID (avoids passing `orgId` to every tool call) |
| `ISSUEHUNT_API_BASE_URL` | No | API base URL (default: `https://api.issuehunt.io`) |

### 4. Run

```bash
npm start
```

## Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "issuehunt": {
      "command": "node",
      "args": ["/absolute/path/to/issuehunt-mcp/dist/index.js"],
      "env": {
        "ISSUEHUNT_API_TOKEN": "your_api_token_here",
        "ISSUEHUNT_DEFAULT_ORG_ID": "your-org-uuid-here"
      }
    }
  }
}
```

Replace `/absolute/path/to/issuehunt-mcp` with the actual path to this project.

## Available Tools

### User

| Tool | Description |
|---|---|
| `get_current_user` | Get the authenticated user profile |

### Organizations

| Tool | Description |
|---|---|
| `list_organizations` | List all organizations you are a member of |
| `get_organization` | Get details + stats for an organization |
| `get_org_stats` | Get statistics for an organization |
| `get_my_membership` | Get your membership and roles in an organization |
| `list_members` | List all members of an organization |
| `list_org_activities` | Get recent activity log for an organization |

### Programs

| Tool | Description |
|---|---|
| `list_programs` | List all programs for an organization |
| `get_program` | Get detailed info about a specific program |
| `list_triage_programs` | List programs in the triage queue |

### Reports

| Tool | Description |
|---|---|
| `list_reports` | List reports with optional state/severity filters |
| `get_report` | Get full report details |
| `get_report_activities` | Get activity timeline for a report |
| `get_report_notes` | Get internal notes for a report |
| `update_report_state` | Change the state of a report |
| `update_report_severity` | Change the severity of a report |
| `add_internal_note` | Add an internal note to a report |

### Messages

| Tool | Description |
|---|---|
| `get_report_messages` | Get all messages in a report thread |
| `post_message` | Send a message to a researcher |

## MCP Resources

Access data via resource URIs:

| URI | Description |
|---|---|
| `issuehunt://organizations` | List your organizations |
| `issuehunt://organizations/{orgId}` | Organization detail + stats |
| `issuehunt://organizations/{orgId}/programs` | Programs list |
| `issuehunt://organizations/{orgId}/reports` | Reports list |
| `issuehunt://organizations/{orgId}/stats` | Organization statistics |
| `issuehunt://reports/{reportId}` | Full report with all messages |

## Report States

| State | Description |
|---|---|
| `new` | Newly submitted, not yet reviewed |
| `checked` | Accepted and under investigation |
| `resolved` | Fix deployed |
| `not_applicable` | Not a valid vulnerability |
| `duplicate` | Already reported |
| `out_of_scope` | Outside the program scope |
| `informational` | No security impact |
| `not_reproducible` | Cannot reproduce the issue |
| `unresolved` | Acknowledged but not yet fixed |

## Report Severities

`informational` | `low` | `medium` | `high` | `critical`

## Development

```bash
# Watch mode
npm run watch

# Run directly without building
npm run dev
```