fcc-broadband-mcp-server

---

概述

FCC 宽带数据涵盖 Form 477（2015 年 6 月至 2021 年 6 月）和宽带数据收集（自 2022 年 6 月起）。将坐标进行地理编码以获取人口普查区块，查询区块内的 ISP 和公布速率，并按未覆盖人口汇总、比较或排名地理区域，支持 BEAD 和公平性研究。

工具

工具	描述
fcc_geocode_block	将经纬度坐标转换为 2010 年版本的人口普查区块 FIPS 代码，并提供县和州标识符
fcc_search_availability	列出人口普查区块内的服务提供商和公布速率，可按技术和速率筛选
fcc_search_geographies	按名称查找地点和 CBSA GEOID，以便查询覆盖情况
fcc_get_coverage_summary	获取某个地理区域按服务提供商数量划分的人口，并按城市/农村和部落/非部落地区细分
fcc_compare_areas	比较多个同类型地理区域的覆盖情况并排名，覆盖最差的排在最前
fcc_find_underserved	按未覆盖人口对州内或全国范围内服务不足最严重的地区进行排名
fcc_search_providers	按名称、州和技术搜索控股公司；返回 hoconum 标识符
fcc_get_provider	获取某家控股公司的全国覆盖情况：各项技术及各速率档位覆盖的人口
fcc_list_filing_periods	列出数据版本：Form 477 申报期和 BDC 数据截止日期
fcc_list_downloads	列出某个数据截止日期的 BDC 批量数据文件

资源

资源	描述
fcc-broadband://geography/{type}/{id}/summary	单个地理区域在 25 Mbps 下的覆盖率摘要
fcc-broadband://providers/list/{offset}	Form 477 控股公司目录中的一页，每页 25 条

也可以通过工具访问资源数据：地理区域数据使用 fcc_get_coverage_summary，控股公司数据使用 fcc_search_providers。

提示词

提示词	描述
broadband_equity_analysis	组织一份数字鸿沟分析，将 FCC 覆盖率与 Census 和 BLS 数据串联起来

能力参考

fcc_geocode_block _工具

• latitude 和 longitude 使用十进制度表示，通过 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（15 位，2010 年版本）；tech_filter（Form 477 技术代码）、min_speed_down（Mbps）和 consumer（true 表示消费者，false 表示企业）可用于缩小结果范围
• 每种服务提供方案返回一行，包含 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 开始
• 按稳定的名称／类型／GEOID 顺序返回不同的 { geography_type, geography_id, name } 匹配项，并附带 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 _工具

• 提供 2 至 50 个相同 geography_type 的 geography_ids（除 nation 外的任意类型），或设置 compare_all_states: true 以比较 50 个州加上 DC；sort_by 为 unserved_pct（默认值）、unserved_pop、coverage_pct 或 competitive_pct
• 所有排序方式都按最差情况优先，因此 rank 为 1 的区域最需要帮助；各行包含 id、解析后得到的 name、按服务提供商数量划分的人口以及全部三个百分比。失败代码包括 missing_geography_ids、invalid_all_states_combo、invalid_geography_id_shape 和 no_data_found

---

fcc_find_underserved _工具

• 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 _工具

• 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 _工具

• hoconum（仅数字），取自 fcc_search_providers 或提供商目录资源
• 返回 techCodes / techLabels 和 speedTierPopulation；后者按每人一次计数，并省略空档位。仅面向企业客户的运营商返回的两个列表均为空。未找到提供商时返回错误 provider_not_found；超过 30 秒时限时返回错误 live_provider_timeout

---

fcc_list_filing_periods _工具

• 始终返回 Form 477 时期；配置凭据后，include_bdc: true 会额外包含 BDC 截止日期
• periods 按时间从新到旧排列，每项包含 asOfDate 和 source（form477 或 bdc），并附带 form477Count、bdcCount 和 hasBdcCredentials；缺少凭据时，bdcCount 为 0，不会报错

---

fcc_list_downloads _工具

• 必须提供 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 _资源

• type 接受 fcc_get_coverage_summary 的七种地理类型；id 是 FIPS GEOID，需通过位数校验；全国范围使用 0
• 固定使用 25 Mbps 和 acfosw；以 application/json 格式返回 population、三个百分比和 segments。如需使用其他阈值或筛选条件，请使用 fcc_get_coverage_summary

---

fcc-broadband://providers/list/{offset} _资源

• offset 按 hoconum 顺序，每次对目录中的 25 个条目分页；从 0 开始，并按 nextOffset 继续
• 条目包含 hoconum，以及在解析后提供的 holdingCompanyName；每页报告 total 和 count。如需按名称查找公司，请使用 fcc_search_providers

---

broadband_equity_analysis _提示词

• 参数：region（自由文本）和 focus（underserved、rural、tribal 或 all），均为必填项
• 返回一条用户消息，概述五步分析：基准覆盖情况、重点区域、人口统计交叉分析、提供商概况和 BEAD 背景

功能

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

FCC 专属功能：

• 提供三个 FCC 数据源，均为美国政府公共领域数据：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 后，才会向 MCP 客户端提供 fcc_list_downloads
• 区域工具共用一套词汇：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

面向 Agent 的输出：

• 筛选条件回显：搜索、摘要和排名工具会返回 appliedFilters，且每个 Form 477 结果都包含 dataVintage
• 明确标示部分结果：scanTruncated 和 scanRowCap 用于标记来自受限上游扫描的结果（fcc_search_providers、fcc_find_underserved），无匹配结果时会返回 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” 下生成令牌。
• 可选：Socrata 应用令牌（FCC_OPENDATA_APP_TOKEN），用于提高 Form 477 的速率限制。

安装

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	在本地 SQLite 镜像覆盖范围内，从镜像提供 Form 477 查询结果。	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 安装不会映射该别名。

• 查询的州已完成全部数据导入后，区块和地理位置查询将从镜像提供；其他查询则回退到实时 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 的十个工具。
src/mcp-server/resources	资源定义（*.resource.ts）。地理摘要和服务提供商目录。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。宽带公平性分析提示词。
src/services/open-data	FCC Open Data（Socrata）服务，提供 Form 477 部署、区域和服务提供商表；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）

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。