关于 usaspending-mcp-server
用于查询 USAspending.gov 联邦奖项、受款方、机构和支出数据的 MCP 服务。它可追踪奖项关联的交易、分包和资金账户,并按地理区域、类别和时间分析支出。
主要功能
- 01搜索联邦奖项
- 02查看奖项交易与分包
- 03追踪奖项至联邦账户
- 04查询受款方与机构资料
- 05按地区和类别分析支出
- 06比较不同时段的支出
适用场景
- 01研究联邦奖项的资金流向
- 02审查受款方或机构支出
- 03比较不同地区或时段的支出
MCP 相关
通过 MCP 工具提供 USAspending.gov 的奖项、受款方、机构、账户和分析数据查询。README 还介绍了可通过 Skills 扩展读取的研究指南技能资源。
配置
远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。
https://usaspending.caseyjhand.com/mcpclaude mcp add --transport http cyanheads-usaspending https://usaspending.caseyjhand.com/mcp{"mcpServers":{"cyanheads-usaspending":{"type":"http","url":"https://usaspending.caseyjhand.com/mcp"}}}在 Cursor 中打开{"servers":{"cyanheads-usaspending":{"type":"http","url":"https://usaspending.caseyjhand.com/mcp"}}}在 VS Code 中打开{"mcpServers":{"cyanheads-usaspending":{"type":"http","url":"https://usaspending.caseyjhand.com/mcp"}}}{"mcpServers":{"cyanheads-usaspending":{"serverUrl":"https://usaspending.caseyjhand.com/mcp"}}}命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
18| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sort | enum | 否 | 排序字段:agency_name(按字母顺序)、budget_authority_amount、obligated_amount 或 outlay_amountagency_name | budget_authority_amount | obligated_amount | outlay_amount |
| order | enum | 否 | 排序方向:asc 或 descasc | desc |
详细介绍
@cyanheads/usaspending-mcp-server
通过 MCP 访问 USAspending.gov 上的美国联邦拨款、受款方、机构及支出分析数据。支持 STDIO 或 Streamable HTTP。
概述
了解联邦资金的流向,数据来自 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_URL | USAspending.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_PORT | HTTP 服务端口。 | 3010 |
MCP_SESSION_MODE | HTTP 会话模式: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.ts | createApp() 入口:注册工具并初始化 USAspending 服务。 |
src/config | 使用 Zod 解析和验证服务专属环境变量。 |
src/mcp-server/tools/definitions | 工具定义(*.tool.ts)以及共享的筛选、日期、分页和格式化辅助函数。 |
src/services/usaspending | USAspending.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。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。