hackerone-mcp-server 1.0.0 → 1.1.0

package/README.md

@@ -1,42 +1,37 @@
 # HackerOne MCP Server
 
-> **Disclaimer:** This is an unofficial, community-built project. It is not affiliated with, endorsed by, or maintained by HackerOne. "HackerOne" is a trademark of HackerOne, Inc. This project integrates with their publicly documented [Hacker API](https://api.hackerone.com/hacker-resources/) and uses the website's public GraphQL API for program signal requirements.
-
-MCP server that gives Claude Code (or any MCP client) full access to your HackerOne reports, programs, earnings, and scope data via the HackerOne API — including submitting reports and responding to triage.
+Unofficial MCP server that gives Codex, Claude Code, or any MCP client full access to your HackerOne reports, programs, earnings, and scope data via the HackerOne API — including submitting reports and responding to triage.
 
 ## Setup
 
+Install Node.js and npm, then use the published [hackerone-mcp-server package](https://www.npmjs.com/package/hackerone-mcp-server) through `npx`.
+
 ### 1. Get your HackerOne API token
 
 Go to **HackerOne > Settings > API Token** and generate one.
 
-### 2. Install and build
+### 2. Add to your MCP client
 
-```bash
-git clone https://github.com/Sicks3c/hackerone-mcp-server.git
-cd hackerone-mcp-server
-npm install
-npm run build
-```
+Replace `your-username` and `your-api-token` below with your HackerOne credentials.
 
-### 3. Add to Claude Code
+#### Codex
 
-```bash
-claude mcp add hackerone \
-  -e H1_USERNAME=your-username \
-  -e H1_API_TOKEN=your-api-token \
-  -s user \
-  -- node /path/to/hackerone-mcp-server/dist/index.js
+```toml
+[mcp_servers.hackerone]
+command = "npx"
+args = ["-y", "hackerone-mcp-server@latest"]
+startup_timeout_sec = 60
+env = { "H1_USERNAME" = "your-username", "H1_API_TOKEN" = "your-api-token" }
 ```
 
-Or add manually to `~/.claude.json`:
+#### Claude Code
 
 ```json
 {
   "mcpServers": {
     "hackerone": {
-      "command": "node",
-      "args": ["/path/to/hackerone-mcp-server/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "hackerone-mcp-server@latest"],
       "env": {
         "H1_USERNAME": "your-username",
         "H1_API_TOKEN": "your-api-token"
@@ -46,14 +41,21 @@ Or add manually to `~/.claude.json`:
 }
 ```
 
-### 4. Verify
+## Build from source
+
+For local development:
 
 ```bash
-claude
-> /mcp
-# You should see "hackerone" listed with 17 tools
+git clone https://github.com/11philip22/hackerone-mcp-server.git
+cd hackerone-mcp-server
+npm install
+npm run build
 ```
 
+Run `npm test` to build and run the fixture tests. Tests use Node's experimental module mocking and require Node.js 22.3+ (or 20.18+ on the Node 20 release line).
+
+To use your local build, set the MCP command to `node` and its arguments to `["/absolute/path/to/hackerone-mcp-server/dist/index.js"]`, keeping the same environment variables.
+
 ## Tools
 
 ### Read
@@ -67,6 +69,7 @@ claude
 | `list_programs` | List all bug bounty programs you have access to (auto-paginates) |
 | `get_program_details` | Get single program info: policy, response times, metrics |
 | `get_program_signal_requirements` | Get a public program's minimum past-year signal threshold and whether requirements are enabled |
+| `get_program_rewards` | Get a public program's currency, severity payout ranges, reward groups, and each group's scope assets |
 | `get_program_scope` | Get all in-scope assets for a program (auto-paginates) |
 | `get_program_weaknesses` | Get accepted CWE/weakness types for a program (auto-paginates) |
 | `get_earnings` | Get your bounty earnings history (amounts, dates, programs) |
@@ -125,6 +128,11 @@ Show my hacker profile — what's my current reputation and signal?
 What signal do I need to submit reports to the uber program?
 ```
 
+**Compare rewards by asset group:**
+```
+Show TikTok's reward groups, severity payout ranges, and which Android apps and websites belong to each group. Flag any unavailable data.
+```
+
 **Track earnings:**
 ```
 Show my recent bounty earnings and current balance
@@ -134,17 +142,3 @@ Show my recent bounty earnings and current balance
 ```
 Analyze my report patterns — what severity gets resolved most?
 ```
-
-## How It Works
-
-- Connects to the [HackerOne Hacker API v1](https://api.hackerone.com/hacker-resources/) using your personal API token
-- Runs locally over stdio — your credentials never leave your machine
-- Supports both read and write operations (submit reports, add comments, close reports)
-- Auto-paginates programs, scope, and weakness endpoints so nothing gets silently truncated
-- Uses server-side API filters where available (program, severity, state) for faster searches
-- Built-in retry with exponential backoff for rate limit handling
-- 60-second response cache to reduce redundant API calls
-
-## License
-
-MIT

package/dist/h1client.d.ts

@@ -81,6 +81,45 @@ export declare function getProgramDetails(handle: string): Promise<{
     bookmarked: any;
 }>;
 export declare function getProgramSignalRequirements(handle: string): Promise<any>;
+type RewardAvailability = "available" | "partial" | "unavailable";
+type RewardSeverity = "low" | "medium" | "high" | "critical";
+interface RewardAsset {
+    id: string;
+    asset_identifier: string;
+    asset_type: string | null;
+    eligible_for_submission: boolean | null;
+    eligible_for_bounty: boolean | null;
+}
+interface RewardGroup {
+    id: string;
+    name: string | null;
+    description: string | null;
+    scope_kind: "all_assets" | "asset" | "reward_group" | null;
+    use_range: boolean | null;
+    rewards: Record<RewardSeverity, {
+        label: string | null;
+        minimum: number | null;
+        maximum: number | null;
+    }>;
+    assets: RewardAsset[] | null;
+    assets_availability: RewardAvailability;
+}
+export interface ProgramRewards {
+    handle: string;
+    currency: string | null;
+    source: string;
+    program_url: string;
+    format: "legacy" | "scope_and_rewards" | null;
+    description: string | null;
+    availability: RewardAvailability;
+    issues: {
+        code: string;
+        group_id: string | null;
+        message: string;
+    }[];
+    groups: RewardGroup[] | null;
+}
+export declare function getProgramRewards(handle: string): Promise<ProgramRewards>;
 export declare function getProgramScope(handle: string, pageSize?: number): Promise<{
     id: any;
     asset_type: any;
@@ -177,3 +216,4 @@ export declare function searchDisclosedReports(opts: {
     query?: string;
     page_size?: number;
 }): Promise<any>;
+export {};

package/dist/h1client.js

@@ -482,6 +482,265 @@ export async function getProgramSignalRequirements(handle) {
     cacheSet(cacheKey, result);
     return result;
 }
+// ── Get public program rewards ───────────────────────────────────
+export async function getProgramRewards(handle) {
+    handle = handle.trim();
+    if (!handle)
+        throw new Error("program_handle must not be empty");
+    const cacheKey = `program-rewards:${handle}`;
+    const cached = cacheGet(cacheKey);
+    if (cached)
+        return cached;
+    // shortcut: uses the public website API; switch when the Hacker API exposes reward groups.
+    const result = {
+        handle, currency: null, source: "https://hackerone.com/graphql",
+        program_url: `https://hackerone.com/${encodeURIComponent(handle)}`,
+        format: null, description: null, availability: "unavailable", issues: [], groups: null,
+    };
+    const issue = (code, message, group_id = null) => {
+        result.issues.push({ code, group_id, message });
+    };
+    const request = async (query, variables = {}) => {
+        const res = await fetch(result.source, {
+            method: "POST", redirect: "error", signal: AbortSignal.timeout(15_000),
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify({ query, variables: { handle, ...variables } }),
+        });
+        if (!res.ok)
+            throw new Error(`HackerOne GraphQL HTTP error ${res.status}`);
+        const body = await res.json();
+        if (body?.errors !== undefined && (!Array.isArray(body.errors) || body.errors.length)) {
+            if (body.data?.team === null && Array.isArray(body.errors) &&
+                body.errors.length && body.errors.every((e) => e?.type === "NOT_FOUND"))
+                return null;
+            throw new Error("HackerOne GraphQL returned errors");
+        }
+        const team = body?.data?.team;
+        if (team !== null && !isObject(team))
+            throw new Error("Malformed HackerOne team response");
+        return team;
+    };
+    const scopeFields = `_id asset_identifier asset_type eligible_for_submission eligible_for_bounty`;
+    const rewardsQuery = `query ProgramRewards($handle: String!, $after: String) {
+    team(handle: $handle) {
+      handle currency scope_and_rewards_groups_enabled
+      bounty_table {
+        _id description low_label medium_label high_label critical_label
+        bounty_table_rows(first: 100, after: $after) {
+          pageInfo { hasNextPage endCursor }
+          edges { node {
+            _id name description use_range
+            low low_minimum medium medium_minimum high high_minimum critical critical_minimum
+            structured_scope { ${scopeFields} }
+          } }
+        }
+      }
+    }
+  }`;
+    const rows = new Map();
+    const groups = [];
+    const nextCursor = (connection, seen) => {
+        const info = connection?.pageInfo;
+        if (!isObject(info) || typeof info.hasNextPage !== "boolean") {
+            throw new Error("Missing reward pagination metadata");
+        }
+        if (!connection.edges.length && seen.size)
+            throw new Error("Prematurely empty reward page");
+        if (!info.hasNextPage)
+            return null;
+        if (!connection.edges.length || typeof info.endCursor !== "string" ||
+            !info.endCursor || seen.has(info.endCursor)) {
+            throw new Error("Incomplete or repeated reward pagination cursor");
+        }
+        seen.add(info.endCursor);
+        return info.endCursor;
+    };
+    const nodes = (connection) => {
+        if (!isObject(connection) || !Array.isArray(connection.edges) ||
+            connection.edges.some((e) => !isObject(e?.node))) {
+            throw new Error("Malformed reward connection");
+        }
+        return connection.edges.map((e) => e.node);
+    };
+    const asset = (raw) => {
+        if (!isObject(raw) || typeof raw._id !== "string" || !raw._id ||
+            typeof raw.asset_identifier !== "string" || !raw.asset_identifier) {
+            throw new Error("Malformed reward scope asset");
+        }
+        return {
+            id: raw._id, asset_identifier: raw.asset_identifier,
+            asset_type: typeof raw.asset_type === "string" ? raw.asset_type : null,
+            eligible_for_submission: typeof raw.eligible_for_submission === "boolean" ? raw.eligible_for_submission : null,
+            eligible_for_bounty: typeof raw.eligible_for_bounty === "boolean" ? raw.eligible_for_bounty : null,
+        };
+    };
+    try {
+        let team = await request(rewardsQuery);
+        if (team === null) {
+            issue("not_public_or_not_found", "Program was not found or is not publicly accessible");
+            return result;
+        }
+        if (typeof team.handle !== "string" || typeof team.scope_and_rewards_groups_enabled !== "boolean") {
+            throw new Error("Malformed program rewards metadata");
+        }
+        result.handle = team.handle;
+        result.format = team.scope_and_rewards_groups_enabled ? "scope_and_rewards" : "legacy";
+        const sourceCurrency = team.currency;
+        result.currency = typeof team.currency === "string" && team.currency.trim() ? team.currency : null;
+        if (result.currency === null)
+            issue("missing_currency", "Reward currency is unknown");
+        if (team.bounty_table === null) {
+            result.groups = [];
+            issue("no_published_table", "No public bounty table is available");
+            return result;
+        }
+        const tableId = team.bounty_table?._id;
+        if (typeof tableId !== "string" || !tableId)
+            throw new Error("Malformed bounty table");
+        result.description = typeof team.bounty_table.description === "string" ? team.bounty_table.description : null;
+        const cursors = new Set();
+        while (true) {
+            const table = team?.bounty_table;
+            if (table?._id !== tableId || team.handle !== result.handle ||
+                team.scope_and_rewards_groups_enabled !== (result.format === "scope_and_rewards") ||
+                team.currency !== sourceCurrency) {
+                throw new Error("Program rewards changed during pagination");
+            }
+            for (const row of nodes(table.bounty_table_rows)) {
+                if (typeof row._id !== "string" || !row._id || rows.has(row._id)) {
+                    throw new Error("Missing or repeated reward group ID");
+                }
+                const useRange = typeof row.use_range === "boolean" ? row.use_range : null;
+                const rewards = {};
+                let incomplete = useRange === null;
+                for (const severity of ["low", "medium", "high", "critical"]) {
+                    const amount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+                    let maximum = amount(row[severity]);
+                    let minimum = useRange === false ? maximum : amount(row[`${severity}_minimum`]);
+                    if (minimum !== null && maximum !== null && minimum > maximum) {
+                        minimum = maximum = null;
+                    }
+                    incomplete ||= minimum === null || maximum === null;
+                    rewards[severity] = {
+                        label: typeof table[`${severity}_label`] === "string" ? table[`${severity}_label`] : null,
+                        minimum, maximum,
+                    };
+                }
+                if (incomplete)
+                    issue("incomplete_rewards", "Some payout amounts, bounds, or the range setting are unknown or invalid", row._id);
+                groups.push({
+                    id: row._id, name: typeof row.name === "string" ? row.name : null,
+                    description: typeof row.description === "string" ? row.description : null,
+                    scope_kind: result.format === "scope_and_rewards" ? "reward_group" :
+                        row.structured_scope === null ? "all_assets" : isObject(row.structured_scope) ? "asset" : null,
+                    use_range: useRange, rewards, assets: null, assets_availability: "unavailable",
+                });
+                rows.set(row._id, row);
+            }
+            const after = nextCursor(table.bounty_table_rows, cursors);
+            if (after === null)
+                break;
+            team = await request(rewardsQuery, { after });
+        }
+        if (!groups.length) {
+            result.groups = [];
+            issue("no_published_rewards", "The public bounty table contains no reward rows");
+            return result;
+        }
+    }
+    catch (err) {
+        issue("upstream_error", `Could not retrieve every reward group: ${err.message}`);
+        if (!groups.length)
+            return result;
+    }
+    result.groups = groups;
+    let allAssets;
+    for (const group of groups) {
+        try {
+            const assets = [];
+            const seenIds = new Set();
+            const append = (rawAssets) => {
+                for (const raw of rawAssets) {
+                    const item = asset(raw);
+                    if (seenIds.has(item.id))
+                        throw new Error("Repeated scope asset during pagination");
+                    seenIds.add(item.id);
+                    assets.push(item);
+                }
+            };
+            if (group.scope_kind === "reward_group") {
+                const rowId = Number(group.id);
+                if (!/^\d+$/.test(group.id) || !Number.isSafeInteger(rowId) || rowId < 1 || rowId > 2147483647) {
+                    throw new Error("Invalid reward group ID for scope search");
+                }
+                let total;
+                while (true) {
+                    const team = await request(`query ProgramRewardAssets($handle: String!, $rowId: Int!, $from: Int!) {
+            team(handle: $handle) {
+              structured_scopes_search(bounty_table_row_id: $rowId, from: $from, size: 100,
+                sort: {field: "id", direction: ASC}) {
+                total_count edges { node { ... on StructuredScopeDocument {
+                  _id asset_identifier: identifier asset_type eligible_for_submission eligible_for_bounty
+                } } }
+              }
+            }
+          }`, { rowId, from: assets.length });
+                    const page = team?.structured_scopes_search;
+                    const batch = nodes(page);
+                    if (!Number.isSafeInteger(page.total_count) || page.total_count < 0 ||
+                        (total !== undefined && total !== page.total_count)) {
+                        throw new Error("Missing or inconsistent reward asset total");
+                    }
+                    total = page.total_count;
+                    append(batch);
+                    if (assets.length === total)
+                        break;
+                    if (!batch.length || assets.length > total)
+                        throw new Error("Incomplete reward asset search");
+                }
+                group.assets = assets;
+            }
+            else if (group.scope_kind === "asset") {
+                group.assets = [asset(rows.get(group.id).structured_scope)];
+            }
+            else if (group.scope_kind === "all_assets") {
+                if (!allAssets) {
+                    let after = null;
+                    const cursors = new Set();
+                    do {
+                        const team = await request(`query ProgramRewardDefaultAssets($handle: String!, $after: String) {
+              team(handle: $handle) {
+                structured_scopes(first: 100, after: $after, archived: false,
+                  eligible_for_submission: true, eligible_for_bounty: true) {
+                  pageInfo { hasNextPage endCursor }
+                  edges { node { ${scopeFields} } }
+                }
+              }
+            }`, { after });
+                        const page = team?.structured_scopes;
+                        append(nodes(page));
+                        after = nextCursor(page, cursors);
+                    } while (after !== null);
+                    allAssets = assets;
+                }
+                group.assets = allAssets;
+            }
+            else {
+                throw new Error("Legacy reward scope applicability is unknown");
+            }
+            group.assets_availability = group.assets.some((a) => a.asset_type === null || a.eligible_for_bounty === null || a.eligible_for_submission === null) ? "partial" : "available";
+            if (group.assets_availability === "partial")
+                issue("incomplete_asset_fields", "Some asset types or eligibility fields are unknown", group.id);
+        }
+        catch (err) {
+            issue("assets_unavailable", `Could not retrieve every asset: ${err.message}`, group.id);
+        }
+    }
+    result.availability = result.issues.length ? "partial" : "available";
+    if (result.availability === "available")
+        cacheSet(cacheKey, result);
+    return result;
+}
 // ── Get program scope (auto-paginated) ────────────────────────────
 export async function getProgramScope(handle, pageSize) {
     const allData = await h1FetchAllPages(`/hackers/programs/${handle}/structured_scopes`, pageSize);

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { searchReports, getReport, getReportActivities, getReportSummary, listPrograms, getProgramDetails, getProgramSignalRequirements, getProgramScope, getProgramWeaknesses, getEarnings, getHackerProfile, getBalance, submitReport, addComment, closeReport, searchDisclosedReports, } from "./h1client.js";
+import { searchReports, getReport, getReportActivities, getReportSummary, listPrograms, getProgramDetails, getProgramSignalRequirements, getProgramRewards, getProgramScope, getProgramWeaknesses, getEarnings, getHackerProfile, getBalance, submitReport, addComment, closeReport, searchDisclosedReports, } from "./h1client.js";
 const server = new McpServer({
     name: "hackerone",
     version: "2.0.0",
@@ -204,7 +204,26 @@ server.tool("get_program_signal_requirements", "Get a public program's minimum p
         };
     }
 });
-// ── Tool: analyze_report_patterns ──────────────────────────────────
+// ── Tool: get_program_rewards ─────────────────────────────────────
+server.tool("get_program_rewards", "Get a public program's published reward groups, currency, Low/Medium/High/Critical payout ranges, and associated scope assets. Supports legacy tables and Scope and rewards groups. Missing values are null, not zero; inspect availability and issues before relying on incomplete data. Legacy asset-specific rows take precedence over all-assets rows for the same asset ID. Private programs are not supported.", {
+    program_handle: z.string().trim().min(1).describe("Public program handle (e.g. 'security', 'tiktok')"),
+}, { readOnlyHint: true }, async ({ program_handle }) => {
+    try {
+        const rewards = await getProgramRewards(program_handle);
+        return {
+            content: [{ type: "text", text: JSON.stringify(rewards, null, 2) }],
+            isError: rewards.availability === "unavailable" &&
+                rewards.issues.some((issue) => issue.code === "upstream_error"),
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+// ── Tool: analyze_report_patterns ────────────────────────────────
 server.tool("analyze_report_patterns", "Fetch your recent reports and analyze patterns: most common vulnerability types, severity distribution, resolution rates, and programs. Useful for understanding your hunting profile.", {
     page_size: z
         .number()

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "hackerone-mcp-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for accessing HackerOne reports in Claude Code",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/11philip22/hackerone-mcp-server.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +17,7 @@
   "scripts": {
     "build": "tsc",
     "prepack": "npm run build",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && node --experimental-test-module-mocks --test test/*.test.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },