@bbradar/mcp 0.1.19 → 0.1.20

package/README.md

@@ -112,6 +112,43 @@ Most tools that accept `program_id` also accept a human program name or handle.
 
 `find_programs_by_target` defaults to flexible target matching. It accepts bare domains, full URLs, wildcard scopes, target names, package/repo-style identifiers, or short phrases like `known api target`.
 
+## Performance Tuning
+
+The defaults expose the complete tool surface and full text results while enabling bounded concurrency, positive response caching, in-flight request coalescing, and short negative caching for repeated 404/405 lookups.
+
+| Environment variable | Default | Purpose |
+| --- | ---: | --- |
+| `BBRADAR_MCP_CACHE_TTL_SECONDS` | `30` | Successful GET response cache lifetime. Set to `0` to disable. |
+| `BBRADAR_MCP_NEGATIVE_CACHE_TTL_SECONDS` | `15` | Repeated 404/405 cache lifetime. Set to `0` to disable. |
+| `BBRADAR_MCP_CACHE_MAX_ENTRIES` | `500` | Maximum entries in each local response cache. |
+| `BBRADAR_MCP_MAX_CONCURRENT_REQUESTS` | `6` | Maximum simultaneous upstream BBRadar API requests. |
+| `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout for each active upstream request; queue time is excluded. |
+| `BBRADAR_MCP_COMPACT_TOOL_TEXT` | `false` | Set to `true` to avoid duplicating results for clients that consume MCP `structuredContent`. |
+| `BBRADAR_MCP_TOOL_PROFILE` | `full` | Complete specialized tool surface. Set to `core` only when a smaller 15-tool discovery payload is preferred. |
+
+No performance variables are required. Caching, request coalescing, name-resolution improvements, early stopping, bounded concurrency, aggregate-call parallelism, and upstream quota protection are always active.
+
+The client learns the API's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers per endpoint group. Once an observed group reaches zero, it blocks additional requests to that group locally until reset instead of repeatedly hitting the API, while unrelated endpoint groups remain usable. A rolling 60-second guard also enforces the documented shared key-and-IP ceiling across uncached upstream requests. A real `429` honors `Retry-After` as a global cooldown; requests are not automatically retried, so one MCP action cannot amplify a rate-limit response into more API calls. The global upstream concurrency default is six, with the heavier target-changes endpoint capped at three.
+
+Call `get_mcp_status` to inspect cache hit rates, negative-cache hits, concurrency state, the latest upstream quota state, actual upstream request counts, per-endpoint status totals, and timing.
+
+### Optimized wildcard discovery
+
+For the latest added wildcard targets from one platform with reward and report-count limits, use `get_latest_added_targets`:
+
+```json
+{
+  "target_type": "wildcard",
+  "platforms": ["HackerOne"],
+  "min_reward": 5000,
+  "max_public_report_count": 10,
+  "require_known_report_count": true,
+  "include_full_target_list": false
+}
+```
+
+This path uses one recent-changes request. Use `find_wildcard_programs` for a ranked current-program shortlist, or `find_recently_added_wildcards` when recent wildcard activity matters. Both accept platform, minimum reward, report-count, and bounded target-sample filters. Wildcard shortlist workflows automatically send the `wildcard` target-type tag upstream before applying reward and report filters locally, so their page budget is spent only on relevant programs. `find_low_competition_high_reward` also accepts `min_wildcards`.
+
 ## Tools
 
 - `search_programs`

package/dist/bbradarClient.d.ts

@@ -1,4 +1,3 @@
-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 = {
@@ -25,6 +24,9 @@ export declare class BBRadarApiError extends Error {
     readonly status: number | undefined;
     readonly detail?: unknown;
     readonly errors?: unknown;
+    readonly cached: boolean;
+    readonly coalesced: boolean;
+    readonly cacheExpiresAt: string | undefined;
     constructor(params: {
         message: string;
         requestId: string;
@@ -32,19 +34,111 @@ export declare class BBRadarApiError extends Error {
         status?: number | undefined;
         detail?: unknown;
         errors?: unknown;
+        cached?: boolean | undefined;
+        coalesced?: boolean | undefined;
+        cacheExpiresAt?: string | undefined;
         cause?: unknown;
     });
 }
 export declare class BBRadarClient {
     private readonly config;
     private readonly cache;
+    private readonly negativeCache;
     private readonly inFlight;
+    private readonly endpointMetrics;
+    private readonly requestQueue;
+    private readonly endpointRequestQueues;
+    private readonly endpointActiveRequests;
+    private readonly upstreamRateLimits;
+    private readonly upstreamRequestTimestampsMs;
+    private activeRequests;
+    private globalBlockedUntilMs;
     constructor(config: ServerConfig);
     diagnostics(): {
-        response_cache: CacheStats & {
+        response_cache: {
+            entries: number;
+            max_entries: number;
+            ttl_ms: number;
+            hits: number;
+            misses: number;
+            sets: number;
+            evictions: number;
+            expirations: number;
+            enabled: boolean;
+        };
+        negative_response_cache: {
+            entries: number;
+            max_entries: number;
+            ttl_ms: number;
+            hits: number;
+            misses: number;
+            sets: number;
+            evictions: number;
+            expirations: number;
             enabled: boolean;
         };
         in_flight_requests: number;
+        request_concurrency: {
+            limit: number;
+            active: number;
+            queued: number;
+            endpoint_limits: {
+                target_changes: {
+                    limit: number;
+                    active: number;
+                    queued: number;
+                };
+            };
+        };
+        upstream_request_window: {
+            enforced: boolean;
+            limit: number;
+            window_ms: number;
+            used: number;
+            remaining: number | undefined;
+            resets_at: string | undefined;
+        };
+        upstream_rate_limit: {
+            observed: boolean;
+            bucket: string | undefined;
+            limit: number | undefined;
+            remaining: number | undefined;
+            reset_at: string | undefined;
+            blocked: boolean;
+            globally_blocked: boolean;
+            blocked_until: string | undefined;
+            observed_at: string | undefined;
+            last_status: number | undefined;
+            buckets: {
+                [k: string]: {
+                    limit: number | undefined;
+                    remaining: number | undefined;
+                    reset_at: string | undefined;
+                    blocked: boolean;
+                    blocked_until: string | undefined;
+                    observed_at: string | undefined;
+                    last_status: number | undefined;
+                };
+            };
+        };
+        upstream_requests: {
+            actual_requests: number;
+            errors: number;
+            avg_ms: number;
+            max_ms: number;
+            by_endpoint: {
+                [k: string]: {
+                    requests: number;
+                    errors: number;
+                    avg_ms: number;
+                    max_ms: number;
+                    last_ms: number;
+                    statuses: {
+                        [k: string]: number;
+                    };
+                };
+            };
+        };
     };
     validateKey(): Promise<void>;
     listPrograms(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
@@ -56,6 +150,18 @@ export declare class BBRadarClient {
     exportTargets(body: Record<string, unknown>): Promise<ApiResult<unknown>>;
     request<T = unknown>(options: ApiRequestOptions): Promise<ApiResult<T>>;
     private fetchFromApi;
+    private withRequestSlot;
+    private withGlobalRequestSlot;
+    private withEndpointRequestSlot;
+    private recordEndpointMetric;
+    private reserveUpstreamRequest;
+    private observeUpstreamRateLimit;
+    private rateLimitState;
+    private refreshUpstreamRequestWindow;
+    private upstreamRequestWindowDiagnostics;
+    private shouldEnforceSharedRequestWindow;
+    private refreshUpstreamRateLimitWindow;
+    private upstreamRateLimitDiagnostics;
     private buildUrl;
     private headers;
 }