@bbradar/mcp 0.1.3

package/README.md

@@ -0,0 +1,156 @@
+# @bbradar/mcp
+
+Local STDIO MCP server for [bbradar.io](https://bbradar.io) Pro subscribers. It lets MCP clients query [bbradar.io](https://bbradar.io) Pro program, target, opportunity, and recent-change data through a local npm package.
+
+## Requirements
+
+- Node.js 20 or newer.
+- A [bbradar.io](https://bbradar.io) Pro API key.
+- An MCP client that supports local STDIO servers.
+
+## Install
+
+Most MCP clients can run the package directly with `npx`:
+
+```bash
+npx -y @bbradar/mcp
+```
+
+For a global install:
+
+```bash
+npm install -g @bbradar/mcp
+bbradar-mcp
+```
+
+For a project-local install:
+
+```bash
+npm install @bbradar/mcp
+npx bbradar-mcp
+```
+
+The server needs your [bbradar.io](https://bbradar.io) Pro key. In the MCP client config, add it as `BBRADAR_API_KEY`.
+
+## Client Configuration
+
+### OpenCode
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "bbradar.io": {
+      "type": "local",
+      "command": ["npx", "-y", "@bbradar/mcp"],
+      "enabled": true,
+      "timeout": 30000,
+      "environment": {
+        "BBRADAR_API_KEY": "your_pro_mcp_api_key"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add with the Codex CLI:
+
+```bash
+codex mcp add bbradar.io --env BBRADAR_API_KEY="your_pro_mcp_api_key" -- npx -y @bbradar/mcp
+```
+
+Or add it to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers."bbradar.io"]
+command = "npx"
+args = ["-y", "@bbradar/mcp"]
+
+[mcp_servers."bbradar.io".env]
+BBRADAR_API_KEY = "your_pro_mcp_api_key"
+```
+
+### Claude Code
+
+Add a private user-level server:
+
+```bash
+claude mcp add bbradar.io --scope user --env BBRADAR_API_KEY="your_pro_mcp_api_key" -- npx -y @bbradar/mcp
+```
+
+On native Windows, wrap `npx` with `cmd /c`:
+
+```bash
+claude mcp add bbradar.io --scope user --env BBRADAR_API_KEY="your_pro_mcp_api_key" -- cmd /c npx -y @bbradar/mcp
+```
+
+### Generic MCP JSON
+
+```json
+{
+  "mcpServers": {
+    "bbradar.io": {
+      "command": "npx",
+      "args": ["-y", "@bbradar/mcp"],
+      "env": {
+        "BBRADAR_API_KEY": "your_pro_mcp_api_key"
+      }
+    }
+  }
+}
+```
+
+## Verify
+
+After adding the MCP config, restart your client and call `get_mcp_status`. A working setup returns server status, timing, and rate-limit metadata.
+
+## Tools
+
+- `search_programs`
+- `get_program`
+- `resolve_program`
+- `run_program_name_action`
+- `get_program_targets`
+- `get_recent_changes`
+- `get_opportunities`
+- `find_programs`
+- `find_wildcard_programs`
+- `find_web3_programs`
+- `find_reward_programs`
+- `find_web3_contests`
+- `find_language_programs`
+- `find_target_type_programs`
+- `find_vdp_programs`
+- `find_paid_programs`
+- `find_stack_matches`
+- `find_low_noise_programs`
+- `find_recent_by_type`
+- `find_programs_by_target`
+- `find_program_candidates`
+- `find_hunt_candidates`
+- `find_fresh_hunt_candidates`
+- `list_filters`
+- `get_mcp_status`
+- `compare_programs`
+- `compare_programs_compact`
+- `summarize_program_activity`
+- `get_program_brief`
+- `find_recently_added_wildcards`
+- `find_low_competition_high_reward`
+- `get_program_delta`
+- `get_latest_added_targets`
+- `get_program_scope_summary`
+- `get_program_target_breakdown`
+- `get_program_scope_delta`
+- `get_recent_target_activity`
+- `check_program_new_targets`
+- `check_watchlist_new_targets`
+- `export_targets`
+
+## Prompts
+
+- `find_best_programs_to_hunt`
+- `summarize_program_scope`
+- `prepare_recon_plan`

package/dist/bbradarClient.d.ts

@@ -0,0 +1,61 @@
+import { type CacheStats } from "./cache.js";
+import type { ServerConfig } from "./config.js";
+export type QueryValue = string | number | boolean | null | undefined | readonly string[] | readonly number[] | readonly boolean[];
+export type ApiRequestOptions = {
+    method?: "GET" | "POST";
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    cache?: boolean;
+    coalesce?: boolean;
+};
+export type ApiResult<T> = {
+    data: T;
+    requestId: string;
+    upstreamRequestId?: string | undefined;
+    cached: boolean;
+    coalesced?: boolean | undefined;
+    status: number;
+    fetchedAt: string;
+    cacheExpiresAt?: string | undefined;
+};
+export declare class BBRadarApiError extends Error {
+    readonly requestId: string;
+    readonly upstreamRequestId: string | undefined;
+    readonly status: number | undefined;
+    readonly detail?: unknown;
+    readonly errors?: unknown;
+    constructor(params: {
+        message: string;
+        requestId: string;
+        upstreamRequestId?: string | undefined;
+        status?: number | undefined;
+        detail?: unknown;
+        errors?: unknown;
+        cause?: unknown;
+    });
+}
+export declare class BBRadarClient {
+    private readonly config;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(config: ServerConfig);
+    diagnostics(): {
+        response_cache: CacheStats & {
+            enabled: boolean;
+        };
+        in_flight_requests: number;
+    };
+    validateKey(): Promise<void>;
+    listPrograms(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getProgram(programId: string): Promise<ApiResult<unknown>>;
+    getProgramTargets(programId: string): Promise<ApiResult<unknown>>;
+    getRecentChanges(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    searchTargets(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getOpportunities(level: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    exportTargets(body: Record<string, unknown>): Promise<ApiResult<unknown>>;
+    request<T = unknown>(options: ApiRequestOptions): Promise<ApiResult<T>>;
+    private fetchFromApi;
+    private buildUrl;
+    private headers;
+}

package/dist/bbradarClient.js

@@ -0,0 +1,307 @@
+import { randomUUID } from "node:crypto";
+import { TtlCache } from "./cache.js";
+import { stableStringify } from "./json.js";
+import { encodeProgramIdPath } from "./url.js";
+export class BBRadarApiError extends Error {
+    requestId;
+    upstreamRequestId;
+    status;
+    detail;
+    errors;
+    constructor(params) {
+        super(params.message, { cause: params.cause });
+        this.name = "BBRadarApiError";
+        this.requestId = params.requestId;
+        this.upstreamRequestId = params.upstreamRequestId;
+        this.status = params.status;
+        this.detail = params.detail;
+        this.errors = params.errors;
+    }
+}
+export class BBRadarClient {
+    config;
+    cache;
+    inFlight = new Map();
+    constructor(config) {
+        this.config = config;
+        this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs);
+    }
+    diagnostics() {
+        return {
+            response_cache: {
+                enabled: this.config.cacheTtlMs > 0 && this.config.cacheMaxEntries > 0,
+                ...this.cache.stats()
+            },
+            in_flight_requests: this.inFlight.size
+        };
+    }
+    async validateKey() {
+        try {
+            await this.request({
+                path: "/pro/programs",
+                query: { page: 1, page_size: 1 },
+                cache: false,
+                coalesce: false
+            });
+        }
+        catch (error) {
+            if (!(error instanceof BBRadarApiError)) {
+                throw error;
+            }
+            if (error.status === 401) {
+                throw new Error("BBRADAR_API_KEY was rejected by the BBRadar Pro API.");
+            }
+            if (error.status === 402) {
+                throw new Error("The BBRadar API key does not have an active Pro subscription entitlement.");
+            }
+            if (error.status === 403) {
+                throw new Error("The BBRadar API key is not allowed to use MCP or lacks the required read-only scope.");
+            }
+            if (error.status === 423) {
+                throw new Error("The BBRadar Pro account or API key is locked.");
+            }
+            throw error;
+        }
+    }
+    listPrograms(query) {
+        return this.request({
+            path: "/pro/programs",
+            query
+        });
+    }
+    getProgram(programId) {
+        return this.request({
+            path: `/pro/programs/${encodeProgramIdPath(programId)}`
+        });
+    }
+    getProgramTargets(programId) {
+        return this.request({
+            path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`
+        });
+    }
+    getRecentChanges(query) {
+        return this.request({
+            path: "/pro/targets/changes",
+            query
+        });
+    }
+    searchTargets(query) {
+        return this.request({
+            path: "/pro/targets/search",
+            query
+        });
+    }
+    getOpportunities(level, query) {
+        return this.request({
+            path: `/pro/opportunities/${encodeURIComponent(level)}`,
+            query
+        });
+    }
+    exportTargets(body) {
+        return this.request({
+            method: "POST",
+            path: "/pro/targets/export",
+            body,
+            cache: false,
+            coalesce: false
+        });
+    }
+    async request(options) {
+        const method = options.method ?? "GET";
+        const requestId = randomUUID();
+        const url = this.buildUrl(options.path, options.query);
+        const requestKey = stableStringify({
+            method,
+            url: url.toString(),
+            body: options.body ?? null
+        });
+        const cacheable = method === "GET" && (options.cache ?? true) && this.config.cacheTtlMs > 0 && this.config.cacheMaxEntries > 0;
+        const coalesceable = method === "GET" && (options.coalesce ?? true);
+        if (cacheable) {
+            const cached = this.cache.get(requestKey);
+            if (cached) {
+                return {
+                    ...cached.value,
+                    requestId,
+                    cached: true,
+                    cacheExpiresAt: new Date(cached.expiresAt).toISOString()
+                };
+            }
+        }
+        if (coalesceable) {
+            const pending = this.inFlight.get(requestKey);
+            if (pending) {
+                try {
+                    const result = (await pending);
+                    return {
+                        ...result,
+                        requestId,
+                        cached: false,
+                        coalesced: true
+                    };
+                }
+                catch (error) {
+                    throw cloneApiError(error, requestId);
+                }
+            }
+        }
+        const request = this.fetchFromApi(options, method, url, requestId);
+        if (coalesceable) {
+            this.inFlight.set(requestKey, request);
+        }
+        try {
+            const result = await request;
+            if (cacheable) {
+                this.cache.set(requestKey, result);
+            }
+            return {
+                ...result,
+                requestId,
+                cached: false
+            };
+        }
+        finally {
+            if (coalesceable) {
+                this.inFlight.delete(requestKey);
+            }
+        }
+    }
+    async fetchFromApi(options, method, url, requestId) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        try {
+            const init = {
+                method,
+                headers: this.headers(options.body),
+                cache: "no-store",
+                signal: controller.signal
+            };
+            if (options.body !== undefined) {
+                init.body = JSON.stringify(options.body);
+            }
+            const response = await fetch(url, init);
+            const upstreamRequestId = extractRequestId(response.headers);
+            const data = await parseResponseBody(response);
+            if (!response.ok) {
+                const params = {
+                    message: formatApiErrorMessage(response.status, data),
+                    requestId,
+                    status: response.status,
+                    detail: extractObjectField(data, "detail"),
+                    errors: extractObjectField(data, "errors")
+                };
+                if (upstreamRequestId) {
+                    params.upstreamRequestId = upstreamRequestId;
+                }
+                throw new BBRadarApiError(params);
+            }
+            const result = {
+                data: data,
+                status: response.status,
+                fetchedAt: new Date().toISOString()
+            };
+            if (upstreamRequestId) {
+                result.upstreamRequestId = upstreamRequestId;
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof BBRadarApiError) {
+                throw error;
+            }
+            throw new BBRadarApiError({
+                message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
+                requestId,
+                cause: error
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    buildUrl(path, query) {
+        const url = new URL(`${this.config.apiBaseUrl}${path}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                if (value.length > 0) {
+                    url.searchParams.set(key, value.join(","));
+                }
+                continue;
+            }
+            url.searchParams.set(key, String(value));
+        }
+        return url;
+    }
+    headers(body) {
+        const headers = {
+            authorization: `Bearer ${this.config.apiKey}`,
+            accept: "application/json",
+            "cache-control": "no-cache, no-store, max-age=0",
+            pragma: "no-cache",
+            "user-agent": "@bbradar/mcp"
+        };
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+        }
+        return headers;
+    }
+}
+async function parseResponseBody(response) {
+    if (response.status === 204) {
+        return null;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const text = await response.text();
+    if (text.length === 0) {
+        return null;
+    }
+    if (contentType.includes("application/json") || contentType.includes("+json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+function extractRequestId(headers) {
+    return (headers.get("x-request-id") ??
+        headers.get("x-correlation-id") ??
+        headers.get("request-id") ??
+        undefined);
+}
+function extractObjectField(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return value[field];
+}
+function formatApiErrorMessage(status, data) {
+    const detail = extractObjectField(data, "detail");
+    const message = extractObjectField(data, "message");
+    const suffix = typeof detail === "string"
+        ? detail
+        : typeof message === "string"
+            ? message
+            : "Request was rejected.";
+    return `BBRadar API returned ${status}: ${suffix}`;
+}
+function cloneApiError(error, requestId) {
+    if (!(error instanceof BBRadarApiError)) {
+        return error;
+    }
+    return new BBRadarApiError({
+        message: error.message,
+        requestId,
+        upstreamRequestId: error.upstreamRequestId,
+        status: error.status,
+        detail: error.detail,
+        errors: error.errors,
+        cause: error
+    });
+}
+//# sourceMappingURL=bbradarClient.js.map

package/dist/bbradarClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bbradarClient.js","sourceRoot":"","sources":["../src/bbradarClient.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,26 @@
+export type CacheEntry<T> = {
+    value: T;
+    expiresAt: number;
+};
+export type CacheStats = {
+    entries: number;
+    max_entries: number;
+    ttl_ms: number;
+    hits: number;
+    misses: number;
+    sets: number;
+    evictions: number;
+};
+export declare class TtlCache<T> {
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly entries;
+    private hits;
+    private misses;
+    private sets;
+    private evictions;
+    constructor(maxEntries?: number, ttlMs?: number);
+    get(key: string): CacheEntry<T> | undefined;
+    set(key: string, value: T): void;
+    stats(): CacheStats;
+}

package/dist/cache.js

@@ -0,0 +1,60 @@
+export class TtlCache {
+    maxEntries;
+    ttlMs;
+    entries = new Map();
+    hits = 0;
+    misses = 0;
+    sets = 0;
+    evictions = 0;
+    constructor(maxEntries = 500, ttlMs = 30_000) {
+        this.maxEntries = maxEntries;
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry) {
+            this.misses += 1;
+            return undefined;
+        }
+        if (entry.expiresAt <= Date.now()) {
+            this.entries.delete(key);
+            this.misses += 1;
+            return undefined;
+        }
+        this.hits += 1;
+        return entry;
+    }
+    set(key, value) {
+        if (this.ttlMs <= 0 || this.maxEntries <= 0) {
+            return;
+        }
+        if (this.entries.has(key)) {
+            this.entries.delete(key);
+        }
+        while (this.entries.size >= this.maxEntries) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey === undefined) {
+                break;
+            }
+            this.entries.delete(oldestKey);
+            this.evictions += 1;
+        }
+        this.entries.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttlMs
+        });
+        this.sets += 1;
+    }
+    stats() {
+        return {
+            entries: this.entries.size,
+            max_entries: this.maxEntries,
+            ttl_ms: this.ttlMs,
+            hits: this.hits,
+            misses: this.misses,
+            sets: this.sets,
+            evictions: this.evictions
+        };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,QAAQ;IAQA;IACA;IARF,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IACpD,IAAI,GAAG,CAAC,CAAC;IACT,MAAM,GAAG,CAAC,CAAC;IACX,IAAI,GAAG,CAAC,CAAC;IACT,SAAS,GAAG,CAAC,CAAC;IAEtB,YACmB,aAAa,GAAG,EAChB,QAAQ,MAAM;QADd,eAAU,GAAV,UAAU,CAAM;QAChB,UAAK,GAAL,KAAK,CAAS;IAC9B,CAAC;IAEJ,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEpC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAEnD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM;YACR,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACnC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,KAAK;QACH,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YAC1B,WAAW,EAAE,IAAI,CAAC,UAAU;YAC5B,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export type ServerConfig = {
+    apiKey: string;
+    apiBaseUrl: string;
+    webBaseUrl: string;
+    cacheTtlMs: number;
+    cacheMaxEntries: number;
+    defaultRateLimitPerMinute: number;
+    exportRateLimitPerMinute: number;
+    requestTimeoutMs: number;
+    validateOnStartup: boolean;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ServerConfig;