usaspending-mcp-server

---

概要

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 _ツール

• sort（agency_name、budget_authority_amount、obligated_amount、outlay_amount）と order を受け取ります。オプションの正の値の limit が指定されていない場合、すべての機関を返します。limit を指定した場合、page の既定値は 1 です。指定しない場合、page は無視されます。total は常にディレクトリ全体の件数を示し、ページ分割時にのみ has_next が表示されます
• 各行には、usaspending_get_agency が受け付ける toptier_code と agency_slug に加え、最新の報告期間における 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コードはassistance_listingsに、pscコードはusaspending_search_awardsおよび3つの支出分析ツールの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（usaspending_autocomplete_filtersのtype: cfdaで取得できる93.866などの支援リスティング番号）、psc_codes（1～4文字。Y1などのプレフィックスは、その配下のコードに一致します。契約とIDVのみ）、def_codes（Zなどの災害緊急基金コード。PSCコードとDEFコードは大文字に変換して送信されます）、time_period（YYYY-MM-DD形式で、開始日は2007-10-01以降。開始日または終了日の片方だけでも指定できます）、location_filter（countryはデフォルトでUSA。PRIなどの地域コードはUSAとその州に置き換えられます。stateには郵便番号または2桁のFIPSコードを指定でき、FM／MH／PW／UMおよび軍関係のAA／AE／APも指定できます。別の国の下では、CANのONなど、その国固有の2文字の地域コードを指定します。countyには、stateと併せて3桁のコード、または5桁のFIPSコードだけを指定できます。適用された値はapplied_locationとして返されます）。award_type_codesはデフォルトで契約（A～D）です。次のいずれか1つのグループ内のコードを指定してください：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）、それ以降は、10,000件未満の結果オフセットまでに返されたlast_record_sort_valueとlast_record_unique_idのカーソルを使ってページングしてください

usaspending_get_award _ツール

• award_id は検索結果の generated_internal_id である generated_unique_award_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 も返します
• 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 の3文字の 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" の受賞案件では、子案件を 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 が含まれます。上流の一覧には受領者の UEI や所在地は含まれません。usaspending_get_award の subaward_count で、サブアワードの有無を確認できます

---

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）が示されます。合計にはすべての契約種別が含まれます。種別ごとの合計を確認するには、filters.recipient_idとaward_type_codesを指定してusaspending_spending_over_timeを使用します

---

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では州のFIPSコードと郡のFIPSコードを連結した5桁（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 _tool

• 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 _tool

• dimension は overview、agency、cfda、recipient、geography のいずれかです。filters.def_codes は overview では任意ですが、それ以外のすべてのディメンションでは必須です（指定されていない、または空の場合は missing_def_codes）。["L", "M", "N", "O", "P"] などのコードを指定すると、COVID-19 の資金を抽出でき、applied_def_codes に適用されたコードが返されます。limit は overview を除くすべてのディメンションで最大 100 です。spending_type（award がデフォルト、または total）は agency のみに適用され、地理情報には filters.geo_layer（state、county）を指定します
• 各行には obligation、outlay、award_count が含まれます。また、spending_type: total の場合、agency の行には total_budgetary_resources も含まれます。overview は合計値と funding_by_def_code を返します。recipient の行の id は usaspending_get_recipient に渡せます。recipient の filters.query では検索テキストで絞り込めます。検索テキストはトリミングされて applied_query に反映され、空白のみの場合はクエリが適用されません。recipient の合計件数が 10,000 の場合、これは到達可能な上限であり、該当する可能性のある件数の下限でもあり、truncated フラグが付きます。最後の項目に到達するには filters.query で絞り込んでください。地理エリアは aggregated_amount の順位順に並び、limit と page でページ分けされます。total にはエリアの全件数が含まれます。後続のエリアが残っているページには truncated フラグが付き、truncationCeiling は表示された金額のうち最も低い金額を示します。履行場所の記録がない支出は、帰属先不明のエリア 1 件として順位付けされます
• Agency、cfda、recipient では、該当するすべての行を対象にした totals も返されます。totals には obligation、outlay、および total_budgetary_resources（agency、total の場合）または award_count が含まれます。コードを指定していても overview がタイムアウトする場合があります。その場合は filters.def_codes を絞り込むか、後で再試行するか、spending_type: total を指定した agency の内訳を使用して、義務額、支出額、予算リソースを確認してください
• 通知には、上流からのメッセージ、無視されたフィルター、上限に関する案内、および両方の出力形式での空ページからの復旧方法が保持されます。query は recipient 以外では無視され、geo_layer は geography 以外では無視され、award_type_codes は overview では無視されます。オフセットが正の合計件数に達している空ページでは、同じフィルターを使って前のページを参照するよう案内されます。途中の空ページでは、取得済み件数が最後であるとは示さずに合計件数が報告されます。合計件数がない場合は、不明のままです

---

usaspending_search_federal_accounts _tool

• 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 _tool

• 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 と、各勘定の金額を含む Treasury Account Symbol ごとの項目が 1 件ずつ並ぶ children を返します。財務データがない年度では、別の年度のデータで置き換えることなく、勘定のメタデータと通知が保持されます

---

usaspending_get_federal_account_breakdown _ツール

• account_code と dimension（program_activity または object_class）を指定します。limit は最大 100 で、行数は page_metadata.total に含まれます
• 各行には code、name、obligations が含まれます。program_activity の行には、PAC/PAN または PARK のいずれかを示す type も含まれます
• 任意の fiscal_year を指定すると、10 月 1 日から 9 月 30 日までの会計報告期間に絞り込まれ、その値は time_period と period に反映されます。省略すると、all available periods が対象になります

3 つすべての連邦会計ツールでは、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 を使用します。API キーは不要です。DATA Act に基づき、データは公開されています
• 賞の検索と支出分析ツールの対象は、2007-10-01 以降のアクション日です。それ以前の日付を指定すると date_before_earliest が返されます。また、DoD 契約データの公開には 90 日の遅れがあります
• usaspending_spending_by_category は 8 つのカテゴリ別サブルートを 1 つの category enum にまとめ、usaspending_disaster_spending は 5 つの災害関連エンドポイントを dimension にまとめています
• 各リクエストは 1 つの実時間予算（デフォルト 45 秒）内で実行されます。遅い応答には予算全体を使って 1 回だけ試行し、高速な失敗のみ再試行されます。失敗は各ツールの復旧ヒントとともに api_timeout または api_unavailable として示され、リクエストが拒否された場合はエラーメッセージに USAspending 独自の説明が含まれます

エージェントに適した出力：

• ID は明示的なフィールドとして連結できます。generated_internal_id、agency_slug、recipient.recipient_id、federal_account、account_number を使うことで、エージェントは表示文字列を解析せずに資金の流れをたどれます
• 正確なページネーション：すべてのリストに 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	1 回の試行における HTTP タイムアウト時間（ミリ秒、1000～120000）です。各試行はこの時間、またはリクエスト予算の残り時間のいずれか短い方で打ち切られます。タイムアウトした試行は再試行されません。	45000
USASPENDING_RETRY_BUDGET_MS	1 回のリクエストに対する実時間の予算（ミリ秒、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 のバレルファイルを介して新しいツールを登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから出力スキーマを返します。不足しているフィールドを捏造してはいけません。

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。