USASpending MCP 服务器
一个用于研究联邦合同授予并分析竞争格局的模型上下文协议（MCP）服务器，利用（此处可接具体工具或方法，但原文未给出，故保持开放） USASpending.gov API该平台基于Next.js构建，专为AI代理设计，用于研究政府合同、识别现有参与者并分析市场机会。
特点/功能
这台MCP服务器为联邦合同研究提供了8种专用工具：
- 搜索奖项 - 搜索联邦合同授予情况，并可按机构、NAICS/PSC代码、关键词、日期等条件进行筛选
- 搜索新奖项 - 根据授予日期（行动日期）查找新签署的合同，不包括修改部分
- 获取奖项详情 - 获取特定奖项的详细信息
- 搜索收件人 - 使用自动补全功能搜索承包商/收件人
- 获取收件人详细信息 - 获取特定收件人的详细信息
- 搜索个人奖项 - 查找无限交付车辆（IDV）下的任务订单
- 获取随时间变化的支出情况 - 分析随时间变化的支出趋势（按财年、季度或月份）
- 分析竞争（情况/对手） - 分析竞争格局，展示市场份额和主要受益者
建筑学
代码库被组织成模块化结构，以提高可维护性：
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关键设计特性
- 集中式过滤器构建器跨工具构建API过滤器的共享逻辑
- “Field Mapper”可以翻译为“实地测绘员”或“现场绘图员”，具体取决于上下文和该术语所指的具体工作内容。在更广泛或技术性的语境中，也可能被翻译为“现场数据映射员”或“实地数据采集与绘图员”，以更准确地描述其职责和工作性质管理API端点之间的字段名称差异（已根据实际API验证）
- 类型安全全面的TypeScript类型，用于API请求/响应
- 模块化工具每个工具分别存放在各自的文件中，便于维护
- 错误处理具有指数退避机制的稳健重试逻辑，用于速率限制
安装
npm install配置
服务器不需要API密钥——USASpending.gov API是公开的。若要在Vercel上进行生产部署，您可以选择配置Redis用于SSE传输：
KV_REST_API_URL=your-redis-url使用方法
发展
npm run devMCP服务器将在 http://localhost:3000/mcp
建筑
npm run build
npm start在Vercel上部署
使用以下方式部署：
npx vercel --prod该存储库已配置为：
- 复杂查询的超时时间为300秒
- 1024MB内存分配
- SSE传输支持（需要Redis）
看 vercel.json 以获取配置详情。
工具参考
搜索奖项
在指定日期范围内搜索具有交易活动的联邦合同授予情况。
重要的日期筛选会查找在指定日期范围内有任何交易活动（修改、义务、支付）的奖项——这包括新签署的奖项和近期有修改的现有奖项。若要仅查找新签署的奖项，请使用 search_new_awards 相反。
参数：
keywords- 在奖项描述中搜索的关键词recipientName- 承包商/受赠人名称agencyName- 授奖机构名称（例如，“退伍军人事务部”）naicsCodes- NAICS代码数组（例如，\["541511"\]表示定制计算机编程）pscCodes- 产品服务代码（例如，IT/电信领域的\["D307"\]）activityStartDate- 交易活动开始日期（YYYY-MM-DD）activityEndDate- 交易活动的结束日期（YYYY-MM-DD）minAmount/maxAmount- 奖金金额范围state- 履约地的国家代码awardTypeCodes- 奖项类型代码（默认：对于合同，为\['A','B','C','D'\]）setAsideTypes- 设立专门类别（例如，“SDVOSBC”、“8A”、“WOSB”）extentCompeted- 竞赛代码（例如，'A'代表公开和全面）contractPricingTypes- 定价类型（例如，“FFPF”、“TM”、“CPFF”）limit- 结果数量（最多100个，默认10个）
搜索新奖项
按授予日期（行动日期）搜索新授予的合同。仅返回基础合同授予（修改编号=0），不包括对现有合同的修改。
当你需要查找在特定日期范围内实际签署/授予的合同时，请使用此功能 （例如，“昨日签署的奖项”，“本周的新合同”）。
参数：
awardStartDate- 开始日期（YYYY-MM-DD）- 最早奖项签署日期awardEndDate- 结束日期（YYYY-MM-DD）- 如未提供，则默认为授予开始日期- 所有其他参数均相同
search_awards
获取奖项详情
获取特定奖项的全面详细信息，包括描述、获奖者、交易记录、子奖项等。
参数：
awardId- 这个（或“那个”、“这些”、“那些”等，根据上下文具体确定）generated_unique_award_id（内部ID）来自搜索结果
注使用 internalId 搜索结果中的字段，而非可读的奖项ID（PIID）。
搜索收件人
使用自动完成功能搜索承包商/收款人。
参数：
search- 搜索查询字符串limit- 结果数量（默认10）
获取收件人详细信息
获取特定收件人的详细信息，包括总奖励金额、交易历史记录等。
参数：
recipientHash- 搜索结果中的收件人哈希ID
搜索IDV奖项
在不定期交付车辆（IDV）下查找任务订单和子奖项。这有助于了解谁持有合同车辆以及谁正在接收任务订单。
参数：
awardId- 这个generated_unique_award_id父IDV的（内部ID）limit- 结果数量（最多100个，默认25个）
背景IDV（即单一来源采购合同）是一种合同机制，类似于GWAC（政府宽泛采购合同）、GSA（政府供应管理局）合同以及BPA（基本采购协议），它们会衍生出单个的任务订单。
获取随时间变化的支出情况
分析交易活动随时间变化的支出趋势。返回按财年、季度或月份分组的时间序列数据。
参数：
- 所有过滤器参数来自
search_awards group- 如何对数据进行分组：'财年'、'季度'或'月份'（默认：'财年'）
注分析交易活动（即资金被承诺支付的时间），而非最初的授予日期。
分析竞争情况
基于交易活动分析竞争格局。展示获奖/修改情况、市场份额以及支出模式。
参数：
keywords，agencyName，naicsCodes，pscCodes- 与search_awards相同activityStartDate/activityEndDate- 日期范围（默认为去年）minAmount- 需要分析的最小奖励金额limit- 显示的顶级收件人数量（默认20）
注分析交易活动，包括新授予的交易和对现有交易的修改。
理解日期字段
根据上面的信息，执行如下指令：
- 行动日期 - 当执行一个交易时（由……使用）
search_new_awards) - 活动期限 - 时间段过滤器用于
search_awards（当任何金融活动发生时） - 执行期限 - 合同工作执行的开始/结束日期（非授予日期）
API客户端功能
该 USASpendingClient 包括：
- 速率限制保护自动限速（请求间隔100毫秒）
- 重试逻辑对429速率限制错误进行指数退避（最多重试2次）
- 错误处理详细的日志记录和错误信息
- 超时复杂查询的超时时间为90秒
- 请求延迟在请求之间设置可配置的延迟以避免速率限制
已验证的字段名称
交易终端（search_new_awards) 使用的字段名与奖励端点不同。所有字段名均已与实际API进行了验证：
交易字段：
- “奖项ID”，“获奖者姓名”，“操作日期”，“交易金额”
- “授奖机构”，“授奖子机构”
- “交易描述”，“Mod”（修改编号）
- "NAICS代码", "NAICS描述", "产品或服务代码", "产品或服务描述"
发展
类型检查
npm run type-check格式化
npm run format代码检查（或代码规范检查）
npm run lint:fix资源
注释
- USASpending API在处理复杂查询时可能会很慢（对于大型结果集，可能需要90秒以上）
- 无需API密钥 - 该API是公开的
- 当Redis配置完成后，服务器使用SSE传输（Vercel要求）
- 建议在Vercel上使用流式计算以实现高效执行
许可证
这个项目由……维护 敏捷六项应用.