fbi-crime-mcp-server

---

概述

FBI Crime Data Explorer 中的美国犯罪统计数据：每月犯罪率和数量（含人口及报送覆盖情况）、仇恨犯罪、逮捕和 NIBRS 总数（按全国、州或机构级别统计）、按州搜索机构 ORI，以及执法人员遭杀害和袭击统计数据（LEOKA）。

工具

工具	描述
fbi_search_agencies	从 CDE 机构目录中查找一个州的机构及其 ORI 代码；可按名称词语、县和机构类型筛选；支持分页
fbi_get_crime_estimates	从 CDE 汇总端点获取按全国、州或机构范围统计的 UCR 月度犯罪率和数量；可选提供州和全国对比率
fbi_get_hate_crimes	按偏见动机和类别统计仇恨犯罪事件，并按犯罪、地点、犯罪者和司法区细分；时间范围为 1991 年至当前年份
fbi_get_arrests	按犯罪、被捕者性别和种族以及年龄组统计逮捕人数；时间范围为 1985 年至当前年份
fbi_get_nibrs_breakdown	按一项犯罪统计 NIBRS 受害者、犯罪者、武器及相关犯罪细分数据；时间范围为 1991 年至当前年份
fbi_get_leoka	按月或年初至今统计警员死亡、武器和情况数据（LEOKA）；时间范围为 2020 年至当前年份
fbi_get_arson	[已禁用] 使用 fbi_get_crime_estimates，并设置 offense="arson"
fbi_get_agency	[已禁用] UCR 机构资料后端已停用；请使用 fbi_search_agencies
fbi_get_human_trafficking	[已禁用] UCR 人口贩运后端已停用
fbi_get_participation	[已禁用] UCR 和 CDE 参与情况后端已停用
fbi_list_code_table	[已禁用] UCR 代码表后端已停用

上方五个不可用条目是已禁用的操作员记录，并非可调用工具。已停用的数据集请访问 FBI CDE。

功能参考

fbi_search_agencies _工具

• state_abbr（必填，两个字母，不区分大小写）用于选择州目录。可选筛选条件适用于整个州：name_contains（名称中必须包含所有词语，顺序不限，不区分大小写）、county（与机构所属任一县匹配，不区分大小写）和 agency_type（City、County、Other State Agency、Other、State Police、University or College 或 Tribal）。
• limit（1–200，默认值为 50）和 offset（默认值为 0）用于对匹配结果分页，结果按机构名称再按 ORI 排序。
• 返回 state_abbr、total（分页前的匹配数）、offset、next_offset（最后一页时不返回），以及包含 ori、agency_name、agency_type、counties、is_nibrs 和 CDE 有记录时的 nibrs_start_date 的 agencies[]。
• 对于 CDE 没有目录的代码（AS、MP 或无法识别的代码），将返回零个机构并附带提示；超出结果范围的 offset 将返回零个机构，并附带说明总数的提示。

---

fbi_get_crime_estimates _工具

• scope：national（不带标识符）、state（仅使用 state_abbr，两个字母）或 agency（仅使用 ori，九个字母或数字；使用 fbi_search_agencies 查找）。大小写会统一转换为大写。
• offense：violent-crime、property-crime、robbery、burglary、larceny、motor-vehicle-theft、arson、aggravated-assault、rape 或 homicide。日期范围从 from_year/from_month 到 to_year/to_month（1985 年至当前年份；月份默认分别为 1 月和 12 月），且开始日期不能晚于结束日期。若年份晚于当前 UTC 年份，则会报错 year_out_of_range；当前年份中晚于最新数据日期的月份会返回 null 值。
• 对每个月的犯罪类型，返回 entity_name、每 100,000 名参与统计人口对应的发生率、实际数量/破案数量，以及可为 null 的 population、participated_population 和 population_coverage_percent；如果数据提供方提供了 data_last_updated 和 max_data_date，也会返回。
• include_comparisons（默认值为 false；仅适用于 state 或 agency 范围）会添加 comparisons：按 CDE 提供的顺序列出每个对比实体（某个机构所属的州，然后是美国；某个州对应美国），每项为 { entity_name, months[] }，包含准确对应所选范围月份的 year、month、rate_per_100k、clearance_rate_per_100k、population、participated_population 和 population_coverage_percent。CDE 不会为对比实体提供数量；如果 CDE 未提供对比实体，列表将为空。
• 类型化错误：scope_param_missing、scope_param_incompatible（national 范围下设置 include_comparisons: true 时也会报此错误）、year_out_of_range、invalid_date_range、no_data（数据提供方不识别格式正确的标识符时也会返回此错误）。

---

fbi_get_hate_crimes _工具

• scope、state_abbr、ori 以及 from_year/from_month/to_year/to_month 时间范围遵循 fbi_get_crime_estimates 的约定，年份范围为 1991 年至当前年份；数量会按整个时间范围汇总。
• bias：all（默认值）或 34 个 CDE 偏见代码之一（11–85，见该字段的说明）。指定代码时，事件数量包括由该动机导致的事件，以及包含该动机的多重偏见事件。
• 返回 incident_section（bias、bias_category）和 bias_section（offense_type、location_type、offender_race、offender_ethnicity、judicial_district），均为类别到数量的映射，并保留 CDE 提供的所有类别，包括零值和 null 值。bias_section 中的各维度按不同口径统计，因此总和不会等于单一总数或事件数量。若有提供，还会返回 bias_label 和 data_last_updated。
• 全零结果会成功返回并附带 notice，因为对于没有报告的情况以及不受识别的州或 ORI，CDE 都会返回零值。
• 类型化错误：scope_param_missing、scope_param_incompatible、year_out_of_range、invalid_date_range。

---

fbi_get_arrests _工具

• 范围、标识符和时间范围与 fbi_get_hate_crimes 相同，年份范围为 1985 年至当前年份。
• offense：all（默认值）或 46 个 CDE 数字犯罪代码之一（例如 30 Robbery、11 Murder and Nonnegligent Homicide；见该字段的说明）。不接受 robbery 等单词形式的 slug。代码 23（Rape - Not Specified）不包含在内，因为 CDE 对其仅返回零值。
• 返回 offense_name、offense_category、offense_breakdown、arrestee_sex、arrestee_race、male_arrests_by_age 和 female_arrests_by_age，均为类别到数量的映射；如果有提供，还会返回 offense_label、data_last_updated 和 max_data_date。各分组分别统计，因此各自的总和会有所不同。
• 全零结果的 notice 和类型化错误与 fbi_get_hate_crimes 相同。

---

fbi_get_nibrs_breakdown _工具

• 范围、标识符和时间窗口与 fbi_get_hate_crimes 相同，年份范围为 1991 年至当前年份。
• offense（必填，不区分大小写）：71 个 CDE NIBRS 犯罪代码之一（例如 13A 加重袭击、120 抢劫；详见字段说明）。没有 all，并且排除 23*（未指定），因为 CDE 对其仅返回 null。
• 返回 victim（age、sex、race、location、ethnicity、relationship）、offender（age、sex、race、ethnicity）和 offense_details（weapons、related_offenses），均为类别到计数的映射，保留 CDE 提供的所有类别，包括零值和 null；此外，若有提供，还会返回 offense_label、data_last_updated 和 max_data_date。各维度分别统计，不会合计为一个总数。
• 类型化错误：scope_param_missing、scope_param_incompatible、year_out_of_range、invalid_date_range、no_data（CDE 对所有类别均无值：州或 ORI 无法识别、该时间窗口内没有 NIBRS 数据，或该窗口内没有上报所选犯罪的事件；对于执法机构，fbi_search_agencies 会显示 is_nibrs 和 nibrs_start_date）。

---

fbi_get_leoka _工具

• period：ytd（年初至今；省略 month）或 monthly（需要提供 month，范围为 1–12）；必须提供 year（2020 年至当前年份；提供更晚年份会触发 year_out_of_range）
• totals 携带 CDE 年初至今数据块中的 total_officers、total_incidents、total_officers_dod、total_officers_doi、total_incidents_dod 和 total_incidents_doi。两个周期都会返回这些值，它们不是指定月份的合计值。上游未定义 dod/doi；它们以相同的值取代了已移除的 total_*_felonious 和 total_*_accidental 字段。
• 类别到计数的映射：weapons、officer_activity、lighting_conditions、body_armor_worn、location_of_attack、offender_previously_known_to_agency、offender_prior_mental_illness、offender_prior_relationship、officer_circumstances_time_of_attack、officer_incident_type、officer_type_of_assignment、weather_conditions、offender_demographic、officer_demographic、officer_death_by_time_of_day 和 officer_death_by_month。
• deaths_by_region 和可选的 deaths_by_year 会按 Felonious/Accidental 等类型细分死亡情况；月度响应会省略年度序列。deaths_by_year 覆盖 CDE 返回的时间范围，可能包含请求年份之后的年份；当前年份的条目为年初至今数据。缺失的部分会省略，null 计数表示不可用，零值仍为零。
• officer_death_by_month 仅保留 CDE 覆盖的月份，因此补齐的零值不会被误读为计数：月度响应在每个年份下仅包含请求月份，当前年份的 YTD 响应则包含截至当前 UTC 月的月份。过去年份的 YTD 响应会保留 CDE 返回的序列。
• 类型化错误：month_required（月度周期未提供 month）、month_not_applicable（YTD 周期提供了 month）、year_out_of_range、no_data

---

功能

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

FBI CDE 专属功能：

• CDE 汇总端点（/cde/summarized/），提供全国、州级和各机构在 10 种犯罪类型中的犯罪率和数量，并可选择包含州级和全国对比率
• CDE 机构目录（/cde/agency/byStateAbbr/），可按州、名称、县和机构类型查找 ORI
• CDE 仇恨犯罪（/cde/hate-crime/）、逮捕（/cde/arrest/）和 NIBRS（/cde/nibrs/）总数，覆盖全国、州级和机构范围；NIBRS 涵盖 71 种犯罪代码
• CDE LEOKA 端点（/cde/leoka/），提供按月或年初至今统计的警员殉职、武器和事发情况数据
• 无需注册即可使用 DEMO_KEY（共享的限流池）；注册的 api.data.gov 密钥可提高吞吐量
• 五个已弃用的工具会在 HTTP 着陆页保留禁用原因；MCP 客户端只能发现六个可调用工具，且没有资源

面向 Agent 的输出：

• 类型化错误原因附带恢复提示，可用于修正范围、日期和周期，或处理数据不可用的情况
• 上游缺失的犯罪率、案件侦破率、数量、人口和覆盖率会显示为 null，而不会伪造为零
• data_last_updated 和 max_data_date 会返回 CDE 自身的日期

开始使用

公共托管实例

公共实例位于 https://fbi-crime.caseyjhand.com/mcp，无需安装。无需 API 密钥；该实例会提供自己的密钥。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。请参阅 FBI CDE API 密钥注册以获取密钥；DEMO_KEY 可用于探索，但受到速率限制。

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FBI_API_KEY=your-api-key",
        "ghcr.io/cyanheads/fbi-crime-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 用于 FBI CDE API 的 api.data.gov API 密钥。DEMO_KEY 可用于测试，但共享池的限额约为 1,000 req/hr。

安装

1. 克隆代码仓库：

git clone https://github.com/cyanheads/fbi-crime-mcp-server.git

2. 进入目录：

cd fbi-crime-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set FBI_API_KEY

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。主要环境变量：

变量	描述	默认值
FBI_API_KEY	必填。 FBI CDE API 的 api.data.gov API 密钥。可使用 DEMO_KEY 进行有限测试。	—
FBI_API_BASE_UCR	覆盖 UCR 基础 URL。	https://api.usa.gov/crime/fbi/ucr
FBI_API_BASE_CDE	覆盖 CDE 基础 URL。	https://api.usa.gov/crime/fbi/cde
FBI_REQUEST_TIMEOUT_MS	单次请求超时时间，单位为毫秒。	15000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto（解析为 stateful）。服务在代码中声明为 stateless；设置此项可覆盖该声明。	stateless
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源地址覆盖值。	无
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
MCP_GC_PRESSURE_INTERVAL_MS	可选的、仅限 Bun 的强制 GC 压力间隔（毫秒）。如果持续 HTTP 负载下 RSS 增长，可尝试设为 60000。	0
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_ENDPOINT	用于导出追踪和指标的 OTLP 基础 URL；不会启用日志导出。	无
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	显式指定的 OTLP 日志导出端点；Docker 镜像包含所需的可选对等依赖项。	无

所有可选覆盖项请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # 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 fbi-crime-mcp-server .
docker run --rm -e FBI_API_KEY=your-key -p 3010:3010 fbi-crime-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/fbi-crime-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具、资源并初始化服务。
src/config	使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含 6 个可调用工具和 5 个已禁用的运维条目。
src/mcp-server/resources	已停用的机构／州定义，未注册。
src/services	FBI CDE API 服务，包含响应验证和共享的重试／超时逻辑。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

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

• 处理程序抛出错误，由框架捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 在 src/index.ts 中传递给 createApp() 的数组里注册新工具和资源
• 活跃工具调用 CDE API（/cde/summarized/、/cde/agency/byStateAbbr/、/cde/hate-crime/、/cde/arrest/、/cde/nibrs/、/cde/leoka/）；已停用的定义用 disabledTool 包装，并从 MCP 注册中省略
• 封装 FBI API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。