@bbradar/mcp 0.1.3 → 0.1.4

package/dist/server.js

@@ -29,6 +29,8 @@ const DEFAULT_FILTER_TARGET_SAMPLE_PROGRAMS = 10;
 const MAX_FILTER_TARGET_SAMPLE_PROGRAMS = 25;
 const MAX_LOCAL_EXPORT_RESOURCES = 25;
 const EXPORT_PREVIEW_LIMIT = 25;
+const STALE_PROGRAM_ID_RESOLVE_PAGES = 5;
+const STALE_PROGRAM_ID_RESOLVE_BUDGET = 5;
 const SDK_VERSION = "1.29.0";
 const WEB3_TAGS = ["web3", "crypto", "blockchain", "smart-contract", "smart contract", "defi", "nft", "ethereum", "solana", "solidity"];
 const WEB3_CONTEST_SIGNALS = ["contest", "audit", "competitive", "code4rena", "sherlock", "cantina", "codehawks", "hats", "spearbit", "warden"];
@@ -124,8 +126,11 @@ const apiEnvelopeOutputShape = {
     upstream_request_id: z.string().optional(),
     fetched_at: z.string().optional(),
     cache: cacheOutputSchema.optional(),
+    source_requests: z.array(jsonRecordSchema).optional(),
     mcp_rate_limit: rateLimitOutputSchema.optional(),
     mcp_timing: toolTimingOutputSchema.optional(),
+    warnings: z.array(z.string()).optional(),
+    program_id_resolution: jsonRecordSchema.optional(),
     error: errorOutputSchema.optional()
 };
 const programListOutputShape = {
@@ -229,9 +234,11 @@ export function createBbradarServer(client, config) {
         },
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_program", config, rateLimiter, async () => {
-        const api = await client.getProgram(args.program_id);
-        return withApiMetadata(api, {
-            program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
+        return runProgramIdTool(client, config, args.program_id, async (programId) => {
+            const api = await client.getProgram(programId);
+            return withApiMetadata(api, {
+                program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
+            });
         });
     }));
     server.registerTool("resolve_program", {
@@ -312,23 +319,25 @@ export function createBbradarServer(client, config) {
         },
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_program_targets", config, rateLimiter, async () => {
-        const api = await client.getProgramTargets(args.program_id);
-        const data = readObject(api.data);
-        const rawTargets = readArray(data?.targets);
-        const sanitizedTargets = rawTargets.map(sanitizeTarget).filter((target) => targetHasAllowedScope(target, args));
-        const targets = sanitizedTargets.slice(args.offset, args.offset + args.limit);
-        return withApiMetadata(api, {
-            program_id: args.program_id,
-            targets: formatTargetList(targets, args.output_mode),
-            meta: {
-                offset: args.offset,
-                limit: args.limit,
-                output_mode: args.output_mode,
-                total_active_targets: rawTargets.length,
-                total_after_filters: sanitizedTargets.length,
-                returned: targets.length,
-                has_more: args.offset + args.limit < sanitizedTargets.length
-            }
+        return runProgramIdTool(client, config, args.program_id, async (programId) => {
+            const api = await client.getProgramTargets(programId);
+            const data = readObject(api.data);
+            const rawTargets = readArray(data?.targets);
+            const sanitizedTargets = rawTargets.map(sanitizeTarget).filter((target) => targetHasAllowedScope(target, args));
+            const targets = sanitizedTargets.slice(args.offset, args.offset + args.limit);
+            return withApiMetadata(api, {
+                program_id: programId,
+                targets: formatTargetList(targets, args.output_mode),
+                meta: {
+                    offset: args.offset,
+                    limit: args.limit,
+                    output_mode: args.output_mode,
+                    total_active_targets: rawTargets.length,
+                    total_after_filters: sanitizedTargets.length,
+                    returned: targets.length,
+                    has_more: args.offset + args.limit < sanitizedTargets.length
+                }
+            });
         });
     }));
     server.registerTool("get_recent_changes", {
@@ -414,7 +423,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_scope_summary", config, rateLimiter, async () => getProgramScopeSummary(client, config, args)));
+    }, (args) => runTool("get_program_scope_summary", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeSummary(client, config, { ...args, program_id: programId }))));
     server.registerTool("get_program_target_breakdown", {
         title: "Get Program Target Breakdown",
         description: "Target type, scope tag, language tag, and bucket counts for one program.",
@@ -433,7 +442,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_target_breakdown", config, rateLimiter, async () => getProgramTargetBreakdown(client, config, args)));
+    }, (args) => runTool("get_program_target_breakdown", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramTargetBreakdown(client, config, { ...args, program_id: programId }))));
     server.registerTool("get_program_scope_delta", {
         title: "Get Program Scope Delta",
         description: "Compact recent scope changes for one program.",
@@ -459,7 +468,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => getProgramScopeDelta(client, config, args)));
+    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeDelta(client, config, { ...args, program_id: programId }))));
     server.registerTool("get_recent_target_activity", {
         title: "Get Recent Target Activity",
         description: "Recent target changes grouped by program.",
@@ -1155,7 +1164,7 @@ export function createBbradarServer(client, config) {
             changes: z.array(jsonRecordSchema).optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("summarize_program_activity", config, rateLimiter, async () => summarizeProgramActivity(client, config, args.program_id, args.recent_changes_limit)));
+    }, (args) => runTool("summarize_program_activity", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => summarizeProgramActivity(client, config, programId, args.recent_changes_limit))));
     server.registerTool("get_program_brief", {
         title: "Get Program Brief",
         description: "Compact worth-hunting brief for one program.",
@@ -1178,7 +1187,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_brief", config, rateLimiter, async () => getProgramBrief(client, config, args)));
+    }, (args) => runTool("get_program_brief", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramBrief(client, config, { ...args, program_id: programId }))));
     server.registerTool("find_recently_added_wildcards", {
         title: "Find Recently Added Wildcards",
         description: "Recently added wildcard programs.",
@@ -1307,7 +1316,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_delta", config, rateLimiter, async () => getProgramDelta(client, config, args)));
+    }, (args) => runTool("get_program_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramDelta(client, config, { ...args, program_id: programId }))));
     server.registerTool("export_targets", {
         title: "Export BBRadar Targets",
         description: `Read-only target export. limit max ${MAX_TARGET_EXPORT}.`,
@@ -1374,9 +1383,11 @@ function registerResources(server, client, config, exportStore) {
         mimeType: "application/json"
     }, async (uri) => {
         const programId = parseProgramIdFromResourceUri(uri);
-        const api = await client.getProgram(programId);
-        const payload = withApiMetadata(api, {
-            program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
+        const payload = await runProgramIdTool(client, config, programId, async (resolvedProgramId) => {
+            const api = await client.getProgram(resolvedProgramId);
+            return withApiMetadata(api, {
+                program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
+            });
         });
         return jsonResource(uri.toString(), payload);
     });
@@ -1386,15 +1397,17 @@ function registerResources(server, client, config, exportStore) {
         mimeType: "application/json"
     }, async (uri) => {
         const programId = parseProgramIdFromResourceUri(uri);
-        const api = await client.getProgramTargets(programId);
-        const data = readObject(api.data);
-        const targets = readArray(data?.targets).map(sanitizeTarget);
-        const payload = withApiMetadata(api, {
-            program_id: programId,
-            targets,
-            meta: {
-                total_active_targets: targets.length
-            }
+        const payload = await runProgramIdTool(client, config, programId, async (resolvedProgramId) => {
+            const api = await client.getProgramTargets(resolvedProgramId);
+            const data = readObject(api.data);
+            const targets = readArray(data?.targets).map(sanitizeTarget);
+            return withApiMetadata(api, {
+                program_id: resolvedProgramId,
+                targets,
+                meta: {
+                    total_active_targets: targets.length
+                }
+            });
         });
         return jsonResource(uri.toString(), payload);
     });
@@ -1433,6 +1446,136 @@ function registerResources(server, client, config, exportStore) {
         }));
     });
 }
+async function getProgramWithIdFallback(client, config, requestedProgramId) {
+    try {
+        return {
+            api: await client.getProgram(requestedProgramId),
+            programId: requestedProgramId,
+            sourceRequests: [],
+            warnings: []
+        };
+    }
+    catch (error) {
+        if (!isProgramNotFoundError(error)) {
+            throw error;
+        }
+        const fallback = await resolveStaleProgramId(client, config, requestedProgramId, error);
+        if (!fallback) {
+            throw error;
+        }
+        return {
+            api: await client.getProgram(fallback.resolvedProgramId),
+            programId: fallback.resolvedProgramId,
+            sourceRequests: fallback.sourceRequests,
+            warnings: fallback.warnings,
+            fallback
+        };
+    }
+}
+async function runProgramIdTool(client, config, requestedProgramId, callback) {
+    try {
+        return await callback(requestedProgramId);
+    }
+    catch (error) {
+        if (!isProgramNotFoundError(error)) {
+            throw error;
+        }
+        const fallback = await resolveStaleProgramId(client, config, requestedProgramId, error);
+        if (!fallback) {
+            throw error;
+        }
+        const payload = await callback(fallback.resolvedProgramId);
+        return withProgramIdFallbackMetadata(payload, fallback);
+    }
+}
+async function resolveStaleProgramId(client, config, requestedProgramId, staleError) {
+    const query = programSearchText(requestedProgramId);
+    if (query.length < 2) {
+        return undefined;
+    }
+    const resolution = await resolveProgram(client, config, {
+        query,
+        platforms: [],
+        tags: [],
+        opportunity_levels: [],
+        max_pages: STALE_PROGRAM_ID_RESOLVE_PAGES,
+        max_results: 5,
+        output_mode: "compact",
+        upstream_request_budget: STALE_PROGRAM_ID_RESOLVE_BUDGET
+    });
+    const match = selectProgramIdFallbackMatch(requestedProgramId, resolution);
+    if (!match) {
+        return undefined;
+    }
+    const sourceRequests = readArray(resolution.source_requests).filter((request) => readObject(request) !== undefined);
+    const warnings = readArray(resolution.warnings).filter((warning) => typeof warning === "string");
+    const staleApiError = staleError instanceof BBRadarApiError ? staleError : undefined;
+    const fallbackWarning = `program_id ${requestedProgramId} was stale; automatically retried with resolved program_id ${match.resolvedProgramId}.`;
+    return {
+        requestedProgramId,
+        resolvedProgramId: match.resolvedProgramId,
+        query,
+        staleRequestId: staleApiError?.requestId,
+        staleUpstreamRequestId: staleApiError?.upstreamRequestId,
+        sourceRequests,
+        warnings: uniqueStrings([...warnings, fallbackWarning]),
+        resolution
+    };
+}
+function selectProgramIdFallbackMatch(requestedProgramId, resolution) {
+    const requestedHandle = normalizeTag(programHandleText(requestedProgramId));
+    const requestedSearchText = normalizeTag(programSearchText(requestedProgramId));
+    const candidates = readArray(resolution.matches)
+        .map((entry) => readObject(entry))
+        .filter((entry) => entry !== undefined)
+        .map((entry) => {
+        const program = readObject(entry.program);
+        const resolvedProgramId = stringField(entry, "program_id") ?? stringField(program, "id");
+        const candidateHandle = normalizeTag(stringField(program, "handle") ?? "");
+        const candidateSearchText = resolvedProgramId ? normalizeTag(programSearchText(resolvedProgramId)) : "";
+        const score = readNumber(entry.score) ?? 0;
+        const exactHandleMatch = candidateHandle === requestedHandle ||
+            candidateHandle === requestedSearchText ||
+            candidateSearchText === requestedSearchText;
+        return {
+            resolvedProgramId,
+            score,
+            exactHandleMatch
+        };
+    })
+        .filter((entry) => entry.resolvedProgramId !== undefined && entry.resolvedProgramId !== requestedProgramId && entry.exactHandleMatch && entry.score >= 80)
+        .sort((left, right) => right.score - left.score || left.resolvedProgramId.localeCompare(right.resolvedProgramId));
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const [best, next] = candidates;
+    if (!best || (next && best.score === next.score)) {
+        return undefined;
+    }
+    return {
+        resolvedProgramId: best.resolvedProgramId
+    };
+}
+function withProgramIdFallbackMetadata(payload, fallback) {
+    const sourceRequests = readArray(payload.source_requests).filter((request) => readObject(request) !== undefined);
+    const warnings = readArray(payload.warnings).filter((warning) => typeof warning === "string");
+    const resolution = stripUndefined({
+        requested_program_id: fallback.requestedProgramId,
+        resolved_program_id: fallback.resolvedProgramId,
+        query: fallback.query,
+        reason: "stale_program_id",
+        stale_status: 404,
+        stale_request_id: fallback.staleRequestId,
+        stale_upstream_request_id: fallback.staleUpstreamRequestId,
+        resolution_request_id: stringField(fallback.resolution, "request_id")
+    });
+    return stripUndefined({
+        ...payload,
+        source_requests: [...fallback.sourceRequests, ...sourceRequests],
+        warnings: uniqueStrings([...fallback.warnings, ...warnings]),
+        program_id_resolution: resolution
+    });
+}
 async function resolveProgram(client, config, input) {
     const warnings = [];
     const budget = {
@@ -2268,17 +2411,22 @@ async function comparePrograms(client, config, input) {
     const candidates = [];
     const sourceRequests = [];
     const errors = [];
+    const warnings = [];
     await mapWithConcurrency(input.program_ids, TARGET_SAMPLE_CONCURRENCY, async (programId) => {
         try {
-            const api = await client.getProgram(programId);
-            candidates.push(toProgramCandidate(api.data, config.webBaseUrl));
-            sourceRequests.push({
+            const lookup = await getProgramWithIdFallback(client, config, programId);
+            const api = lookup.api;
+            const requestSource = stripUndefined({
                 source: "program",
-                program_id: programId,
+                program_id: lookup.programId,
+                requested_program_id: lookup.programId === programId ? undefined : programId,
                 request_id: api.requestId,
                 upstream_request_id: api.upstreamRequestId,
                 ...apiSourceMetadata(api)
             });
+            candidates.push(toProgramCandidate(api.data, config.webBaseUrl));
+            sourceRequests.push(...lookup.sourceRequests, requestSource);
+            warnings.push(...lookup.warnings);
         }
         catch (error) {
             errors.push(programFetchError(programId, error));
@@ -2333,6 +2481,7 @@ async function comparePrograms(client, config, input) {
         partial_success: errors.length > 0,
         program_ids_requested: input.program_ids,
         failed_program_ids: errors.map((error) => error.program_id).filter((id) => typeof id === "string"),
+        warnings: warnings.length > 0 ? uniqueStrings(warnings) : undefined,
         errors: errors.length > 0 ? errors : undefined,
         source_requests: sourceRequests,
         compared_programs: candidates.map((candidate, index) => candidateOutput(candidate, index, targetSamples, input.output_mode ?? "compact")),
@@ -2673,13 +2822,15 @@ async function getRecentTargetActivity(client, config, input) {
     };
 }
 async function checkProgramNewTargets(client, config, input) {
-    const handle = programSearchText(input.program_id);
+    const programLookup = await getProgramWithIdFallback(client, config, input.program_id);
+    const programId = programLookup.programId;
+    const handle = programSearchText(programId);
     const api = await client.getRecentChanges({
         change_type: "added",
         include_removed: false,
         include_ineligible: input.include_ineligible,
         include_out_of_scope: false,
-        search: handle.length >= 2 ? handle : input.program_id,
+        search: handle.length >= 2 ? handle : programId,
         tags: input.target_type ? [input.target_type] : [],
         page: 1,
         page_size: input.page_size
@@ -2693,7 +2844,7 @@ async function checkProgramNewTargets(client, config, input) {
         const target = readObject(change.target);
         const changedAt = timestampField(change, "changed_at");
         return (stringField(change, "change_type") === "added" &&
-            stringField(readObject(change.program), "id") === input.program_id &&
+            stringField(readObject(change.program), "id") === programId &&
             target !== undefined &&
             (sinceTimestamp === undefined || changedAt >= sinceTimestamp) &&
             (!input.target_type || targetMatchesRequestedType(target, input.target_type)) &&
@@ -2709,18 +2860,30 @@ async function checkProgramNewTargets(client, config, input) {
         .map((change) => readObject(change.target))
         .filter((target) => target !== undefined);
     const latest = matchingChanges[0];
-    return stripUndefined({
+    const sourceRequests = [
+        {
+            source: "program",
+            program_id: programId,
+            requested_program_id: programId === input.program_id ? undefined : input.program_id,
+            request_id: programLookup.api.requestId,
+            upstream_request_id: programLookup.api.upstreamRequestId,
+            ...apiSourceMetadata(programLookup.api)
+        },
+        {
+            source: "recent_changes",
+            request_id: api.requestId,
+            upstream_request_id: api.upstreamRequestId,
+            ...apiSourceMetadata(api)
+        }
+    ];
+    const payload = stripUndefined({
         request_id: randomUUID(),
-        source_requests: [
-            {
-                source: "recent_changes",
-                request_id: api.requestId,
-                upstream_request_id: api.upstreamRequestId,
-                ...apiSourceMetadata(api)
-            }
-        ],
-        program_id: input.program_id,
-        program: latest ? formatProgram(addProgramResourceLinks(readObject(latest.program) ?? {}), "compact") : undefined,
+        source_requests: sourceRequests,
+        warnings: !programLookup.fallback && programLookup.warnings.length > 0 ? uniqueStrings(programLookup.warnings) : undefined,
+        program_id: programId,
+        program: latest
+            ? formatProgram(addProgramResourceLinks(readObject(latest.program) ?? {}), "compact")
+            : formatProgram(addProgramResourceLinks(sanitizeProgram(programLookup.api.data, config.webBaseUrl)), "compact"),
         has_new_targets: matchingChanges.length > 0,
         new_target_count: matchingChanges.length,
         latest_added_at: latest ? stringField(latest, "changed_at") : undefined,
@@ -2738,6 +2901,7 @@ async function checkProgramNewTargets(client, config, input) {
             scan_may_be_incomplete: (readNumber(upstreamMeta?.total_pages) ?? 1) > 1
         })
     });
+    return programLookup.fallback ? withProgramIdFallbackMetadata(payload, programLookup.fallback) : payload;
 }
 async function checkWatchlistNewTargets(client, config, input) {
     const watchlist = new Set(input.program_ids);
@@ -3504,6 +3668,10 @@ function programSearchText(programId) {
     const lastPathSegment = handle.split("/").filter(Boolean).at(-1) ?? handle;
     return lastPathSegment.length >= 2 ? lastPathSegment : handle;
 }
+function programHandleText(programId) {
+    const colonIndex = programId.indexOf(":");
+    return colonIndex >= 0 ? programId.slice(colonIndex + 1) : programId;
+}
 function normalizeFindProgramsInput(input) {
     const warnings = [];
     const normalized = { ...input };
@@ -3984,6 +4152,9 @@ function addUniqueWarning(warnings, warning) {
         warnings.push(warning);
     }
 }
+function isProgramNotFoundError(error) {
+    return error instanceof BBRadarApiError && error.status === 404;
+}
 function runImmediately(callback) {
     return callback();
 }