usas_search_awards

Instructions

Implementation Reference

• src/usaspending.ts:97-121 (handler)

  The actual implementation of the searchAwards handler. Calls USAspending 'search/spending_by_category/recipient' endpoint with constructed filters and returns top recipients by total $ + count.

  export async function searchAwards(args: {
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
  }) {
    const filters = buildFilters(args);
    type Resp = {
      results?: { name?: string; amount?: number; count?: number }[];
    };
    const json = await postUsas<Resp>(
      "search/spending_by_category/recipient",
      { filters, limit: 10, page: 1 },
    );
    const results = json.results ?? [];
    return {
      totalAwards: results.reduce((s, r) => s + (r.count ?? 0), 0),
      totalValue: results.reduce((s, r) => s + (r.amount ?? 0), 0),
      topRecipients: results.map((r) => ({
        name: r.name ?? "—",
        value: r.amount ?? 0,
        awards: r.count ?? 0,
      })),
    };
  }

• src/server.ts:318-324 (registration)

  Registration of the 'usas_search_awards' tool: defines name, description, and inputSchema (UsasFiltersBase) in the tool list for MCP discovery.

  // ━━━ USAspending — Awards & Recipients (8) ━━━
  {
    name: "usas_search_awards",
    description:
      "Aggregate share-of-wallet on USAspending. Given an agency × NAICS × fiscal year, returns top recipients by total $ + count. Use for competitive landscape ('who wins at VA in 541512?').",
    inputSchema: UsasFiltersBase,
  },

• src/server.ts:74-81 (schema)

  UsasFiltersBase Zod schema: defines optional fields agency, naics, fiscalYear, and setAside used to validate input for usas_search_awards.

  const UsasFiltersBase = z.object({
    agency: z.string().optional().describe("Canonical agency name"),
    naics: z.string().optional(),
    fiscalYear: z.number().int().min(2007).optional(),
    setAside: z
      .enum(["SBA", "8A", "HZS", "SDVOSBC", "WOSB", "EDWOSB", "VSA", "VSS"])
      .optional(),
  });

• src/usaspending.ts:42-67 (helper)

  The buildFilters helper function that constructs the USAspending API filter object from args (agency, naics, fiscalYear, setAside, pscCodes).

  function buildFilters(args: {
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
    pscCodes?: string[];
  }): UsasFilters {
    const filters: UsasFilters = { award_type_codes: ["A", "B", "C", "D"] };
    if (args.agency) {
      filters.agencies = [
        { type: "awarding", tier: "toptier", name: args.agency },
      ];
    }
    if (args.naics) filters.naics_codes = [args.naics];
    if (args.fiscalYear) {
      filters.time_period = [
        {
          start_date: `${args.fiscalYear - 1}-10-01`,
          end_date: `${args.fiscalYear}-09-30`,
        },
      ];
    }
    if (args.setAside) filters.set_aside_type_codes = [args.setAside];
    if (args.pscCodes?.length) filters.psc_codes = args.pscCodes;
    return filters;
  }