USASpending MCP Server

# USASpending MCP Server A Model Context Protocol (MCP) server for researching federal contract awards and analyzing the competitive landscape using the [USASpending.gov API](https://api.usaspending.gov/). Built with Next.js and designed for AI agents to research government contracts, identify incumbents, and analyze market opportunities. ## Features This MCP server provides 8 specialized tools for federal contracting research: - **search_awards** - Search for federal contract awards with filters for agencies, NAICS/PSC codes, keywords, dates, and more - **search_new_awards** - Find newly signed contracts by their award date (action date), excluding modifications - **get_award_details** - Get comprehensive details about a specific award - **search_recipients** - Search for contractors/recipients with autocomplete - **get_recipient_details** - Get detailed information about a specific recipient - **search_idv_awards** - Find task orders under Indefinite Delivery Vehicles (IDVs) - **get_spending_over_time** - Analyze spending trends over time (by fiscal year, quarter, or month) - **analyze_competition** - Analyze competitive landscape showing market shares and top recipients ## Architecture The codebase is organized into a modular structure for maintainability: ``` src/ ├── builders/ │ ├── filter-builder.ts # Centralized filter building logic │ └── field-mapper.ts # Field name mappings and transformers ├── clients/ │ └── usaspending.ts # API client with retry logic ├── tools/ │ ├── search-awards.ts │ ├── search-new-awards.ts │ ├── get-award-details.ts │ ├── search-recipients.ts │ ├── get-recipient-details.ts │ ├── search-idv-awards.ts │ ├── get-spending-over-time.ts │ ├── analyze-competition.ts │ └── index.ts # Tool registration └── types/ ├── award.ts ├── recipient.ts └── tool-params.ts ``` ### Key Design Features - **Centralized Filter Builder**: Shared logic for building API filters across tools - **Field Mapper**: Manages field name differences between API endpoints (verified against actual API) - **Type Safety**: Comprehensive TypeScript types for API requests/responses - **Modular Tools**: Each tool in its own file for easy maintenance - **Error Handling**: Robust retry logic with exponential backoff for rate limiting ## Installation ```bash npm install ``` ## Configuration The server requires no API keys - the USASpending.gov API is public. For production deployment on Vercel, you can optionally configure Redis for SSE transport: ```env KV_REST_API_URL=your-redis-url ``` ## Usage ### Development ```bash npm run dev ``` The MCP server will be available at `http://localhost:3000/mcp` ### Building ```bash npm run build npm start ``` ### Deployment on Vercel Deploy with: ```bash npx vercel --prod ``` The repository is configured with: - 300 second timeout for complex queries - 1024MB memory allocation - SSE transport support (requires Redis) See `vercel.json` for configuration details. ## Tool Reference ### search_awards Search for federal contract awards with transaction activity during a date range. **Important**: Date filtering searches for awards that had ANY transaction activity (modifications, obligations, payments) during the date range - this includes both new awards and existing awards with recent modifications. For finding only newly signed awards, use `search_new_awards` instead. **Parameters:** - `keywords` - Keywords to search in award descriptions - `recipientName` - Contractor/recipient name - `agencyName` - Awarding agency name (e.g., "Department of Veterans Affairs") - `naicsCodes` - Array of NAICS codes (e.g., ["541511"] for Custom Computer Programming) - `pscCodes` - Product Service Codes (e.g., ["D307"] for IT/Telecom) - `activityStartDate` - Start date (YYYY-MM-DD) for transaction activity - `activityEndDate` - End date (YYYY-MM-DD) for transaction activity - `minAmount` / `maxAmount` - Award amount range - `state` - State code for place of performance - `awardTypeCodes` - Award type codes (default: ['A','B','C','D'] for contracts) - `setAsideTypes` - Set aside types (e.g., 'SDVOSBC', '8A', 'WOSB') - `extentCompeted` - Competition codes (e.g., 'A' for full and open) - `contractPricingTypes` - Pricing types (e.g., 'FFPF', 'TM', 'CPFF') - `limit` - Number of results (max 100, default 10) ### search_new_awards Search for newly awarded contracts by their award date (Action Date). Returns only BASE awards (Modification Number = 0), not modifications to existing awards. **Use this when you need to find contracts that were actually signed/awarded during a specific date range** (e.g., "awards signed yesterday", "new contracts this week"). **Parameters:** - `awardStartDate` - Start date (YYYY-MM-DD) - earliest award signing date - `awardEndDate` - End date (YYYY-MM-DD) - defaults to awardStartDate if not provided - All other parameters same as `search_awards` ### get_award_details Get comprehensive details about a specific award including description, recipient, transactions, sub-awards, and more. **Parameters:** - `awardId` - The `generated_unique_award_id` (internalId) from search results **Note**: Use the `internalId` field from search results, NOT the human-readable Award ID (PIID). ### search_recipients Search for contractors/recipients using autocomplete. **Parameters:** - `search` - Search query string - `limit` - Number of results (default 10) ### get_recipient_details Get detailed information about a specific recipient including total awards, transaction history, and more. **Parameters:** - `recipientHash` - The recipient hash ID from search results ### search_idv_awards Find task orders and child awards under an Indefinite Delivery Vehicle (IDV). Useful for understanding who holds a contract vehicle and who is getting task orders. **Parameters:** - `awardId` - The `generated_unique_award_id` (internalId) of the parent IDV - `limit` - Number of results (max 100, default 25) **Background**: IDVs are contract vehicles like GWACs, GSA Schedules, and BPAs that spawn individual task orders. ### get_spending_over_time Analyze spending trends over time for transaction activity. Returns time-series data grouped by fiscal year, quarter, or month. **Parameters:** - All filter parameters from `search_awards` - `group` - How to group data: 'fiscal_year', 'quarter', or 'month' (default: 'fiscal_year') **Note**: Analyzes transaction activity (when money was obligated), not original award dates. ### analyze_competition Analyze the competitive landscape based on transaction activity. Shows who's winning awards/modifications, market shares, and spending patterns. **Parameters:** - `keywords`, `agencyName`, `naicsCodes`, `pscCodes` - Same as search_awards - `activityStartDate` / `activityEndDate` - Date range (defaults to last year) - `minAmount` - Minimum award size to analyze - `limit` - Number of top recipients to show (default 20) **Note**: Analyzes transaction activity, which includes both new awards and modifications to existing awards. ## Understanding Date Fields The USASpending API has different date concepts that are important to understand: - **Action Date** - When a transaction was executed (used by `search_new_awards`) - **Activity Period** - The time period filter for `search_awards` (when any financial activity occurred) - **Period of Performance** - Start/End dates when the contract work is performed (NOT award dates) ## API Client Features The `USASpendingClient` includes: - **Rate Limiting Protection**: Automatic throttling (100ms between requests) - **Retry Logic**: Exponential backoff for 429 rate limit errors (up to 2 retries) - **Error Handling**: Detailed logging and error messages - **Timeouts**: 90 second timeout for complex queries - **Request Delay**: Configurable delay between requests to avoid rate limits ## Verified Field Names The transaction endpoint (`search_new_awards`) uses different field names than the award endpoint. All field names have been verified against the actual API: **Transaction Fields:** - "Award ID", "Recipient Name", "Action Date", "Transaction Amount" - "Awarding Agency", "Awarding Sub Agency" - "Transaction Description", "Mod" (modification number) - "naics_code", "naics_description", "product_or_service_code", "product_or_service_description" ## Development ### Type Checking ```bash npm run type-check ``` ### Formatting ```bash npm run format ``` ### Linting ```bash npm run lint:fix ``` ## Resources - [USASpending API Documentation](https://api.usaspending.gov/docs/endpoints) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Vercel MCP Adapter (mcp-handler)](https://www.npmjs.com/package/mcp-handler) - [Model Context Protocol Specification](https://modelcontextprotocol.io/) ## Notes - The USASpending API can be slow for complex queries (90+ seconds for large result sets) - No API key required - the API is public - The server uses SSE transport when Redis is configured (required for Vercel) - Fluid compute is recommended for efficient execution on Vercel ## License This project is maintained by [Agile Six Applications](https://agile6.com/).