usaspending-mcp 0.1.0

package/dist/tools/search.js

@@ -0,0 +1,230 @@
+/**
+ * Search & Discovery Tools
+ *
+ * The primary search tools for finding and analyzing federal spending data.
+ * These tools use the shared filter schemas from types/filters.ts to provide
+ * flexible, composable search across awards, transactions, and aggregations.
+ */
+import { z } from "zod";
+import { client } from "../api/client.js";
+import { SearchFiltersSchema, PaginationSchema, buildFilters } from "../types/filters.js";
+export function registerSearchTools(server) {
+    // ---------------------------------------------------------------------------
+    // search_awards
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_awards", {
+        title: "Search Awards",
+        description: "Search federal awards (contracts, grants, IDVs, loans) with flexible filters. " +
+            "Supports filtering by agency, recipient, NAICS/PSC codes, date range, award type, " +
+            "keywords, and geography. Returns paginated results. This is the primary search tool " +
+            "for finding federal contracts and awards.",
+        inputSchema: SearchFiltersSchema.merge(PaginationSchema).extend({
+            fields: z
+                .array(z.string())
+                .optional()
+                .default([
+                "Award ID",
+                "Recipient Name",
+                "Award Amount",
+                "Total Outlays",
+                "Description",
+                "Contract Award Type",
+                "Awarding Agency",
+                "Awarding Sub Agency",
+                "Start Date",
+                "End Date",
+                "recipient_id",
+                "prime_award_recipient_id",
+            ])
+                .describe("Fields to include in the response"),
+            subawards: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Whether to search subawards instead of prime awards"),
+        }),
+    }, async (input) => {
+        const { page, limit, sort, order, fields, subawards, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            fields,
+            page,
+            limit,
+            sort: sort ?? "Award Amount",
+            order: order ?? "desc",
+            subawards,
+        };
+        const data = await client.post("/search/spending_by_award/", body);
+        const enriched = client.addSummary(data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(enriched, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_awards_count
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_awards_count", {
+        title: "Search Awards Count",
+        description: "Get counts of awards matching your filters, broken down by award type " +
+            "(contracts, IDVs, grants, direct payments, loans, other). Useful for " +
+            "understanding the scale of results before doing a full search.",
+        inputSchema: SearchFiltersSchema,
+    }, async (filters) => {
+        const body = {
+            filters: buildFilters(filters),
+        };
+        const data = await client.post("/search/spending_by_award_count/", body);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_subawards
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_subawards", {
+        title: "Search Subawards",
+        description: "Search subaward records across all prime awards. Returns subcontractor/sub-grantee " +
+            "details including amounts and recipients.",
+        inputSchema: SearchFiltersSchema.merge(PaginationSchema),
+    }, async (input) => {
+        const { page, limit, sort, order, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            page,
+            limit,
+            sort: sort ?? "subaward_number",
+            order: order ?? "desc",
+        };
+        const data = await client.post("/search/subawards/", body);
+        const enriched = client.addSummary(data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(enriched, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_by_category
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_by_category", {
+        title: "Search by Category",
+        description: "Group and aggregate spending by a dimension: awarding_agency, awarding_subagency, " +
+            "funding_agency, funding_subagency, recipient_name, naics, psc, cfda, county, " +
+            "district, state_territory, country, federal_account. Returns top results ranked by amount.",
+        inputSchema: SearchFiltersSchema.merge(PaginationSchema).extend({
+            category: z
+                .string()
+                .describe("The grouping dimension. One of: awarding_agency, awarding_subagency, " +
+                "funding_agency, funding_subagency, recipient_name, naics, psc, cfda, " +
+                "county, district, state_territory, country, federal_account"),
+        }),
+    }, async (input) => {
+        const { page, limit, sort, order, category, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            category,
+            page,
+            limit,
+        };
+        const data = await client.post(`/search/spending_by_category/${category}/`, body);
+        const enriched = client.addSummary(data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(enriched, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_new_awards_over_time
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_new_awards_over_time", {
+        title: "New Awards Over Time",
+        description: "Track the volume of new awards over time matching your filters. Returns counts " +
+            "grouped by time period. Great for spotting trends in new contract issuance.",
+        inputSchema: SearchFiltersSchema.extend({
+            group: z
+                .enum(["month", "quarter", "fiscal_year"])
+                .describe("Time grouping for results: month, quarter, or fiscal_year"),
+        }),
+    }, async (input) => {
+        const { group, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            group,
+        };
+        const data = await client.post("/search/new_awards_over_time/", body);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_spending_over_time
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_spending_over_time", {
+        title: "Spending Over Time",
+        description: "Track spending amounts over time matching your filters. Returns aggregated " +
+            "amounts grouped by time period.",
+        inputSchema: SearchFiltersSchema.extend({
+            group: z
+                .enum(["month", "quarter", "fiscal_year"])
+                .describe("Time grouping for results: month, quarter, or fiscal_year"),
+        }),
+    }, async (input) => {
+        const { group, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            group,
+        };
+        const data = await client.post("/search/spending_over_time/", body);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_spending_by_geography
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_spending_by_geography", {
+        title: "Spending by Geography",
+        description: "Break down spending geographically. Shows spending by state, county, or " +
+            "congressional district based on either place of performance or recipient location.",
+        inputSchema: SearchFiltersSchema.extend({
+            scope: z
+                .enum(["place_of_performance", "recipient_location"])
+                .describe("Geographic scope: where the work is performed or where the recipient is located"),
+            geo_layer: z
+                .enum(["state", "county", "district"])
+                .describe("Geographic granularity: state, county, or congressional district"),
+        }),
+    }, async (input) => {
+        const { scope, geo_layer, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            scope,
+            geo_layer,
+        };
+        const data = await client.post("/search/spending_by_geography/", body);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // search_by_transaction
+    // ---------------------------------------------------------------------------
+    server.registerTool("search_by_transaction", {
+        title: "Search Transactions",
+        description: "Search at the transaction level across all awards. Returns individual funding " +
+            "actions/modifications. More granular than search_awards.",
+        inputSchema: SearchFiltersSchema.merge(PaginationSchema),
+    }, async (input) => {
+        const { page, limit, sort, order, ...filterParams } = input;
+        const body = {
+            filters: buildFilters(filterParams),
+            page,
+            limit,
+            sort: sort ?? "Transaction Amount",
+            order: order ?? "desc",
+        };
+        const data = await client.post("/search/spending_by_transaction/", body);
+        const enriched = client.addSummary(data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(enriched, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

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

package/dist/types/filters.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared Zod filter schemas for USASpending API search endpoints.
+ *
+ * The USASpending search endpoints accept a common `filters` object.
+ * Each search tool composes the filters it needs by merging/extending
+ * these schemas:
+ *
+ *   SearchFiltersSchema.merge(PaginationSchema).extend({ ... })
+ *
+ * The `buildFilters` helper strips undefined values before sending
+ * to the API.
+ */
+import { z } from "zod";
+export declare const TimePeriodSchema: z.ZodObject<{
+    start_date: z.ZodString;
+    end_date: z.ZodString;
+}, z.core.$strip>;
+export declare const AgencyFilterSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        awarding: "awarding";
+        funding: "funding";
+    }>;
+    tier: z.ZodEnum<{
+        toptier: "toptier";
+        subtier: "subtier";
+    }>;
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const LocationFilterSchema: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodOptional<z.ZodString>;
+    county: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sort: z.ZodOptional<z.ZodString>;
+    order: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>>;
+}, z.core.$strip>;
+export declare const SearchFiltersSchema: z.ZodObject<{
+    time_period: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        start_date: z.ZodString;
+        end_date: z.ZodString;
+    }, z.core.$strip>>>;
+    award_type_codes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            awarding: "awarding";
+            funding: "funding";
+        }>;
+        tier: z.ZodEnum<{
+            toptier: "toptier";
+            subtier: "subtier";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    recipient_search_text: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipient_id: z.ZodOptional<z.ZodString>;
+    naics_codes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    psc_codes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    place_of_performance_locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        country: z.ZodString;
+        state: z.ZodOptional<z.ZodString>;
+        county: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    recipient_locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        country: z.ZodString;
+        state: z.ZodOptional<z.ZodString>;
+        county: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type TimePeriod = z.infer<typeof TimePeriodSchema>;
+export type AgencyFilter = z.infer<typeof AgencyFilterSchema>;
+export type LocationFilter = z.infer<typeof LocationFilterSchema>;
+export type Pagination = z.infer<typeof PaginationSchema>;
+export type SearchFilters = z.infer<typeof SearchFiltersSchema>;
+/**
+ * Takes a parsed SearchFilters object and returns a clean record with
+ * only the defined keys. This is the object you pass as `filters` in
+ * the POST body to USASpending search endpoints.
+ */
+export declare function buildFilters(filters: z.infer<typeof SearchFiltersSchema>): Record<string, unknown>;
+//# sourceMappingURL=filters.d.ts.map

package/dist/types/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/types/filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,gBAAgB;;;iBAO3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAU7B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;iBAY/B,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;iBAyB3B,CAAC;AAMH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2D9B,CAAC;AAMH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,GAC3C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB"}

package/dist/types/filters.js

@@ -0,0 +1,150 @@
+/**
+ * Shared Zod filter schemas for USASpending API search endpoints.
+ *
+ * The USASpending search endpoints accept a common `filters` object.
+ * Each search tool composes the filters it needs by merging/extending
+ * these schemas:
+ *
+ *   SearchFiltersSchema.merge(PaginationSchema).extend({ ... })
+ *
+ * The `buildFilters` helper strips undefined values before sending
+ * to the API.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Primitive filter schemas
+// ---------------------------------------------------------------------------
+export const TimePeriodSchema = z.object({
+    start_date: z
+        .string()
+        .describe("Start date in YYYY-MM-DD format (e.g. '2024-10-01' for FY2025 start)"),
+    end_date: z
+        .string()
+        .describe("End date in YYYY-MM-DD format (e.g. '2025-09-30' for FY2025 end)"),
+});
+export const AgencyFilterSchema = z.object({
+    type: z
+        .enum(["awarding", "funding"])
+        .describe("Agency role: 'awarding' (who issued the award) or 'funding' (who provided the money)"),
+    tier: z
+        .enum(["toptier", "subtier"])
+        .describe("Agency tier: 'toptier' (e.g. Department of Defense) or 'subtier' (e.g. Army)"),
+    name: z
+        .string()
+        .describe("Agency name as it appears in USASpending (e.g. 'Department of Defense')"),
+});
+export const LocationFilterSchema = z.object({
+    country: z
+        .string()
+        .describe("Country code (e.g. 'USA', 'GBR')"),
+    state: z
+        .string()
+        .optional()
+        .describe("State FIPS code or abbreviation (e.g. 'VA', '51')"),
+    county: z
+        .string()
+        .optional()
+        .describe("County FIPS code (e.g. '059' for Fairfax County, VA)"),
+});
+// ---------------------------------------------------------------------------
+// Pagination schema
+// ---------------------------------------------------------------------------
+export const PaginationSchema = z.object({
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(1)
+        .describe("Page number (starts at 1)"),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .default(20)
+        .describe("Results per page (max 100)"),
+    sort: z
+        .string()
+        .optional()
+        .describe("Field name to sort by (varies by endpoint)"),
+    order: z
+        .enum(["asc", "desc"])
+        .optional()
+        .default("desc")
+        .describe("Sort order: 'asc' (ascending) or 'desc' (descending, default)"),
+});
+// ---------------------------------------------------------------------------
+// Main search filters schema
+// ---------------------------------------------------------------------------
+export const SearchFiltersSchema = z.object({
+    time_period: z
+        .array(TimePeriodSchema)
+        .optional()
+        .describe("Date range filters. Each entry narrows results to awards active within that range. " +
+        "Fiscal years run Oct 1 - Sep 30 (e.g. FY2025 = 2024-10-01 to 2025-09-30)."),
+    award_type_codes: z
+        .array(z.string())
+        .optional()
+        .describe("Award type codes to filter by. Common codes: " +
+        "Contracts: 'A' (BPA Call), 'B' (Purchase Order), 'C' (Delivery Order), 'D' (Definitive Contract). " +
+        "IDVs: 'IDV_A' (GWAC), 'IDV_B' (IDC), 'IDV_B_A' (IDC/IDIQ), 'IDV_B_B' (IDC/Multiple Award Schedule), " +
+        "'IDV_B_C' (IDC/BOA), 'IDV_C' (FSS), 'IDV_D' (BPA), 'IDV_E' (BOA). " +
+        "Grants: '02' (Block Grant), '03' (Formula Grant), '04' (Project Grant), '05' (Cooperative Agreement). " +
+        "Loans: '07' (Direct Loan), '08' (Guaranteed/Insured Loan). " +
+        "Direct Payments: '06' (Direct Payment for Specified Use), '10' (Direct Payment with Unrestricted Use). " +
+        "Other: '09' (Insurance), '11' (Other Financial Assistance)."),
+    agencies: z
+        .array(AgencyFilterSchema)
+        .optional()
+        .describe("Filter by awarding or funding agencies"),
+    recipient_search_text: z
+        .array(z.string())
+        .optional()
+        .describe("Search for recipients by name (e.g. ['Lockheed Martin', 'Raytheon'])"),
+    recipient_id: z
+        .string()
+        .optional()
+        .describe("Filter to a specific recipient by their hash ID (from autocomplete_recipient or search results)"),
+    naics_codes: z
+        .array(z.string())
+        .optional()
+        .describe("NAICS industry codes to filter by (e.g. ['541512'] for Computer Systems Design, " +
+        "['541511'] for Custom Programming). Use search_naics to find codes."),
+    psc_codes: z
+        .array(z.string())
+        .optional()
+        .describe("Product/Service Classification codes to filter by (e.g. ['D306'] for IT and Telecom - " +
+        "Systems Development). Use search_psc to find codes."),
+    place_of_performance_locations: z
+        .array(LocationFilterSchema)
+        .optional()
+        .describe("Filter by where the work is performed (geographic location)"),
+    recipient_locations: z
+        .array(LocationFilterSchema)
+        .optional()
+        .describe("Filter by where the recipient is located (geographic location)"),
+    keywords: z
+        .array(z.string())
+        .optional()
+        .describe("Full-text keyword search across award descriptions (e.g. ['cybersecurity', 'cloud migration'])"),
+});
+// ---------------------------------------------------------------------------
+// Helper: strip undefined values from a filters object
+// ---------------------------------------------------------------------------
+/**
+ * Takes a parsed SearchFilters object and returns a clean record with
+ * only the defined keys. This is the object you pass as `filters` in
+ * the POST body to USASpending search endpoints.
+ */
+export function buildFilters(filters) {
+    const result = {};
+    for (const [key, value] of Object.entries(filters)) {
+        if (value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=filters.js.map

package/dist/types/filters.js.map

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "usaspending-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the USASpending.gov API - federal spending intelligence",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "usaspending-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --transport http --port 3001",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "usaspending",
+    "federal-spending",
+    "government-contracts",
+    "model-context-protocol"
+  ],
+  "author": "Joe Bucci",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boejucci/usa-spending-mcp.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "express": "^5.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.0",
+    "typescript": "^5.9.3"
+  }
+}