fcc-broadband-mcp-server

---

概要

Form 477（2015年6月～2021年6月）およびブロードバンドデータ収集（2022年6月以降）の FCC ブロードバンドデータを利用できます。座標を国勢調査区画にジオコーディングし、区画内の ISP と公表速度を検索するほか、未サービス人口に基づいて地理区域を要約、比較、順位付けできます。BEAD および公平性の調査に役立ちます。

ツール

ツール	説明
fcc_geocode_block	緯度・経度の座標を、郡および州の識別子を含む2010年版の国勢調査区画 FIPS コードに変換します
fcc_search_availability	技術と速度で絞り込み、国勢調査区画内のプロバイダーと公表速度を一覧表示します
fcc_search_geographies	カバレッジ検索用に、名称から地域および CBSA の GEOID を検索します
fcc_get_coverage_summary	1つの地理区域について、プロバイダー数別の人口を、都市部／農村部および部族地域／非部族地域に分けて表示します
fcc_compare_areas	同じ種類の複数の地理区域のカバレッジを、カバレッジの低い順に順位付けします
fcc_find_underserved	州内または全国の、未サービス人口が最も多い地域を順位付けします
fcc_search_providers	名称、州、技術で持株会社を検索し、hoconum 識別子を返します
fcc_get_provider	1社の持株会社について、技術と速度階層別の人口を含む全国カバレッジプロファイルを表示します
fcc_list_filing_periods	Form 477 の提出期間と BDC の基準日を含む、データの各時点を一覧表示します
fcc_list_downloads	指定した基準日の BDC 一括データファイルを一覧表示します

リソース

リソース	説明
fcc-broadband://geography/{type}/{id}/summary	25 Mbps における1つの地域のカバレッジ概要
fcc-broadband://providers/list/{offset}	Form 477 の持株会社ディレクトリの1ページ分。1ページあたり25件

リソースデータは、ツールからも取得できます。地域には fcc_get_coverage_summary、持株会社には fcc_search_providers を使用します。

プロンプト

プロンプト	説明
broadband_equity_analysis	FCC のカバレッジと国勢調査局および BLS のデータを連携させ、デジタルデバイド分析を構成します

機能リファレンス

fcc_geocode_block _ツール

• latitude と longitude は10進度で指定し、FCC Geo API を通じて2010年の国勢調査境界に照合されます
• blockFips（15桁。fcc_search_availability ですぐに使用できます）、censusVintage、countyFips、countyName、stateFips、stateCode、stateName を返します。水域上または米国のカバレッジ範囲外の座標は block_not_found として失敗します。FCC バックエンドの構造化された障害は geo_backend_unavailable として失敗し、後で同じ座標を使って再試行するよう案内します

---

fcc_search_availability _ツール

• block_fips（2010年版、15桁）は必須です。tech_filter（Form 477 の技術コード）、min_speed_down（Mbps）、consumer（true は消費者向け、false は事業者向け）を指定して対象を絞り込めます
• 提供内容ごとに1行を返します。各行には hoconum、techCode / techLabel、maxDownloadMbps、maxUploadMbps、consumer、business が含まれ、さらに異なる持株会社の数を示す totalProviders も含まれます。プロバイダーが存在しない未絞り込みのブロックは block_not_found として失敗します。絞り込み条件に一致する結果がない場合は、notice 付きの空リストを返します

---

fcc_search_geographies _ツール

• 空白以外の値を含む name は必須で、大文字と小文字を区別しないリテラル部分文字列として照合されます。任意の geography_type は place または cbsa を指定します。limit の既定値は20（最大100）、offset の開始値は0です
• { geography_type, geography_id, name } の重複しない一致を、名前、タイプ、GEOID の安定した順序で返します。さらに count、offset を返し、残りの一致がある場合に限り nextOffset も返します。結果がないページや最終ページを超えたページには案内が含まれます。総件数は計算されません
• ミラーが有効な場合でも、year='2021' を指定して FCC のライブ検索を使用します。一致を絞り込むには、name に場所を示す語句を含めてください。CBSA コードから州への所属は判断できません。選択したタイプと GEOID を fcc_get_coverage_summary に渡してください

---

fcc_get_coverage_summary _ツール

• geography_type には nation、state、county、cd、place、cbsa、tribal のいずれかを指定します。nation 以外のすべてのタイプで geography_id が必須です。urban_rural_filter（all / R / U）と tribal_filter（all / T / N）で対象人口を絞り込めます
• プロバイダー数別の人口を示す population（noCoverage、oneProvider、twoProviders、threeOrMore、total）、coveragePct、unservedPct、competitivePct、セグメントごとの breakdown を返します。geography_not_found、invalid_geography_combo、invalid_geography_id_shape のいずれかとして失敗します
• 全国のカバレッジはローカルでは United States という名前で、geography.id: "0" を維持します。地域名の検索は不要です

---

fcc_compare_areas _ツール

• 同じ geography_type（nation 以外のすべてのタイプ）の geography_ids を2～50件指定するか、compare_all_states: true を指定すると、50州と DC を比較します。sort_by には unserved_pct（既定値）、unserved_pop、coverage_pct、competitive_pct のいずれかを指定します
• どの並べ替え方法でも、最も状況が悪い地域が先頭になります。そのため rank が1の地域が最も支援を必要としています。各行には id、解決済みの場合は name、プロバイダー数別の人口、および3つすべての割合が含まれます。missing_geography_ids、invalid_all_states_combo、invalid_geography_id_shape、no_data_found のいずれかとして失敗します

---

fcc_find_underserved _tool

• state（USPS の州または準州コード）を指定すると検索範囲が絞られ、指定しない場合は全国を検索します。geography_type は county（デフォルト）、cd、place、cbsa のいずれかです。urban_rural_filter のデフォルトは R、min_unserved_pop は 1、limit は 20（最大 100）です
• noCoverage の順にランク付けされた地域が返されます。各地域には rank、id、name、oneProvider、total、unservedPct、coveragePct が含まれます。totalFound は上限適用前の一致件数です。認識されない state を指定すると unknown_state エラーになり、一致するものがないフィルターでは notice を含む空のランキングが返されます

---

fcc_search_providers _tool

• name_search（大文字と小文字を区別しない部分一致）、state、tech_filter はすべて省略可能で、同じ届出に一致する必要があります。limit のデフォルトは 50（最大 200）です
• 重複を除いた持株会社が返されます。各社には hoconum、holdingCompanyName、およびフィルターで絞り込まれない全国の statesServed / techCodes が含まれます。一致するものがない場合は notice を含む空のリストが返されます。30 秒の制限時間内にライブ検索が完了しない場合は live_search_timeout エラーになります
• ライブ API では、scanTruncated: true はリストがサンプルであることを示し、totalCount は省略されます。完全なコーパスのミラー（FCC_MIRROR_ENABLED=true）では、すべての一致が返されます

---

fcc_get_provider _tool

• fcc_search_providers またはプロバイダーディレクトリーリソースから取得した、数字のみの hoconum
• techCodes / techLabels と、各人を一度だけ数え、空の階層を省略する speedTierPopulation が返されます。法人向けのみの通信事業者では、両方のリストが空になります。provider_not_found エラーになるか、30 秒の制限時間を超えると live_provider_timeout エラーになります

---

fcc_list_filing_periods _tool

• Form 477 の対象期間は常に返されます。認証情報が設定されている場合、include_bdc: true を指定すると BDC の基準日が追加されます
• periods は新しい順で、各項目に asOfDate と source（form477 または bdc）が含まれます。また、form477Count、bdcCount、hasBdcCredentials も返されます。認証情報がない場合、エラーにはならず、bdcCount は 0 になります

---

fcc_list_downloads _tool

• as_of_date（YYYY-MM-DD）は必須です。data_type（availability がデフォルト、または challenge）、category（Summary、State、Provider）、technology_type（Fixed Broadband、Mobile Broadband、Mobile Voice）、state、provider_name で絞り込めます。limit のデフォルトは 50（最大 200）で、offset を使ってページ分割します
• 各ファイルのメタデータと downloadUrl が返されます。ファイルの内容は返されません。totalFiles はすべての一致件数で、最終ページでは nextOffset が省略されます。対応していない日付では invalid_as_of_date エラーになります
• 起動時に BDC 認証情報が両方設定されている場合に限り、MCP クライアントから利用できます。それ以外の場合、HTTP ランディングページには無効状態のカードとセットアップ手順が引き続き表示されます

---

fcc-broadband://geography/{type}/{id}/summary _resource

• type には fcc_get_coverage_summary の7種類の地理タイプを指定します。id は桁数が検証される FIPS GEOID で、国全体には 0 を指定します
• 25 Mbps および acfosw に固定されており、application/json 形式で population、3種類の割合、segments が返されます。ほかのしきい値やフィルターを使う場合は fcc_get_coverage_summary を使用してください

---

fcc-broadband://providers/list/{offset} _resource

• offset を指定して、hoconum 順のディレクトリーを一度に25件ずつページ分割します。0 から始め、nextOffset に従ってください
• 各項目には hoconum と、解決済みの場合は holdingCompanyName が含まれます。各ページには total と count が表示されます。名前で会社を検索するには fcc_search_providers を使用してください

---

broadband_equity_analysis _prompt

• 引数は region（自由記述）と focus（underserved、rural、tribal、all のいずれか）で、どちらも必須です
• 基本のカバレッジ、対象地域、人口統計との照合、プロバイダーの状況、BEAD の背景という5段階の分析を説明するユーザーメッセージが1件返されます

特長

@cyanheads/mcp-ts-core 上に構築されています。stdio および Streamable HTTP トランスポート、差し替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

FCC 固有の機能：

• FCC の 3 つの情報源はすべて、米国政府のパブリックドメインデータです。FCC Open Data（Socrata）の Form 477、BDC Public Data API、FCC Geo API を利用します。
• すべての Form 477 ツールとリソースは認証情報なしで動作し、最後の提出分である 2021 年 6 月のデータを読み込みます。BDC データは一括ファイルのマニフェストとしてのみ公開されます。FCC_BDC_USERNAME と FCC_BDC_HASH_VALUE の両方が設定されている場合に限り、fcc_list_downloads が MCP クライアントに公開されます。
• エリアツールでは共通の用語体系を使用します。tech_filter の文字（すべての技術を表す acfosw がデフォルト、a は DSL、c はケーブル、f は光ファイバー、o はその他、s は衛星、w は固定無線）と、speed_down の段階（0.2、4、10、25、100、250、1000 Mbps。デフォルトは 25、100 は BEAD のしきい値）です。
• カバレッジ分析では、ブロック単位の展開テーブルではなく、事前集計済みの Area Table（xvwq-qtaj）を読み込むため、州や郡の規模のクエリも高速に処理できます。
• オプションのローカル Form 477 ミラー（FCC_MIRROR_ENABLED=true）を使用すると、SQLite からクエリに応答し、取り込み済みでないデータについてはライブ API にフォールバックします。

エージェント向けの出力：

• フィルターのエコー：検索、要約、ランキングの各ツールは appliedFilters を返し、すべての Form 477 結果には dataVintage が含まれます。
• 部分的な結果を明示：上流のスキャンに上限がある場合（fcc_search_providers、fcc_find_underserved）、scanTruncated と scanRowCap でその結果であることを示します。一致するデータがない場合はエラーではなく notice を返します。
• 型付きエラー：block_not_found、invalid_geography_id_shape、credentials_required などの理由と、復旧のヒントを示します。

はじめに

公開ホストインスタンス

公開インスタンス https://fcc-broadband.caseyjhand.com/mcp を利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続できます。

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "streamable-http",
      "url": "https://fcc-broadband.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fcc-broadband-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "fcc-broadband-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fcc-broadband-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• オプション：fcc_list_downloads と BDC の提出期間に必要な FCC BDC 認証情報。broadbandmap.fcc.gov の「Manage API Access」でトークンを生成してください。
• オプション：Form 477 のレート制限を緩和するには、Socrata アプリトークン（FCC_OPENDATA_APP_TOKEN）を使用します。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/fcc-broadband-mcp-server.git

2. ディレクトリに移動します：

cd fcc-broadband-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set FCC_BDC_USERNAME, FCC_BDC_HASH_VALUE, and FCC_OPENDATA_APP_TOKEN as needed

設定

変数	説明	デフォルト
FCC_BDC_USERNAME	BDC API 用の FCC アカウントのメールアドレスです。fcc_list_downloads と、fcc_list_filing_periods の BDC の日付に必要です。	なし
FCC_BDC_HASH_VALUE	broadbandmap.fcc.gov の「Manage API Access」で取得する API トークンのハッシュです。FCC_BDC_USERNAME と組み合わせて使用します。	なし
FCC_OPENDATA_APP_TOKEN	Socrata アプリトークンです。FCC Open Data のレート制限を緩和します。	なし
FCC_MIRROR_ENABLED	カバレッジの範囲内で、Form 477 のクエリをローカルの SQLite ミラーから提供します。	false
FCC_MIRROR_PATH	ミラーの SQLite ファイルを格納するディレクトリです。	data/fcc-mirror
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
LOGS_DIR	ログファイル用のディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。in-memory、filesystem、supabase、cloudflare-kv/r2/d1 を指定します。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

オプションの上書き設定の全一覧については、.env.example を参照してください。

BDC 認証情報は、プロセス環境または .env から取得できます。プロセス環境の値が優先されます。空の値、空白文字のみの値、置換されていないプレースホルダー値は、未設定として扱われます。両方の認証情報を設定した後に再起動すると、fcc_list_downloads が有効になります。Form 477 の申請期間は、認証情報がなくても利用できます。

サーバーの実行

ローカル開発

• ビルドして実行：

  # 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 build -t fcc-broadband-mcp-server .
docker run --rm -p 3010:3010 fcc-broadband-mcp-server

Dockerfile は、HTTP トランスポートとステートレスセッションモードをデフォルトとし、/var/log/fcc-broadband-mcp-server にログを出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省くには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。イメージにはミラースクリプトと書き込み可能な data/ ディレクトリも含まれています。

ローカル Form 477 ミラー

Form 477 は 2021 年 6 月の申請で凍結されているため、一度取り込んでローカルの SQLite インデックスにできます。ミラーはデフォルトで無効になっています。また、コーパス全体のソースデータは約 9 GB あり、取り込みに数時間かかるため、クエリ対象の州に絞って初期化できます。

bun run mirror:init -- --states 11,53   # specific states by 2-digit FIPS (11 = DC, 53 = WA)
bun run mirror:init -- --full           # the whole corpus
bun run mirror:verify                   # coverage, row counts, SQLite integrity

次に、FCC_MIRROR_ENABLED=true を設定してください。Docker では、docker exec <container> bun run mirror:init -- --states 11,53 を使って同じスクリプトを実行します。スクリプトは @/ パスエイリアスを通じてインポートするため、npm install では解決されません。ソースコードのチェックアウトまたはイメージから実行してください。

• クエリ対象の州がすべて取り込まれていれば、ブロックと地理情報の検索はミラーから提供されます。それ以外はライブ API にフォールバックします。
• fcc_search_geographies は常にライブ検索を使用します。ミラーには年の列が保持されていません。
• fcc_search_providers、fcc_get_provider、および GEOID に州が含まれない地理情報（cbsa、tribal、nation）は、--full を指定して取り込んだ場合にのみミラーから提供されます。
• ミラーの名前検索では単語の先頭一致（comc で「Comcast」が見つかります）が使われます。一方、ライブ API では部分文字列一致（mcast）が使われるため、単語の途中の文字列では結果が少なくなる場合があります。
• 取り込みは冪等で、処理が中断されても保存済みカーソルから再開します。全件を取り込む場合は、先に FCC_OPENDATA_APP_TOKEN を設定してください。Bun は組み込みの bun:sqlite を使用します。Node.js ではオプションのピア依存関係 better-sqlite3 が必要です。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、プロンプトを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。FCC Open Data、BDC API、Geo API にわたる 10 個のツールがあります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。地理情報の概要とプロバイダーディレクトリが含まれます。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。ブロードバンドの公平性を分析するプロンプトが含まれます。
src/services/open-data	Form 477 の展開状況、地域、プロバイダーのテーブルを扱う FCC Open Data（Socrata）サービスです。mirror/ にはローカルの SQLite ミラーが格納されています。
src/services/bdc-api	BDC Public Data API サービスです。認証が必要な申告期間とダウンロードマニフェストを扱います。
src/services/geo-api	FCC Geo API サービスです。緯度・経度を国勢調査区画 FIPS に変換します。
scripts/	ビルド、開発チェック、パッケージ作成用のスクリプトと、fcc-mirror-init.ts / fcc-mirror-verify.ts が含まれます。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を記述しないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください。
• src/mcp-server/*/definitions/index.ts のバレルを通じて、新しいツールとリソースを登録してください。
• 外部 API の呼び出しはラップしてください。未加工データを検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足しているフィールドを捏造してはいけません。
• Socrata はすべてのフィールドを文字列として返すため、件数と速度（has_0～has_3more、maxaddown、maxadup）を明示的に解析してください。

コントリビューション

Issue は歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

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