mcpField
F
fcc-spectrum-mcp-server

fcc-spectrum-mcp-server

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

关于 fcc-spectrum-mcp-server

fcc-spectrum-mcp-server 让频谱研究者、许可证持有人和分析人员通过本地索引搜索美国 FCC 无线电许可证记录。支持许可证和站点查询、频率搜索及参考代码解读;不包括全功率广播电台和卫星地球站。

主要功能

  1. 01搜索许可证和频谱租赁
  2. 02读取许可证站点及技术记录
  3. 03查找附近的授权发射站
  4. 04按频段搜索频率分配
  5. 05解读 ULS 参考代码

适用场景

  1. 01按呼号查看许可证详情
  2. 02根据坐标定位附近授权站点
  3. 03查找覆盖某个频率的许可证
  4. 04解释 FCC 服务和状态代码

MCP 相关

通过 STDIO 或 Streamable HTTP 向 MCP 客户端提供五个工具和两个资源。查询使用本地 SQLite 索引;构建和刷新索引时需要联网。

配置

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

服务地址https://fcc-spectrum.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/fcc-spectrum-mcp-server0.3.0

工具

5
参数类型必填说明
frnstring否FCC 注册号,最多 10 位数字;空格和连字符会被移除,并在左侧补零。
limitinteger否每页记录数,必须为正整数;超过 100 的值将限制为 100,并附带提示。
stateenum否被许可人的邮寄地址所在州:两个字母的 USPS 代码(包括 DC、PR、VI、GU、AS、MP)或完整州名。这是被许可人的地址,而非站点位置。AL | AK | AZ | AR | CA | CO | CT | DE | DC | FL | GA | HI | ID | IL | IN | IA | KS | KY | LA | ME | MD | MA | MI | MN | MS | MO | MT | NE | NV | NH | NJ | NM | NY | NC | ND | OH | OK | OR | PA | RI | SC | SD | TN | TX | UT | VT | VA | WA | WV | WI | WY | AS | GU | MP | PR | VI
cursorstring否同一搜索上一页返回的 nextCursor;首页请省略。
statusenum否许可证状态:A 表示有效,L 表示法律审核中,X 表示期限待定,E 表示已过期,C 表示已取消,T 表示已终止,P 表示母站已取消;或使用 "any" 表示所有状态。默认值为 A。A | C | E | L | P | T | X | any
callsignstring否精确的呼号或租赁 ID,例如 "KNKA123" 或 "L000012345"。大小写、空格和一个尾随的便携后缀("/4")会进行规范化。ULS 会重复使用呼号,因此可能匹配多条记录。
licenseestring否被许可人名称中的词语,至少包含一个字母或数字;每个词都必须匹配名称中某个词的开头,顺序不限(例如 "verizon wireless")。由 - 或 & 连接的词语("T-Mobile"、"AT&T")会按相邻部分进行匹配。
market_codestring否地理区域许可证的市场代码,精确匹配,例如 "PEA016"、"CMA020"、"D06037" 或 "NW"(全国范围);结果中以 marketCode 返回。大小写、空格和连字符会被忽略,数字会在左侧补零("pea16" 会按 PEA016 处理)。
radio_servicestring否两字符无线电业务代码,例如 "CD"(寻呼)或 "BR"(BRS);请参阅 fcc_spectrum_list_reference 主题 "radio_services"。

详细介绍

@cyanheads/fcc-spectrum-mcp-server

通过 MCP 搜索 FCC 无线电许可证、查找附近的持证站点,并查看哪些用户获准使用某个频率。支持 STDIO 或 Streamable HTTP。

5 个工具 • 2 个资源

版本 许可证 Docker MCP SDK npm TypeScript Bun

安装到 Claude Desktop 安装到 Cursor 安装到 VS Code

框架


概述

离线搜索 FCC 通用许可系统中的美国无线电频谱许可证。可查询呼号、被许可方或市场;查看许可证的站点、天线、频率和微波路径;查找某个坐标附近的发射机;并查看哪些用户获准使用任意频率或频段。涵盖陆地移动、微波、蜂窝、寻呼、业余无线电等;不包括全功率广播电台和卫星地球站。无需 API 密钥。

工具
工具描述
fcc_spectrum_search_licenses按呼号、被许可方名称、FRN、市场代码、无线电服务、状态或被许可方所在州搜索许可证和频谱租赁。
fcc_spectrum_get_license按呼号或 USI 完整读取单个许可证或租赁:被许可方、状态和日期、位置、天线、带发射类型的频率、微波路径、市场频段和租赁关联。
fcc_spectrum_find_transmitters查找给定坐标半径范围内由 FCC 许可的站点,按距离从近到远排列,并列出其申报用途和获准频率。
fcc_spectrum_search_frequencies查找频段与指定频率或频段重叠的站点频率分配和市场区域频谱区块。
fcc_spectrum_list_reference解码 ULS 代码(无线电服务、站点类别、状态、位置和天线类型、申请人类型、操作员类别),并报告索引覆盖范围和更新情况。
资源
资源描述
fcc-spectrum://license/{callsign}一个按呼号查询的许可证或租约,以 JSON 格式返回 — 即第一页 fcc_spectrum_get_license 返回的内容。
skill://fcc-spectrum-guide/SKILL.mdULS 调查工作流指南:完整性检查、标识符、共享站点、市场地理区域、租约和微波路径。

也可以通过 fcc_spectrum_get_license 获取许可证记录。客户端可通过 resources/list 和 resources/read 访问调查指南。

功能参考

fcc_spectrum_search_licenses 工具
  • 筛选条件:callsign、licensee(名称中每个单词的开头都必须匹配)、frn、market_code(地理区域许可证的市场代码,精确匹配:PEA016、CMA020、D06037、NW;pea16 会按 PEA016 处理)、radio_service 和 state(被许可人的邮寄地址所在州)——至少需要一个条件;status 可缩小范围至 A(默认值)、C、E、L、P、T、X 或 any
  • 正整数 limit(默认值为 25,上限为 100),支持游标分页;每行包含传递给 fcc_spectrum_get_license 的 usi,以及 isLease、licenseeRedacted、位置数量和频率数量
  • 类型化错误:no_criteria、unknown_radio_service、service_not_indexed、invalid_cursor、index_not_ready

fcc_spectrum_get_license 工具
  • callsign 和 usi 必须且只能提供一个(否则返回 identifier_required);如果一个呼号对应多条记录,则返回其中有效的记录,否则返回最新记录,并在 otherCallsignRecords 中列出其他记录
  • 对大型记录分页:每次最多返回 50 个完整位置、100 个天线和 100 条微波路径(超过此数量的位置会单独列出),最多返回 100 个租约;每次调用返回 max_frequencies 行频率数据(正整数,默认值为 100,上限为 1000);nextLocationOffset 和 nextLeaseOffset 的值用于下一次调用的 location_offset 和 lease_offset
  • 微波路径(FCC PA 记录)列在发射信号的天线下方的 paths 中,包含路径编号、类型、无源标记和申报时填写的接收呼号;还包含一个 receive 端,其中有其位置和天线编号,以及许可证恰好申报了一个有效的接收编号对应站点时的坐标;如果未申报站点或申报了多个站点,则包含 siteCount;如果没有匹配的天线记录,则包含 antennaFiled: false。pathTotal 统计该记录所有位置的路径总数(在尚未为路径建立索引的索引中,此字段不存在,直到 mirror:init 重建索引);如果后面还有更多位置,提示会报告与其关联的已列出路径
  • location_number 从 fcc_spectrum_find_transmitters 或 fcc_spectrum_search_frequencies 返回的站点 locationNumber 开始列出位置;如果与非零的 location_offset 同时使用,则会失败(location_start_conflict)
  • 未找到记录时会返回包含 guidance 和最多 5 个呼号前缀 candidates 的 found: false,而不是报错;technicalRetained: false 表示该记录的状态下没有保留站点或频率数据

fcc_spectrum_find_transmitters 工具
  • latitude / longitude 使用十进制度数或 DMS 字符串;radius_km 范围为 0.1–100(默认值为 5);可选的 frequency_low / frequency_high 使用 unit(kHz、MHz 为默认值、GHz);radio_service、location_type(一个 ULS 位置类型代码,不区分大小写:F 仅保留固定站点,M 保留移动区域,T 保留临时固定区域)以及 status(默认值为 A,也可为 L、X 或 any,表示全部三种状态)
  • 站点按距离从近到远排列;limit 为正整数(默认值为 25,上限为 100),支持游标分页;每个站点最多列出 max_frequencies_per_site 个频率(正整数,默认值为 10,上限为 50),frequencyCount 提供完整计数
  • 若有存档信息,每个站点都会包含 locationTypeCode、locationTypeLabel、radiusKm、locationClassCode 和 locationClassLabel;移动区域或临时固定区域按存档中心点返回,distanceKm 表示到该中心点的距离。location_class(不区分大小写,可为 C、L、P、R 或 T)仅保留一个 FCC 类别;结果描述的是授权情况,而非实际的空中活动
  • 类型化错误:invalid_frequency_range、unknown_radio_service、service_not_indexed、invalid_cursor、index_not_ready

fcc_spectrum_search_frequencies 工具
  • 必填 frequency_low,frequency_high 可选,均使用 unit;当站点分配的占用频段(按其发射带宽扩展后)与查询频段重叠时即匹配;市场频段块则按存档的频段边缘匹配;kind 可为 site、market 或 both(默认值)
  • 可按 state、radio_service、licensee、frn、market_code 和 status(默认值为 A,也可为 L、X 或 any)缩小范围;limit 为正整数(默认值为 50,上限为 200),支持游标分页,按频率升序排列;每行的 kind 表明其为站点分配还是市场频段块
  • market_code 和 frn 会同时筛选站点行和市场行;frn 搜索会对单个被许可方的信息进行脱敏。若有存档信息,单站点行会包含 locationTypeCode、locationTypeLabel、radiusKm、locationClassCode 和 locationClassLabel;共用编号的行和市场频段块不包含这些字段
  • 类型化错误:invalid_frequency_range、unknown_radio_service、service_not_indexed、invalid_cursor、index_not_ready

fcc_spectrum_list_reference 工具
  • topic 可为 radio_services、station_classes、license_statuses、location_types、antenna_types、applicant_types、operator_classes 或 coverage;filter 会将无线电业务和电台类别缩小到代码和标签中包含所有令牌的条目,匹配时会折叠大小写和重音符号,并将标点视为令牌分隔符
  • 可搜索的 filter 必须包含 ASCII 字母或数字(否则返回 invalid_filter);空白值表示未设置。其他主题会忽略该筛选条件并说明原因
  • 使用 {"topic":"station_classes","filter":"FXO"} 解码电台类别(FXO 为 Operational Fixed,FB2 为 Mobile Relay,MO 为 Mobile)。标签来自 FCC 的 uls_code_definitions_20240718.txt 所附的 266 个代码表(存档副本);代码未映射时不会返回任何条目。这些是许可类别,而非实际的空中活动
  • coverage 会报告 index.status(none、building、ready)、每个分组的记录数、站点数和频率数及其快照时间,并说明是否启用了脱敏;即使尚未构建索引也可使用。index.antennaCoverageIncomplete: true 表示较旧的索引遗漏了无编号的天线;index.pathCoverageIncomplete: true 表示索引构建时尚未纳入微波路径;运行 bun run mirror:init 可重新构建其中任一索引

fcc-spectrum://license/{callsign} 资源
  • 以 application/json 格式提供 fcc_spectrum_get_license 的第一页(最多 100 行频率数据,包含其微波路径),以及 dataAsOf、总数和一条指出用于读取其余内容的工具调用的 notice;缓存 1 小时
  • 类型化错误:index_not_ready、license_not_found

功能

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

FCC ULS 专属功能:

  • 请求时无需密钥且完全本地运行——每次查询都会读取 SQLite 索引;只有构建和刷新索引时才需要网络访问
  • 按占用频段匹配频率——每个指配频段都会根据从其发射标识中解析出的带宽进行扩展,因此即使查询频率接近宽信道边缘,也能找到该信道
  • 频谱租赁是一级记录——isLease 标记租赁记录,显示的被许可人是承租人,且会双向列出租赁链接
  • 如果申报中未填写站点州/地区(微波和 BRS/EBS 申报中很常见),则根据坐标推导,并标记 stateFromCoordinates
  • 默认会隐去个人被许可人的信息,且永远不会摄取联系详情——参见个人被许可人信息隐去

便于 Agent 使用的输出:

  • 数据新鲜度和筛选条件回显——每个数据响应都包含 dataAsOf,搜索工具会回显 appliedFilters
  • 截断说明——包含 truncated、shown、cap 和 totalCount,并通过 notice 指明下一次调用,避免将部分页面误读为完整结果;超过上限的输出预算会被限制到该上限,并通过说明列出请求值和生效值
  • 缺失字段保持缺失——ULS 留空的字段会省略;未通过验证的坐标会保留为 DMS 文本(coordinatesDms);全零的占位坐标会被丢弃
  • 带区分标记的输出——found、kind、isLease、licenseeRedacted 和 technicalRetained 让调用方可以根据数据分支处理,而无需解析字符串

开始使用

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

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

托管索引每周重建、每日刷新,且会隐去个人被许可人的信息。

或者,在通过首次运行设置构建的索引上本地运行:

claude mcp add fcc-spectrum-mcp-server -e FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls -- bunx @cyanheads/fcc-spectrum-mcp-server

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

{
  "mcpServers": {
    "fcc-spectrum-mcp-server": {
      "command": "bunx",
      "args": ["@cyanheads/fcc-spectrum-mcp-server"],
      "env": { "FCC_SPECTRUM_MIRROR_DIR": "/path/to/fcc-uls" }
    }
  }
}

FCC_SPECTRUM_MIRROR_DIR 必须指定 mirror:init 构建的目录。请使用绝对路径:MCP 客户端会选择进程的工作目录。在首次构建完成前,数据工具会报错 index_not_ready;将主题设为 coverage 的 fcc_spectrum_list_reference 会报告构建状态。

如需了解 Docker 或从源码构建,请参阅运行服务。

首次运行设置

索引基于 FCC 在 data.fcc.gov 提供的 ULS 公共批量文件构建:每个服务组每周提供完整快照,另有每日增量文件。使用默认服务组时,一次构建会逐个下载约 1.1 GB 的压缩包;一次实测构建生成了 3,270,502 条许可证记录,索引约为 1.8 GB,耗时约 3 分钟。

在源码检出目录中执行 bun run build 后(参见运行服务),从已安装的软件包中,或使用 Docker 镜像,构建一次:

# Download the weekly snapshots and build the index (resumable; skips when nothing is newer)
FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls bun run mirror:init

# Check it: SQLite integrity plus per-file line counts against the FCC's counts files
FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls bun run mirror:verify

# Apply the daily incrementals published since the last build
FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls bun run mirror:refresh

每个 mirror:* 脚本都会在 Bun 上运行 dist/cli/ 下编译好的入口。从 npm 安装后,请在软件包目录中运行这些脚本,或直接调用入口:FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls bun node_modules/@cyanheads/fcc-spectrum-mcp-server/dist/cli/mirror-init.js(mirror-verify.js 和 mirror-refresh.js 也一样)。

使用 Docker 时,对卷运行相同的命令:docker run --rm -v fcc-uls:/usr/src/app/.mirror ghcr.io/cyanheads/fcc-spectrum-mcp-server:latest bun run mirror:init。

保持数据最新:

  • HTTP 传输。 服务会在每周日 16:00 执行每周重建,并在 17:00 执行每日刷新,时间均为进程的本地时间(Docker 镜像使用 UTC;FCC 在美国东部时间周日早晨发布快照)。刷新会检查可用的每日发布日期是否存在缺口,以及文件是否已被覆盖。如果这些文件无法覆盖检查点,服务会执行每周重建并重试刷新;如果没有更新的快照可用,任务会报告失败,直到可以恢复为止。首次索引发布前,不会运行任何任务。每项任务都会在服务运行时所用的运行时中作为子进程运行,因此写入期间查询和 /healthz 仍可正常响应,任务日志也会出现在服务日志中;关闭时,正在运行的任务会停止,并在下次运行时恢复。
  • stdio。 不会安排任何任务。请通过 cron 或其他调度器每天运行 mirror:refresh,每周运行 mirror:init;每日文件不会删除许可证,因此许可证的删除会在每周重建时生效。
  • 磁盘。 重建时会在当前服务所用索引旁写入新一代索引,因此请预留足够空间,用于存放第二份索引和最大的压缩包(约 420 MB)。较旧的索引版本会在下一次重建开始时删除。
  • 并发。 摄取锁确保同一时间只有一个 mirror:init、mirror:refresh 或计划任务写入;如果 mirror:init 中断,重新运行时会从上一个已完成的步骤继续。

配置

变量描述默认值
FCC_SPECTRUM_MIRROR_DIR存放索引及其构建文件的目录。请使用绝对路径。.mirror/fcc-uls
FCC_SPECTRUM_SERVICES要建立索引的每周服务组,以逗号分隔,不区分大小写。可选启用:gmrs、ship、aircr。名称无效时,启动会失败并列出有效选项。LMpriv,LMcomm,LMbcast,micro,cell,market,paging,coast,mdsitfs,amat
FCC_SPECTRUM_REDACT_INDIVIDUALS对个人许可证持有人和受托人姓名进行脱敏,并将个人排除在姓名搜索之外。只有设置为 false、0、no 或 off 时才会禁用此功能。true
FCC_SPECTRUM_BASE_URLULS 批量文件的主机根 URL,仅在构建或刷新索引时读取。https://data.fcc.gov/download/pub/uls
MCP_TRANSPORT_TYPE传输方式:stdio 或 http。stdio
MCP_SESSION_MODE会话模式:auto(解析为有状态)、stateful 或 stateless。stateless
MCP_HTTP_PORTHTTP 服务的端口。3010
MCP_HTTP_ENDPOINT_PATHMCP 服务挂载的 HTTP 端点路径。/mcp
MCP_AUTH_MODE身份验证模式:none、jwt 或 oauth。none
MCP_LOG_LEVEL日志级别(RFC 5424)。info
LOGS_DIR日志文件目录(仅限 Node.js)。<project-root>/logs
OTEL_ENABLED启用 OpenTelemetry 插桩(跨度、指标、完成日志)。false

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

服务组

FCC 会将每周快照划分为服务组。新增组将在下次 mirror:init 时生效;移除的组将在下次每周重建时退出。

组内容是否索引
LMpriv私人陆地移动无线电(公共安全、商业、工业)默认
LMcomm商业陆地移动无线电默认
LMbcast广播辅助陆地移动无线电默认
micro点对点微波默认
cell蜂窝通信默认
market市场区域无线通信(PCS、AWS、700 MHz、3.45 和 3.7 GHz,以及其他拍卖频段)默认
paging寻呼默认
coast海岸电台默认
mdsitfs宽带无线电服务和教育宽带服务(BRS/EBS)默认
amat业余无线电默认
gmrs通用移动无线电服务——仅被许可人记录可选
ship船舶电台——仅被许可人记录可选
aircr航空器电台——仅被许可人记录可选
个人被许可人信息屏蔽

ULS 记录会列出许多许可证背后的个人姓名,无论是业余无线电许可证,还是其他许可证:个人也持有陆地移动无线电、寻呼和微波许可证。FCC_SPECTRUM_REDACT_INDIVIDUALS 默认启用,并采用安全失败策略:

  • 当申请人类型为 I,或在业余无线电和 GMRS 服务中类型为空时,该记录视为个人记录。在任何服务中,类型为空或为 H(其他)时,如果备案包含个人姓名字段,或被许可人名称中不含组织类词语(Inc、County、Church、Wireless 等),也会视为个人记录,因此,即使组织名称中不包含这些词语,也会被屏蔽。此时,被许可人名称会设为 null,并将 licenseeRedacted 设为 true;其被许可人所在城市、各站点的街道地址和站点名称也会省略,因为有些个人会将自己的姓名填作站点名称。
  • 所有许可证的受托人姓名都会被隐藏,因为受托人必定是个人。
  • 被许可人名称搜索会排除个人,响应中的 notice 会说明这一点。通过呼号、USI 或 FRN 查询仍会返回记录,但其中的信息会被屏蔽。
  • 站点坐标、城市、县、州和技术数据仍会保留:这些属于频谱记录。
  • 屏蔽会在生成响应时应用,因此更改此设置需要重启,而非重建。

任何人的被许可人邮寄街道地址、ZIP 码、邮政信箱、收件人信息、电话号码、传真号码和电子邮件地址都不会被采集。

已知限制

  • 密集频段的频率搜索会返回不完整的页面。 在拥挤的频段(整个 150–174 MHz 频段或整个频谱)中,即使页面的行数少于 limit,也可能仍带有 nextCursor,此时 totalCount 是下限(totalIsLowerBound: true)。使用 state、radio_service、licensee、frn 或 market_code 缩小范围,以获取准确计数。
  • 站点、频率和市场区块仅为有效许可证保留(A 有效,L 法律程序待处理,X 期限待处理)。过期、已取消和已终止的记录会保留其许可证持有人、状态、日期和租赁链接。
  • 市场区块按州匹配,而非按县匹配。 如果 FCC 的市场区域定义将市场划分到某个州(跨州市场会匹配其涉及的每个州),市场名称中包含该州代码,或者许可证在该州申报了站点,则 state 会匹配该市场区块;系统不会将县或坐标映射到覆盖该区域的市场。全国性和墨西哥湾市场不会匹配任何州;名称中没有州代码的部落土地(TL)和 MVDDS(MVD)市场会被跳过;不带 state 的 market_code 可查询其中任意市场。
  • 半径搜索按覆盖区域的中心匹配。 ULS 将移动和临时固定位置记录为中心点及其覆盖半径。若中心位于 radius_km 范围内,fcc_spectrum_find_transmitters 会在该中心位置返回此覆盖区域,并附带 radiusKm;如果搜索点位于覆盖区域内,则不会因此匹配。未填写坐标的位置(大多数移动、临时、流动和控制站位置均如此)不会返回。
  • 州属信息的推导在州界附近并不精确,误差范围约为州界两侧各 1 公里;波多黎各以外的领地不会获得推导出的州属信息。
  • 移除记录最多会延迟一周。 每日文件不会删除许可证;每周重建时才会删除。如果刷新间隔超过每日文件的覆盖窗口,就必须完整重建。
  • 按频率无法找到优先接入许可证。 ULS 将每个 3.5 GHz PAL 记录为带宽 10 MHz、但不含频率的信道;请使用 fcc_spectrum_search_licenses 和 radio_service PL 列出这些许可证。
  • 同一位置编号下的频率无法关联到具体站点。 ULS 按位置编号记录频率,因此当许可证在同一编号下申报多个站点时,无法将任何频率指定到单个站点。
  • 脱敏按记录进行。 同一个人如果也持有以非个人申请人类型申报的许可证,则会在这些记录中以姓名显示;这些记录的 FRN 相同。
  • 站点类别标签使用随附的 FCC 快照。 技术响应会保留申报的代码;fcc_spectrum_list_reference 配合 topic: "station_classes" 和 filter 可解读已知代码。较新的或未知代码可能没有随附标签。
  • 坐标为申报时的 NAD83 坐标,不进行基准转换。
  • 少数不合理的发射带宽仍会被接受。 对于带宽达到频率的 20% 或更宽的设计符号,会作为申报错误忽略;较窄但不合理的申报则按申报内容记录。

运行服务

先决条件
  • Bun v1.4 或更高版本(或 Node.js v24+)。bun:sqlite 已内置于 Bun;使用 Node 时,请在服务旁安装 better-sqlite3(已声明为可选对等依赖)。
  • 在 FCC_SPECTRUM_MIRROR_DIR 指定的位置为索引预留磁盘空间:使用默认分组时约需 1.8 GB,另需预留上述重建空间。
  • 构建或刷新索引时需要访问网络以连接 data.fcc.gov。查询无需联网。
安装

用于本地开发或从源码构建索引:

  1. 克隆仓库:
git clone https://github.com/cyanheads/fcc-spectrum-mcp-server.git
  1. 进入目录:
cd fcc-spectrum-mcp-server
  1. 安装依赖:
bun install
  1. 构建服务,此操作也会编译 mirror:* 条目:
bun run build
  1. 构建索引(参见首次运行设置):
FCC_SPECTRUM_MIRROR_DIR=/path/to/fcc-uls bun run mirror:init
本地开发
  • 构建并运行:

    # One-time build
    bun run rebuild
    
    # Build the index (see First-run setup)
    bun run mirror:init
    
    # 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
# Build the index once against the volume:
docker run --rm -v fcc-uls:/usr/src/app/.mirror ghcr.io/cyanheads/fcc-spectrum-mcp-server:latest bun run mirror:init
# Serve over HTTP:
docker run --rm -p 3010:3010 -v fcc-uls:/usr/src/app/.mirror ghcr.io/cyanheads/fcc-spectrum-mcp-server:latest

该镜像默认使用无状态会话的 HTTP 传输,包含 mirror:* CLI,并将日志写入 /var/log/fcc-spectrum-mcp-server。如需使用 stdio,请运行 docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -v fcc-uls:/usr/src/app/.mirror ghcr.io/cyanheads/fcc-spectrum-mcp-server:latest。使用 docker build -t fcc-spectrum-mcp-server . 在本地构建。默认会安装 OpenTelemetry 对等依赖;如需省略,请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录用途
src/index.tscreateApp() 入口 — 注册工具、资源和技能目录,初始化索引服务,并在 HTTP 传输下启动摄取计划。
src/config使用 Zod 解析并验证服务环境变量。
src/mcp-server/tools工具定义(*.tool.ts)、共享输入架构和格式化辅助函数。
src/mcp-server/resources资源定义(*.resource.ts)。
src/services/ulsULS 服务 — 批量客户端、记录解析器、摄取器、索引版本、带脱敏的读取路径,以及会启动作业进程的摄取计划。
src/cli索引生命周期 CLI — mirror:init、mirror:refresh、mirror:verify — 编译至 dist/cli/。
tests/与 src/ 结构对应的单元测试和集成测试,包含 ULS 记录样例。
skills/已发布的调查指南,作为 MCP 资源提供。

开发指南

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

  • 处理程序抛出异常,框架负责捕获 — 工具逻辑中不要使用 try/catch
  • 使用 ctx.log 记录请求范围内的日志;数据访问须通过 ULS 索引服务
  • 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
  • 运行时以索引为事实来源 — 在进程外构建并刷新索引,并确保 ULS 空字段保持缺省

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。

许可证数据来自 FCC Universal Licensing System(ULS),属于美国政府作品,依据 17 U.S.C. §105 进入公有领域。请以“FCC Universal Licensing System (ULS)”为来源,并注明每个响应中包含的 dataAsOf 时间。本项目不再分发任何许可证数据;运营者在构建索引时会从 FCC 下载数据。本软件包确实包含一个市场至州的对照表(src/services/uls/data/market-states.json),该表根据 FCC 区域定义编制,来源包括 FCC 的县至市场文件 FCCCNTY2K.txt、其部分经济区县列表以及 47 CFR 80.385(a)(3);其中仅记录各市场覆盖的州。基本交易区域由 Rand McNally 1992 Commercial Atlas & Marketing Guide 第 123 版第 38-39 页划定;经 Federal Communications Commission 扩展和修订,见 59 FR 46195(1994 年 9 月 7 日)。主要交易区域由 Rand McNally 1992 Commercial Atlas & Marketing Guide 第 123 版第 38-39 页划定,经 Federal Communications Commission 扩展并作出例外规定,见 59 FR 14115(1994 年 3 月 25 日)。本服务独立于 FCC,且未获 FCC 背书。

评论

支持 Markdown

第一次接触 MCP?

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

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