mcpField
U
usaspending-mcp-server

usaspending-mcp-server

远程服务
github.com/cyanheads法律与政务52 天前更新
代码仓库

关于 usaspending-mcp-server

用于查询 USAspending.gov 联邦奖项、受款方、机构和支出数据的 MCP 服务。它可追踪奖项关联的交易、分包和资金账户,并按地理区域、类别和时间分析支出。

主要功能

  1. 01搜索联邦奖项
  2. 02查看奖项交易与分包
  3. 03追踪奖项至联邦账户
  4. 04查询受款方与机构资料
  5. 05按地区和类别分析支出
  6. 06比较不同时段的支出

适用场景

  1. 01研究联邦奖项的资金流向
  2. 02审查受款方或机构支出
  3. 03比较不同地区或时段的支出

MCP 相关

通过 MCP 工具提供 USAspending.gov 的奖项、受款方、机构、账户和分析数据查询。README 还介绍了可通过 Skills 扩展读取的研究指南技能资源。

配置

远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。

服务地址https://usaspending.caseyjhand.com/mcp
一键复制安装命令
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。

安装包
npm@cyanheads/usaspending-mcp-server0.7.0

工具

18
参数类型必填说明
sortenum否排序字段:agency_name(按字母顺序)、budget_authority_amount、obligated_amount 或 outlay_amountagency_name | budget_authority_amount | obligated_amount | outlay_amount
orderenum否排序方向:asc 或 descasc | desc

详细介绍

@cyanheads/usaspending-mcp-server

通过 MCP 访问 USAspending.gov 上的美国联邦拨款、受款方、机构及支出分析数据。支持 STDIO 或 Streamable HTTP。

18 个工具

版本 许可证 Docker MCP SDK npm TypeScript Bun

在 Claude Desktop 中安装 在 Cursor 中安装 在 VS Code 中安装

框架


概述

了解联邦资金的流向,数据来自 USAspending.gov,涵盖拨款、受款方、机构和支出。搜索并追踪拨款,深入查看交易、次级拨款和资金账户;查看受款方和机构的概况;并按地理区域、类别、时间和灾害拨款汇总支出。

工具
工具描述
usaspending_list_agencies列出顶级联邦机构及其代码、标识符和预算总额,并标注报告年份和季度
usaspending_autocomplete_filters根据自由文本描述查找 NAICS、PSC、CFDA、机构或受款方代码
usaspending_search_awards按关键词、受款方、机构、授标类型、NAICS 代码、援助项目、PSC、DEF 代码、地点或日期范围搜索授标
usaspending_get_award获取单项授标的完整记录:金额、受款方、机构、代码、上级 IDV、DEF 代码资金
usaspending_get_award_transactions列出某项授标的交易(修改、修订)
usaspending_get_award_subawards列出某项主要授标下的分包合同或转拨补助
usaspending_get_award_federal_accounts列出为某项授标提供资金的财政部联邦账户及各账户的出资金额
usaspending_get_idv_awards列出某个 IDV 下发出的子订单和子 IDV
usaspending_search_recipients按名称、UEI 或 DUNS 搜索受款方
usaspending_get_recipient获取受款方档案:地址、企业类型、母公司和授标总额
usaspending_get_agency获取机构的使命、最新年份的预算总额、下属机构和 DEF 代码
usaspending_spending_by_geography按州、县或国会选区汇总支出
usaspending_spending_by_category按 NAICS、PSC、机构、CFDA 项目或受款方汇总支出
usaspending_spending_over_time按财政年度、季度或月份汇总支出
usaspending_disaster_spending按机构、项目、受款方或地理位置分解灾害和紧急补充拨款支出
usaspending_search_federal_accounts按标题关键词或机构标识符搜索联邦账户
usaspending_get_federal_account获取联邦账户的预算总额及其财政部账户符号组成项
usaspending_get_federal_account_breakdown按项目活动或对象类别分解联邦账户的义务金额
研究指南

usaspending-guide 涵盖受款方研究、授标至账户的资金追踪,以及跨时期和紧急拨款的支出比较。插件安装后可在 skills/ 中找到该指南;MCP 客户端可通过 Skills 扩展读取 skill://usaspending-guide/SKILL.md。没有领域数据资源。

能力参考

usaspending_list_agencies tool
  • 接受 sort(agency_name、budget_authority_amount、obligated_amount、outlay_amount)和 order;除非提供可选的正数 limit,否则返回所有机构。提供 limit 时,page 默认为 1;未提供时,忽略 page。total 始终统计目录中的全部机构,只有分页时才会出现 has_next
  • 每行包含 toptier_code 和 agency_slug,两者均可用于 usaspending_get_agency,还包含最新报告期的 budget_authority_amount、obligated_amount 和 outlay_amount。存在时,fiscal_year 和 fiscal_quarter 保留提供方的报告标签

usaspending_autocomplete_filters 工具
  • type(naics、psc、cfda、awarding_agency、recipient)加上 search_text;limit 为 1–500,默认值为 10
  • 行包含 code 和 name;收款方还包含 uei / duns;无匹配项时返回 no_match。cfda 代码应填入 usaspending_search_awards 和三个支出分析工具的 assistance_listings,psc 代码则应填入 psc_codes
  • 机构行包含匹配机构自身的 name、abbreviation 和 tier(toptier 或 subtier)、其上级机构的 toptier_name 和 toptier_code,以及(如有)subtier_code。在奖项搜索或支出分析中,将 name 传给 agency_name 可匹配该机构;传入 toptier_name 可匹配整个部门。机构结果会在同一个 limit 下先列出顶层匹配项,再列出次级匹配项;不包含办公室匹配项
  • naics 会匹配 NAICS 官方标题文本:"software" 可以匹配,而 "cybersecurity" 不行,因此请使用标题中采用的行业术语进行搜索

usaspending_search_awards 工具
  • 筛选条件:keyword、agency_name、recipient_name、naics_codes、assistance_listings(援助清单编号,例如 93.866,来自 usaspending_autocomplete_filters 的 type: cfda)、psc_codes(1–4 个字符,前缀如 Y1 可涵盖其下的代码;仅适用于合同和 IDV)、def_codes(灾害应急基金代码,例如 Z;PSC 和 DEF 代码会转换为大写)、time_period(自 2007-10-01 起的 YYYY-MM-DD;可只提供任一端日期),以及 location_filter(country 默认为 USA,领地代码如 PRI 会转换为 USA 加上其州;state 可使用邮政缩写或 2 位 FIPS 代码,也包括 FM/MH/PW/UM 和武装部队代码 AA/AE/AP;若为其他国家,则使用该国自身的 2 位行政区划代码,例如 CAN 下的 ON;county 可使用与 state 一起提供的 3 位代码,或单独提供 5 位 FIPS 代码;结果会在 applied_location 中回显);award_type_codes 默认为合同(A–D),且必须属于同一组:IDV 为 IDV_A–IDV_E,拨款为 02–05/F001/F002,直接付款为 06/10/F006/F007,贷款为 07/08/F003/F004,其他援助为 09/11/-1/F005/F008/F009/F010;limit 最大为 100
  • 行包含供 usaspending_get_award 使用的 generated_internal_id,以及供 usaspending_get_agency 使用的 agency_slug;贷款行会返回 loan_value、subsidy_cost 和 issued_date,而非金额和日期。结果不含总数;每页返回满额时,page_metadata.has_next 为 true。嵌套的 filters 对象接受分析工具的 filters 键,但不包括 recipient_id,且同一字段下优先于扁平字段。错误包括 assistance_listings_type_mismatch(援助清单与非援助类别一起使用)、psc_codes_type_mismatch(PSC 代码与援助类别一起使用)、unsupported_sort、date_range_inverted、date_before_earliest 和 invalid_location(未知州、未提供州的 3 位县代码、武装部队代码下的县(AA/AE/AP)、其他国家下的县或 FIPS 数字州代码,或指向不同州的地点字段)
  • sort 选项取决于类别:贷款支持 Loan Value(默认值)、Subsidy Cost、Issued Date、Recipient Name 或 Awarding Agency;其他类别支持 Award Amount(默认值)、Total Outlays、Start Date、End Date(IDV 除外)、Recipient Name 或 Awarding Agency。页码查询最多到结果偏移量 50,000(pagination_limit_exceeded);超过后,请使用 last_record_sort_value + last_record_unique_id 游标分页,该游标会在结果偏移量低于 10,000 时返回
usaspending_get_award 工具
  • award_id 是 generated_unique_award_id,即搜索结果中的 generated_internal_id;未知 ID 会返回 award_not_found
  • 返回 category、total_obligation、total_outlays、total_account_obligation、total_account_outlay、base_exercised_options、subaward_count、NAICS / PSC 代码、account_obligations_by_defc、account_outlays_by_defc;对于贷款,在有提供时还会返回 total_loan_value 和 total_subsidy_cost
  • 对于援助类 award,assistance_listings 按上游顺序列出每个 Assistance Listing,包含 number、title 和 obligation;number 可用于 usaspending_search_awards 的 assistance_listings
  • recipient 包含 uei、parent_uei、business_categories(类别名称,而非 usaspending_get_recipient 中的 business_types 代码),以及其 location 中的三字母 country_code、county_name、congressional_code 和 zip5。place_of_performance 也包含国家代码、县名和国会选区代码;若上游未提供位置字段,则会省略该位置
  • recipient.recipient_id 和 recipient.parent_recipient_id 可关联到 usaspending_get_recipient,parent_award.generated_unique_award_id 可关联到父级 IDV;category: "idv" awards 会通过 usaspending_get_idv_awards 列出其子级

usaspending_get_award_transactions 工具
  • award_id,以及 sort(action_date、federal_action_obligation、modification_number);limit 最大为 100
  • 行包含字符串 id(ASST_TX 或 CONT_TX)、action_date、modification_number、action_type 和带正负号的 federal_action_obligation(负数表示撤销义务)。贷款交易还包含 face_value_loan_guarantee 和 original_loan_subsidy_cost;援助交易在有提供时包含 cfda_number

usaspending_get_award_subawards 工具
  • award_id,以及 sort(subaward_number、description、action_date、amount、recipient_name);limit 最大为 100
  • 行包含 id、subaward_number、description、amount、action_date 和 recipient_name;上游列表不提供 recipient UEI 或位置。usaspending_get_award 中的 subaward_count 表示是否存在子 award

usaspending_get_award_federal_accounts 工具
  • award_id 是 generated_unique_award_id;limit 最大为 100,page_metadata.count 为总数
  • 行包含可用于 usaspending_get_federal_account 的 federal_account(AGENCY-MAIN,例如 080-0120)、total_transaction_obligated_amount,以及带有 funding_agency_slug 的资助机构

usaspending_get_idv_awards 工具
  • 父级 IDV 的 award_id;type 为 child_awards(任务订单和交付订单,默认值)、child_idvs 或 grandchild_awards;limit 最大为 100
  • 行包含可用于 usaspending_get_award 的 generated_unique_award_id、obligated_amount 和履约日期;没有总数,且在页面已满时 has_next 为 true

usaspending_search_recipients 工具
  • keyword 匹配名称、UEI 或 DUNS,也包括部分匹配;会去除两端空白,空文本表示不应用关键词筛选,并会显示提示。可选的 award_type 仍会限定总额;limit 最大为 100
  • 行包含可用于 usaspending_get_recipient 的 id(哈希值后缀为 -P 表示父级、-C 表示子级或 -R 表示独立实体),以及 uei、duns、recipient_level 和 amount;page_metadata.total 为完整匹配数
usaspending_get_recipient 工具
  • usaspending_search_recipients 或 usaspending_get_award 返回的 recipient_id;可选的 fiscal_year(2001–2030)可将总额限定到该财年,否则总额涵盖过去 12 个月;未知 ID 会报错 recipient_not_found
  • 返回地址、business_types、parent_name / parent_uei、alternate_names、total_transaction_amount、total_transactions 和贷款面值总额,其中 period 用于标明时间窗口(FY2020 或 trailing 12 months)。总额涵盖所有奖励类型;如需按类型查看总额,请使用 usaspending_spending_over_time,并设置 filters.recipient_id 和 award_type_codes

usaspending_get_agency 工具
  • 提供 toptier_code(例如 097)或 agency_slug(例如 department-of-defense)之一;page 每次遍历 10 个子机构。可能的错误包括 missing_input、conflicting_input(同时提供了两个标识符)和 agency_not_found
  • 返回 mission,以及最近一个有预算数据的 fiscal_year 对应的 budgetary_resources_amount、obligated_amount 和 outlay_amount(新开启但尚无金额的财年会被跳过);还会返回 sub_agencies,其中包含同一财年的义务金额、交易数和新奖励数(sub_agency_fiscal_year 标明该财年;如果 5 秒内未能获取预算年份,则明细涵盖当前财年),以及 def_codes
  • 即使预算或子机构请求失败,仍会返回概览:缺失字段将被省略,unavailable_sections 会列出各个部分及其 reason(api_unavailable、api_timeout 或 upstream_error),并说明重试是否可能成功加载该部分

usaspending_spending_by_geography 工具
  • 必须提供 scope(place_of_performance、recipient_location)和 geo_layer(state、county、district);filters 可包含 keywords、award_type_codes、agency_name、recipient_id、naics_codes、assistance_listings、psc_codes、def_codes(与 usaspending_search_awards 的代码筛选器相同,回显为 applied_*),以及 time_period_start / time_period_end(格式为 YYYY-MM-DD;仅提供其中一项时会自动补全另一项,与 usaspending_search_awards 相同;applied_time_period_* 会回显所传范围;开始日期晚于结束日期会报错 date_range_inverted,开始日期早于 2007-10-01 会报错 date_before_earliest);limit 范围为 1–500,默认为 50
  • 奖励类型可以混合使用。如果指定的类型全部为合同或 IDV,则 assistance_listings 会报错 assistance_listings_type_mismatch;如果全部为援助,则 psc_codes 会报错 psc_codes_type_mismatch。按代码筛选的金额涵盖符合条件的完整奖励,按 DEF 筛选的总额可能为负数
  • 每行包含 shape_code、display_name、aggregated_amount、population 和 per_capita,并按金额排序;total_areas_available 统计数量上限生效前的所有匹配区域
  • shape_codes(1–500)仅返回列出的区域,格式为对应地理图层的 shape_code:state 使用邮政编码(NY),county 使用 5 位州 + 县 FIPS(36117),district 使用 4 位州 FIPS + 选区编号(3623)。筛选会遍历所有匹配区域,因此可以返回排序位置超过 limit 的区域;这些代码会回显为 applied_shape_codes,未匹配到任何区域的代码会列在 notice 中
  • 未设置筛选器时,会汇总所有奖励类型,并通过 applied_award_type_default 说明这一点;subawards: true 会切换为子奖励数据

usaspending_spending_by_category 工具
  • category 可为 naics、psc、awarding_agency、awarding_subagency、funding_agency、funding_subagency、cfda 或 recipient_duns;接受与 usaspending_spending_by_geography 相同的 filters 对象;limit 最高为 100
  • 每行包含 id、code、name 和 amount,并按义务金额排序;recipient_duns 行会将 DUNS 作为 code 返回,并在上游数据提供时附带 recipient_id 和 uei;recipient_id 可用于调用 usaspending_get_recipient
usaspending_spending_over_time 工具
  • group 为 fiscal_year、quarter 或 month(财政月份,其中 1 表示 10 月);使用相同的 filters 对象,award_type_codes 默认为合同,因此 assistance_listings 需要指定一个援助组;subawards: true 切换为子奖励数据
  • 行包含 time_period、aggregated_amount,以及按类型划分的 contracts、grants、direct_payments、idvs、loans 和 other

usaspending_disaster_spending 工具
  • dimension 为 overview、agency、cfda、recipient 或 geography;filters.def_codes 对 overview 为可选,对其他维度则必填(缺失或为空时返回 missing_def_codes)。["L", "M", "N", "O", "P"] 等代码可筛选出 COVID-19 资金,并会作为 applied_def_codes 回显。除 overview 外,各维度的 limit 最高为 100;spending_type(award 为默认值,或 total)仅适用于 agency,geography 则使用 filters.geo_layer(state、county)
  • 行包含 obligation、outlay 和 award_count;当 spending_type: total 时,agency 行还包含 total_budgetary_resources;overview 返回总额和 funding_by_def_code。收款方行的 id 可用于调用 usaspending_get_recipient。收款方的 filters.query 可按搜索文本缩小范围;该文本会经过去除首尾空格处理,并作为 applied_query 回显;空白内容不会应用查询。收款方总数达到 10,000 表示已触及可达上限,也是可能匹配数量的下限,此时会标记 truncated;使用 filters.query 可进一步查找剩余结果。地理区域按 aggregated_amount 排序,并通过 limit 和 page 分页;total 为区域总数。若当前页之后还有区域,则标记 truncated;truncationCeiling 为当前页显示的最低金额。没有记录履约地点的支出会作为一个未归属区域参与排序
  • Agency、cfda 和 recipient 还会返回涵盖所有匹配行的 totals:obligation、outlay,以及 total_budgetary_resources(agency 且 total 时)或 award_count。即使提供了代码,overview 仍可能超时:可缩小 filters.def_codes 范围、稍后重试,或使用 spending_type: total 的 agency 明细查询义务额、支出额和预算资源
  • 两种输出形式都会保留上游消息、被忽略的筛选条件、上限说明和空页恢复提示。在 recipient 以外的维度中,query 会被忽略;在 geography 以外的维度中,geo_layer 会被忽略;overview 中的 award_type_codes 也会被忽略。若空页的偏移量达到一个正数 total,则会提示调用方在筛选条件不变的情况下查看更早的页面;若为空页位于结果中间,则会报告总数,但不会声称结果已耗尽;若 total 缺失,则总数仍为未知

usaspending_search_federal_accounts 工具
  • 可选参数 keyword 和 3 位数的 agency_identifier;sort_field 可为 account_name、account_number、budgetary_resources(默认值)或 managing_agency;limit 最高为 100
  • 行包含 account_number(例如 097-8097),供联邦账户工具使用;还包含 managing_agency 和 budgetary_resources;page_metadata.count 为总数。可选参数 fiscal_year 用于选择报告年份;否则使用提供方最新的提交年份。返回的 fiscal_year 标识该期间

usaspending_get_federal_account 工具
  • account_code 使用 AGENCY-MAIN 格式,可从搜索结果的 account_number 或某项奖励中的 federal_account 获取;未知代码会返回 account_not_found
  • 可选参数 fiscal_year 用于选择报告年份;否则使用提供方当前的联邦财政年度。返回所选 fiscal_year 的 total_obligated_amount、total_gross_outlay_amount 和 total_budgetary_resources,以及 children:每个条目对应一个 Treasury Account Symbol,并包含其各自的金额。若某年份没有财务数据,则保留账户元数据并附带提示,不会改用其他年份的数据

usaspending_get_federal_account_breakdown 工具
  • 使用 account_code 和 dimension(program_activity 或 object_class);limit 最高为 100,page_metadata.total 表示行数
  • 每行包含 code、name 和 obligations;program_activity 行还包含 type,值为 PAC/PAN 或 PARK
  • 可选的 fiscal_year 用于限定财务报告期(10 月 1 日至 9 月 30 日),并会显示在 time_period 和 period 中。省略时涵盖所有可用期间

所有三个联邦账户工具都接受 2001 年至当前联邦财政年度(每年 10 月 1 日切换)之间的整数 fiscal_year;表单值留空表示省略。搜索结果和详情中的预算总额使用不同的上游计算方式,即使年份相同,也不一定一致。

功能

基于 @cyanheads/mcp-ts-core 构建:支持 stdio 和 Streamable HTTP 传输、可插拔身份验证(none / jwt / oauth)、可切换存储(in-memory、filesystem、Supabase、Cloudflare KV/R2/D1),以及带可选 OpenTelemetry 跟踪的结构化日志记录。

USAspending 专属功能:

  • 使用 USAspending.gov API v2,无需密钥:根据 DATA Act,数据为公开数据
  • 奖项搜索和支出分析工具涵盖 2007-10-01 及之后的操作日期(更早的开始日期会导致 date_before_earliest),且 DoD 合同数据的发布会延迟 90 天
  • usaspending_spending_by_category 将八个类别子路由整合在一个 category 枚举下;usaspending_disaster_spending 将五个灾害端点整合在一个 dimension 下
  • 每个请求都在一个墙钟时间预算内运行(默认 45 秒);慢速响应会用尽全部预算进行一次尝试,只有快速失败才会重试。失败时会返回 api_timeout 或 api_unavailable,并附上各工具的恢复提示;被拒绝的请求会在错误消息中包含 USAspending 自身的说明

便于 Agent 使用的输出:

  • 将 ID 作为显式字段串联:generated_internal_id、agency_slug、recipient.recipient_id、federal_account 和 account_number,以便 Agent 无需解析显示字符串即可追踪资金流向
  • 真实反映分页情况:每个列表都提供 page_metadata.has_next;上游有提供时会包含 total 或 count;只有确认返回结果之外还有行时才会包含 truncated / shown / cap。若整页已满但没有此类证据,则只保留 has_next,不声称结果已截断
  • 空结果会显示提示,而不是错误:账户资金、账户细分和收款方搜索会区分已知总数为零与超过总数的空白页面;后一种情况会引导调用方使用相同筛选条件查询更早的页面。若没有总数,提示仅描述当前页面;奖项搜索不会提供总数。按 ID 查询的列表工具(交易、子奖项、资金账户、IDV 子级、账户细分)遇到未知 ID 时会返回空列表,而不是失败
  • 提供带恢复提示的类型化错误:award_not_found、recipient_not_found、agency_not_found、account_not_found、no_match、conflicting_input、date_before_earliest、date_range_inverted、unsupported_sort、assistance_listings_type_mismatch、psc_codes_type_mismatch、invalid_location、pagination_limit_exceeded、incomplete_cursor、missing_def_codes

开始使用

连接到托管实例,无需安装:

claude mcp add --transport http usaspending-mcp-server https://usaspending.caseyjhand.com/mcp

或在本地运行:

claude mcp add usaspending-mcp-server -- npx -y @cyanheads/usaspending-mcp-server

对于其他客户端,请将以下内容添加到 MCP 配置文件中:

{
  "mcpServers": {
    "usaspending-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/usaspending-mcp-server"]
    }
  }
}

无需 API 密钥或账户。有关 Docker 或从源代码构建的信息,请参阅运行服务。

配置

无需设置任何变量;默认值开箱即用。

变量描述默认值
USASPENDING_BASE_URLUSAspending.gov API v2 基础 URL。https://api.usaspending.gov/api/v2/
USASPENDING_TIMEOUT_MS每次尝试的 HTTP 超时时间,单位为 ms(1000–120000)。每次尝试会在达到此时间或请求预算剩余时间(以较短者为准)时终止;超时的尝试不会重试。45000
USASPENDING_RETRY_BUDGET_MS单个请求的总耗时预算,包含所有尝试和退避时间,单位为 ms(1000–300000)。503 等快速失败会在此预算内重试。45000,如果 USASPENDING_TIMEOUT_MS 更高则使用其值
MCP_TRANSPORT_TYPE传输方式:stdio 或 http。stdio
MCP_HTTP_PORTHTTP 服务端口。3010
MCP_SESSION_MODEHTTP 会话模式:stateless、stateful 或 auto。stateless
MCP_AUTH_MODE身份验证方式:none、jwt 或 oauth。none
MCP_LOG_LEVEL日志级别(debug、info、warning、error 等)。info
LOG_TOOL_FAILURE_PAYLOADS记录每次失败的工具调用参数和结果,按键名脱敏,并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节以内(默认 16384)。自由格式值中的密钥不会被脱敏。false
LOGS_DIR日志文件目录(仅 Node.js)。<project-root>/logs
STORAGE_PROVIDER_TYPE存储后端:in-memory、filesystem、supabase、cloudflare-kv/r2/d1。in-memory
OTEL_ENABLED启用 OpenTelemetry。false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT可选的 OTLP 日志导出端点;基础端点 OTEL_EXPORTER_OTLP_ENDPOINT 不会启用此功能。—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本(或 Node.js v24+)。无需 API 密钥或账号。

git clone https://github.com/cyanheads/usaspending-mcp-server.git
cd usaspending-mcp-server && bun install
cp .env.example .env # optional overrides
  • 构建并运行:

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    
  • 运行检查和测试:

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/usaspending-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式,并将日志写入 /var/log/usaspending-mcp-server。如需使用 stdio,请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/usaspending-mcp-server:latest"]。使用 docker build -t usaspending-mcp-server . 在本地构建;默认会安装 OpenTelemetry 对等依赖项——使用 --build-arg OTEL_ENABLED=false 构建可省略这些依赖项。

项目结构

目录用途
src/index.tscreateApp() 入口:注册工具并初始化 USAspending 服务。
src/config使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools/definitions工具定义(*.tool.ts)以及共享的筛选、日期、分页和格式化辅助函数。
src/services/usaspendingUSAspending.gov API 客户端:请求超时、重试预算、原始响应类型。
tests/针对工具、服务、配置和脚本的单元测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明:

  • 处理程序抛出异常,框架负责捕获——工具逻辑中不要使用 try/catch
  • 使用 ctx.log 记录请求范围的日志,使用 ctx.state 存储租户范围的数据
  • 通过 src/mcp-server/tools/definitions/index.ts 中的 barrel 注册新工具
  • 封装外部 API 调用:验证原始数据 → 规范化为领域类型 → 返回输出模式;绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试:

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。