@bbradar/mcp 0.1.6 → 0.1.7

package/dist/server.js

@@ -92,10 +92,9 @@ const filterValueSchema = z
     message: "Filter values cannot contain commas or control characters."
 });
 const stringListSchema = z
-    .array(filterValueSchema)
-    .max(50)
-    .default([])
+    .preprocess(normalizeStringListInput, z.array(filterValueSchema).max(50).default([]))
     .describe("Filter values.");
+const acceptedTargetLimitSchema = z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM);
 const searchTextSchema = z
     .string()
     .trim()
@@ -329,7 +328,7 @@ export function createBbradarServer(client, config) {
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(25),
+            max_targets: acceptedTargetLimitSchema.default(25),
             group_limit: z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM).default(100),
             target_list_mode: targetListModeSchema.default("identifiers"),
             max_resolve_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
@@ -486,7 +485,7 @@ export function createBbradarServer(client, config) {
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(50),
+            max_targets: acceptedTargetLimitSchema.default(50),
             target_list_mode: targetListModeSchema.default("identifiers")
         },
         outputSchema: {
@@ -498,7 +497,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeDelta(client, config, { ...args, program_id: programId }))));
+    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeDelta(client, config, { ...args, program_id: programId }), (indexFallback) => getProgramScopeDeltaFromIndexedProgram(client, config, { ...args, program_id: indexFallback.resolvedProgramId }, indexFallback.program))));
     server.registerTool("get_recent_target_activity", {
         title: "Get Recent Target Activity",
         description: "Recent target changes grouped by program.",
@@ -534,7 +533,7 @@ export function createBbradarServer(client, config) {
             target_type: filterValueSchema.optional(),
             include_ineligible: z.boolean().default(false).describe("Include ineligible."),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(25),
+            max_targets: acceptedTargetLimitSchema.default(25),
             target_list_mode: targetListModeSchema.default("identifiers")
         },
         outputSchema: {
@@ -1366,24 +1365,33 @@ export function createBbradarServer(client, config) {
         },
         outputSchema: {
             ...apiEnvelopeOutputShape,
-            export: z.unknown().optional()
+            export: z.unknown().optional(),
+            meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
     }, (args) => runTool("export_targets", config, rateLimiter, async () => {
-        const api = await client.exportTargets(compactRecord(args));
-        const exportId = randomUUID();
-        const sanitizedExport = sanitizeTargetsForExport(api.data, args.limit);
-        const resourceUri = exportResourceUri(exportId);
-        rememberExport(exportStore, exportId, sanitizedExport);
-        return withApiMetadata(api, {
-            export: {
-                export_id: exportId,
-                resource_uri: resourceUri,
-                preview: previewExportPayload(sanitizedExport),
-                returned_preview_count: previewExportCount(sanitizedExport),
-                limit: args.limit
+        try {
+            const api = await client.exportTargets(compactRecord(args));
+            const exportId = randomUUID();
+            const sanitizedExport = sanitizeTargetsForExport(api.data, args.limit);
+            const resourceUri = exportResourceUri(exportId);
+            rememberExport(exportStore, exportId, sanitizedExport);
+            return withApiMetadata(api, {
+                export: {
+                    export_id: exportId,
+                    resource_uri: resourceUri,
+                    preview: previewExportPayload(sanitizedExport),
+                    returned_preview_count: previewExportCount(sanitizedExport),
+                    limit: args.limit
+                }
+            });
+        }
+        catch (error) {
+            if (!(error instanceof BBRadarApiError) || (error.status !== 404 && error.status !== 405)) {
+                throw error;
             }
-        });
+            return exportTargetsFromProgramTargetsFallback(client, config, exportStore, args, error);
+        }
     }));
     registerPrompts(server);
     registerResources(server, client, config, exportStore);
@@ -2827,7 +2835,7 @@ async function getProgramTargetsPayload(client, input, programId) {
     });
 }
 async function getProgramTargetsExportFallbackPayload(client, input, programId) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, programId);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, programId);
     const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input));
     const targets = sanitizedTargets.slice(input.offset, input.offset + input.limit);
     return stripUndefined({
@@ -2853,6 +2861,42 @@ async function getProgramTargetsExportFallbackPayload(client, input, programId)
         })
     });
 }
+async function fetchProgramTargetsWithEndpointFallback(client, programId) {
+    try {
+        const api = await client.getProgramTargets(programId);
+        const data = readObject(api.data);
+        const rawTargets = readArray(data?.targets).map(sanitizeTarget);
+        return {
+            requestId: api.requestId,
+            upstreamRequestId: api.upstreamRequestId,
+            fetchedAt: api.fetchedAt,
+            cache: readObject(stripUndefined({
+                hit: api.cached,
+                coalesced_live_request: api.coalesced,
+                expires_at: api.cacheExpiresAt
+            })),
+            source: "program_targets",
+            rawTargets,
+            sourceRequests: [
+                {
+                    source: "program_targets",
+                    program_id: programId,
+                    request_id: api.requestId,
+                    upstream_request_id: api.upstreamRequestId,
+                    ...apiSourceMetadata(api)
+                }
+            ],
+            warnings: [],
+            unavailable: false
+        };
+    }
+    catch (error) {
+        if (!isProgramNotFoundError(error)) {
+            throw error;
+        }
+        return fetchProgramTargetsFromExportFallback(client, programId);
+    }
+}
 async function fetchProgramTargetsFromExportFallback(client, programId) {
     try {
         const api = await client.exportTargets({
@@ -2908,6 +2952,116 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
         };
     }
 }
+async function exportTargetsFromProgramTargetsFallback(client, config, exportStore, input, exportError) {
+    const warnings = ["Target export endpoint is unavailable; assembled a fallback export from per-program target endpoints."];
+    const sourceRequests = [
+        {
+            source: "target_export",
+            failed: true,
+            request_id: exportError.requestId,
+            upstream_request_id: exportError.upstreamRequestId,
+            status: exportError.status
+        }
+    ];
+    const programIds = input.program_ids.length > 0 ? input.program_ids : await discoverExportProgramIds(client, input, sourceRequests, warnings);
+    const targets = [];
+    const errors = [];
+    for (const programId of programIds) {
+        if (targets.length >= input.limit) {
+            break;
+        }
+        try {
+            const payload = await runProgramIdTool(client, config, programId, (resolvedProgramId) => getProgramTargetsPayload(client, {
+                include_out_of_scope: input.include_out_of_scope,
+                include_ineligible: input.include_ineligible,
+                strict_scope_filter: false,
+                offset: 0,
+                limit: input.limit - targets.length,
+                output_mode: "full"
+            }, resolvedProgramId), (indexFallback) => getProgramTargetsExportFallbackPayload(client, {
+                include_out_of_scope: input.include_out_of_scope,
+                include_ineligible: input.include_ineligible,
+                strict_scope_filter: false,
+                offset: 0,
+                limit: input.limit - targets.length,
+                output_mode: "full"
+            }, indexFallback.resolvedProgramId));
+            const resolvedProgramId = stringField(payload, "program_id") ?? programId;
+            sourceRequests.push(...readArray(payload.source_requests).filter((request) => readObject(request) !== undefined));
+            warnings.push(...readArray(payload.warnings).filter((warning) => typeof warning === "string"));
+            for (const target of readArray(payload.targets)) {
+                const object = readObject(target);
+                if (!object) {
+                    continue;
+                }
+                targets.push({ program_id: resolvedProgramId, ...object });
+                if (targets.length >= input.limit) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            errors.push(apiOperationError(programId, error));
+        }
+    }
+    if (input.format === "csv") {
+        warnings.push("Fallback target export returns JSON even when CSV was requested.");
+    }
+    const exportPayload = stripUndefined({
+        targets,
+        meta: {
+            export_source: "program_targets_fallback",
+            requested_program_count: programIds.length,
+            returned: targets.length,
+            limit: input.limit,
+            format: "json"
+        },
+        generated_at: new Date().toISOString()
+    });
+    const exportId = randomUUID();
+    const resourceUri = exportResourceUri(exportId);
+    rememberExport(exportStore, exportId, exportPayload);
+    return stripUndefined({
+        request_id: randomUUID(),
+        source_requests: sourceRequests,
+        warnings: uniqueStrings(warnings),
+        errors: errors.length > 0 ? errors : undefined,
+        export: {
+            export_id: exportId,
+            resource_uri: resourceUri,
+            preview: previewExportPayload(exportPayload),
+            returned_preview_count: previewExportCount(exportPayload),
+            limit: input.limit
+        },
+        meta: stripUndefined({
+            export_source: "program_targets_fallback",
+            requested_program_count: programIds.length,
+            returned: targets.length,
+            failed_program_count: errors.length,
+            fallback_error: apiOperationError("target_export", exportError)
+        })
+    });
+}
+async function discoverExportProgramIds(client, input, sourceRequests, warnings) {
+    const budget = {
+        initial: 1,
+        remaining: 1
+    };
+    const collected = await collectPrograms(client, {
+        platforms: input.platforms,
+        tags: input.tags,
+        updated_since: undefined,
+        opportunity_levels: input.opportunity_levels,
+        max_pages: 1,
+        budget,
+        warnings
+    });
+    sourceRequests.push(...collected.sourceRequests);
+    return uniqueStrings(collected.programs
+        .map((program) => stringField(sanitizeProgram(program, ""), "id"))
+        .filter((programId) => programId !== undefined)
+        .slice(0, input.limit));
+}
 function readExportTargetRows(data) {
     if (Array.isArray(data)) {
         return data;
@@ -2958,7 +3112,7 @@ async function getProgramScopeSummary(client, config, input) {
     };
 }
 async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, input) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, input.program_id);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
         include_out_of_scope: input.include_out_of_scope,
         include_ineligible: input.include_ineligible,
@@ -3031,7 +3185,7 @@ async function getProgramTargetBreakdown(client, config, input) {
     };
 }
 async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback, input) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, input.program_id);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
         include_out_of_scope: input.include_out_of_scope,
         include_ineligible: input.include_ineligible,
@@ -3069,19 +3223,8 @@ async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback,
 async function getProgramScopeDelta(client, config, input) {
     const programApi = await client.getProgram(input.program_id);
     const program = addProgramResourceLinks(sanitizeProgram(programApi.data, config.webBaseUrl));
-    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope);
-    const sinceTimestamp = input.since ? Date.parse(input.since) : undefined;
-    const filteredChanges = changesPayload.changes
-        .filter((change) => !input.change_type || stringField(change, "change_type") === input.change_type)
-        .filter((change) => sinceTimestamp === undefined || timestampField(change, "changed_at") >= sinceTimestamp)
-        .filter((change) => {
-        const target = readObject(change.target);
-        return !input.target_type || (target !== undefined && targetMatchesRequestedType(target, input.target_type));
-    })
-        .filter((change) => {
-        const target = readObject(change.target);
-        return input.language_tags.length === 0 || (target !== undefined && targetMatchesAnySignal(target, input.language_tags));
-    });
+    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope, input.max_targets);
+    const filteredChanges = filterProgramScopeDeltaChanges(changesPayload.changes, input);
     const limitedChanges = filteredChanges.slice(0, input.max_targets);
     return stripUndefined({
         request_id: randomUUID(),
@@ -3106,10 +3249,55 @@ async function getProgramScopeDelta(client, config, input) {
             change_type: input.change_type,
             target_type: input.target_type,
             language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
-            target_list_mode: input.target_list_mode
+            target_list_mode: input.target_list_mode,
+            upstream_total_pages: readNumber(changesPayload.meta?.total_pages),
+            pages_fetched: readNumber(changesPayload.meta?.pages_fetched),
+            scan_may_be_incomplete: (readNumber(changesPayload.meta?.total_pages) ?? 1) > (readNumber(changesPayload.meta?.pages_fetched) ?? 1)
+        })
+    });
+}
+async function getProgramScopeDeltaFromIndexedProgram(client, config, input, indexedProgram) {
+    const program = addProgramResourceLinks(indexedProgram);
+    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope, input.max_targets);
+    const filteredChanges = filterProgramScopeDeltaChanges(changesPayload.changes, input);
+    const limitedChanges = filteredChanges.slice(0, input.max_targets);
+    return stripUndefined({
+        request_id: randomUUID(),
+        source_requests: changesPayload.sourceRequests,
+        program: formatProgram(program, "compact"),
+        delta: buildScopeDelta(limitedChanges, input.target_list_mode),
+        changes: limitedChanges.map((change) => formatChange(change, "compact")),
+        meta: stripUndefined({
+            recent_changes_scanned: changesPayload.changes.length,
+            changes_after_filters: filteredChanges.length,
+            returned: limitedChanges.length,
+            has_more: filteredChanges.length > limitedChanges.length,
+            since: input.since,
+            change_type: input.change_type,
+            target_type: input.target_type,
+            language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
+            target_list_mode: input.target_list_mode,
+            program_detail_source: "program_index",
+            upstream_total_pages: readNumber(changesPayload.meta?.total_pages),
+            pages_fetched: readNumber(changesPayload.meta?.pages_fetched),
+            scan_may_be_incomplete: (readNumber(changesPayload.meta?.total_pages) ?? 1) > (readNumber(changesPayload.meta?.pages_fetched) ?? 1)
         })
     });
 }
+function filterProgramScopeDeltaChanges(changes, input) {
+    const sinceTimestamp = input.since ? Date.parse(input.since) : undefined;
+    return changes
+        .filter((change) => !input.change_type || stringField(change, "change_type") === input.change_type)
+        .filter((change) => sinceTimestamp === undefined || timestampField(change, "changed_at") >= sinceTimestamp)
+        .filter((change) => {
+        const target = readObject(change.target);
+        return !input.target_type || (target !== undefined && targetMatchesRequestedType(target, input.target_type));
+    })
+        .filter((change) => {
+        const target = readObject(change.target);
+        return input.language_tags.length === 0 || (target !== undefined && targetMatchesAnySignal(target, input.language_tags));
+    });
+}
 async function getRecentTargetActivity(client, config, input) {
     const query = toQuery({
         change_type: input.change_type,
@@ -3517,32 +3705,45 @@ async function getProgramDelta(client, config, input) {
         meta: changes.meta
     };
 }
-async function fetchProgramChanges(client, config, programId, pageSize, includeRemoved, includeIneligible, includeOutOfScope) {
+async function fetchProgramChanges(client, config, programId, pageSize, includeRemoved, includeIneligible, includeOutOfScope, maxChanges = pageSize) {
     const handle = programSearchText(programId);
-    const api = await client.getRecentChanges({
-        search: handle.length >= 2 ? handle : programId,
-        include_removed: includeRemoved,
-        include_ineligible: includeIneligible,
-        include_out_of_scope: includeOutOfScope,
-        page: 1,
-        page_size: pageSize
-    });
-    const data = readObject(api.data);
-    const changes = readArray(data?.results)
-        .map((change) => sanitizeChange(change, config.webBaseUrl))
-        .filter((change) => stringField(readObject(change.program), "id") === programId);
-    return {
-        changes,
-        meta: sanitizeJson(data?.meta),
-        sourceRequests: [
-            {
-                source: "recent_changes",
-                request_id: api.requestId,
-                upstream_request_id: api.upstreamRequestId,
-                ...apiSourceMetadata(api)
-            }
-        ]
-    };
+    const changes = [];
+    const sourceRequests = [];
+    let meta;
+    const maxPages = Math.max(1, Math.ceil(maxChanges / pageSize));
+    for (let page = 1; page <= maxPages && changes.length < maxChanges; page += 1) {
+        const api = await client.getRecentChanges({
+            search: handle.length >= 2 ? handle : programId,
+            include_removed: includeRemoved,
+            include_ineligible: includeIneligible,
+            include_out_of_scope: includeOutOfScope,
+            page,
+            page_size: pageSize
+        });
+        const data = readObject(api.data);
+        const pageMeta = readObject(sanitizeJson(data?.meta));
+        const rows = readArray(data?.results);
+        meta = {
+            ...(meta ?? {}),
+            ...(pageMeta ?? {}),
+            pages_fetched: page
+        };
+        sourceRequests.push({
+            source: "recent_changes",
+            request_id: api.requestId,
+            upstream_request_id: api.upstreamRequestId,
+            page,
+            ...apiSourceMetadata(api)
+        });
+        changes.push(...rows
+            .map((change) => sanitizeChange(change, config.webBaseUrl))
+            .filter((change) => stringField(readObject(change.program), "id") === programId));
+        const totalPages = readNumber(pageMeta?.total_pages);
+        if (rows.length === 0 || (totalPages !== undefined && page >= totalPages)) {
+            break;
+        }
+    }
+    return { changes: changes.slice(0, maxChanges), meta, sourceRequests };
 }
 function addProgramResourceLinks(program) {
     const id = stringField(program, "id");
@@ -4136,6 +4337,23 @@ function programFetchError(programId, error) {
         suggested_fix: "Retry the program lookup or verify the BBRadar program id."
     };
 }
+function apiOperationError(operation, error) {
+    if (error instanceof BBRadarApiError) {
+        return stripUndefined({
+            operation,
+            request_id: error.requestId,
+            upstream_request_id: error.upstreamRequestId,
+            status: error.status,
+            message: error.message,
+            detail: sanitizeJson(error.detail),
+            errors: sanitizeJson(error.errors)
+        });
+    }
+    return {
+        operation,
+        message: error instanceof Error ? error.message : String(error)
+    };
+}
 function programSearchText(programId) {
     const colonIndex = programId.indexOf(":");
     const handle = colonIndex >= 0 ? programId.slice(colonIndex + 1) : programId;
@@ -4999,6 +5217,21 @@ function toRateLimitPayload(decision) {
 function rateLimitForTool(toolName, config) {
     return toolName === "export_targets" ? config.exportRateLimitPerMinute : config.defaultRateLimitPerMinute;
 }
+function normalizeStringListInput(value) {
+    if (typeof value === "string") {
+        return splitFilterList(value);
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => (typeof entry === "string" ? splitFilterList(entry) : [entry]));
+    }
+    return value;
+}
+function splitFilterList(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
 function toQuery(values) {
     return compactRecord(values);
 }