uk-police-crime-mcp-server

---

概述

通过 data.police.uk 获取英格兰、威尔士和北爱尔兰的街头犯罪、警方处理结果及拦截与搜查记录。可按坐标、区域、社区或警队搜索，跟踪犯罪案件的处理结果历史，并查找负责某地的警务团队。

工具

工具	说明
ukcrime_list_reference	解码警队 ID、犯罪类别、某警队的社区 ID，以及已发布数据所涵盖的月份和警队
ukcrime_search_crimes	搜索某个月内记录的街头犯罪，或搜索最多 12 个月的范围；可限定区域，并按类别统计数量及列出最新处理结果
ukcrime_search_outcomes	列出某个月内某区域记录的警方处理结果，案件发生时间可为当月或更早
ukcrime_get_crime_outcomes	根据 persistent_id 获取最多 25 起犯罪案件的完整处理结果历史
ukcrime_search_stops	搜索某个月或最多 12 个月范围内某区域或整个警队的拦截与搜查记录，并提供分类统计和筛选条件
ukcrime_find_neighbourhood	查找某个坐标对应的警队和社区警务团队，或按 ID 查询

功能参考

ukcrime_list_reference _工具

• topic：forces、categories、availability 或 neighbourhoods（需要 force）；name_contains 按名称筛选警察机构和街区，month 将 availability 缩小到一行
• availability 返回 latest_month、earliest_month，以及每个月发布了拦截与搜查数据的警察机构；提供 force 时，返回该机构发布和未发布数据的月份
• forces 包含英国交通警察（btp）以及各警察机构已知的覆盖范围 gaps；类型化错误：force_required、unknown_force、invalid_filter

---

ukcrime_search_crimes _工具

• area：point（lat、lng；半径为 1 英里）、polygon（3–2,500 个顶点）、location（location_id）、neighbourhood（force + neighbourhood_id）或 force_unplaced（force：无法定位的犯罪）；可选 month（默认为最新发布月份）、month_from（截至 month 的时间范围，最多 12 个月）和 category（默认为所有类别）
• 返回 total、by_category、by_outcome、最多 10 个 top_locations，以及一页 crimes；其中包含 ukcrime_get_crime_outcomes 所需的 persistent_id；limit 默认为 25，接受 1–10,000，最多应用 200，并以 cap 回显；使用 next_offset 继续获取
• 使用 month_from 时，汇总、分类统计和 top_locations 覆盖整个时间范围，by_month 提供每个月的总数，分页结果按月份从最早到最新排列
• 失败时会附带类型化的 reason，例如 month_not_published、unknown_category 或 area_too_large；如果无法在一次调用中完整获取某个范围，则会失败并返回 range_incomplete（再次调用：已获取的月份会保留在缓存中）或 range_too_large

---

ukcrime_search_outcomes _工具

• 区域选项与 ukcrime_search_crimes 相同，但不包括 force_unplaced；month 指记录结果的月份，category 只统计该类别犯罪的结果
• 返回 total、unfiltered_total、by_category（犯罪类别和数量）、by_outcome（代码、名称、数量）、by_crime_month，以及一页 outcomes，每项都包含对应的犯罪；limit 默认为 20，接受 1–10,000，最多应用 200，并以 cap 回显
• 仅包含警方结果：法院判决结果不会发布；如果某个警察机构未发布任何结果，响应会说明这一点

---

ukcrime_get_crime_outcomes _工具

• persistent_ids：来自 ukcrime_search_crimes 或 ukcrime_search_outcomes 的 64 字符 ID，可作为数组提供，也可作为以逗号或空白字符分隔的字符串提供；数组原始元素最多 1,000 个，去重前最多 1,000 个非空标记，总计最多 128,000 个 UTF-16 代码单元；反社会行为记录不包含此类 ID
• 查询前会验证每个 ID；处理前 25 个唯一 ID，并按顺序返回 remaining_ids，供下一次调用时作为 persistent_ids 传入（全部处理完后为空数组）
• 每项犯罪都会返回其所有结果，按时间从早到晚排列；history_available: false 表示该犯罪没有已发布的历史记录
• 未知 ID 会归入 not_found，查询失败的 ID 会归入 failed；如果一次调用中处理的查询全部失败，则调用本身也会失败

---

ukcrime_search_stops _工具

• area：point、polygon、location、neighbourhood 或 force（该警队发布的所有拦截搜查记录，无论是否标注位置）；可选的 month 和 month_from 与 ukcrime_search_crimes 相同；可对 type、self_defined_ethnicity、officer_defined_ethnicity、outcome、object_of_search、legislation、age_range、gender、outcome_linked_to_object_of_search 或 removal_of_more_than_outer_clothing 设置最多 8 个 filters（最后两项接受 'true'、'false' 或 '(not recorded)'；JSON 布尔值也可用）
• 返回 total、unfiltered_total、unplaced、force_published（对于该区域找到的每个警队——即指定的警队，或在某个点、某个多边形的中心和最外侧顶点，或某个地点的地图点找到的警队——是否都发布了该月或某个时间范围内每个月的拦截搜查数据）、每个可筛选字段的分类统计，以及一页 stops；limit 默认为 15，接受 1–10,000，最多按 200 条应用，并以 cap 回显
• 使用 month_from 时，by_month 会给出每个月的总数和各自的 force_published，因此警队跳过的月份会显示为缺失，而非数量下降；通知会列出每个警队跳过的月份
• 筛选条件会同时缩小所有月份中的分类统计和分页结果：筛选一个字段，并读取另一个字段的分类统计，即可交叉制表
• 已发布的 outcome: false 表示 Nothing found；空白、null 或缺失的结果仍标记为 (not recorded)，与查获率标志无关

---

ukcrime_find_neighbourhood _工具

• 通过 lat + lng 或 force + neighbourhood_id 查找；include 用于选择 priorities、team、events（默认包含这三项）和 boundary
• 查询和搜索 neighbourhood 时会先尝试精确 id；未找到时，会根据缓存的警队列表重试唯一的不区分大小写匹配。若匹配不唯一，则会报错并给出候选 id；结果会回显规范拼写。
• 返回警队、团队的描述、联系渠道和警察局、当前优先事项、警队发布的所有即将举行的活动（按时间从近到远排序），以及搜索工具可接受的多边形字符串形式的边界
• 团队条目仅包含职级和姓名；不会返回个人简介和个人联系方式。覆盖范围外的点会返回 found: false 和 guidance

功能

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

data.police.uk 专属功能：

• 每个位置都是匿名化地图点，覆盖至少八个地址，绝不是犯罪或拦截发生的地点；输出会明确标注这一点
• 在本地验证上游会悄然放宽的内容：未知类别、超出时间范围的月份、与任何 ID 或名称都不匹配的警队（Leicestershire Police 和 leicestershire 均可），以及所选区域不使用的区域字段
• 省略 month 时会搜索最新发布的月份并返回该月份；每项结果的 notice 都会注明各警队数据覆盖缺口的日期和名称
• 即使没有解析出任何警队，覆盖范围查询失败或超时后，仍会保留搜索记录并说明无法检查覆盖范围；覆盖范围未知时，绝不会报告 force_published: true
• 对于大多数区域，一次调用即可获取 12 个月的犯罪或拦截与搜查趋势：month_from 每次获取两个月的数据，并将每个月缓存 15 分钟，因此翻页和重复发送都不会再次请求区域数据；如果大区域的请求超时，则会报错 range_incomplete，重复请求只会获取仍然缺失的月份
• 按 data.police.uk 的速率限制在整个进程范围内控制请求频率，并使用重试和进程内缓存

适合 Agent 使用的输出：

• 每个响应都包含 Open Government Licence 署名；除 ukcrime_list_reference 外，所有工具都会添加 data_note，说明记录能够和不能说明什么
• 总数和明细涵盖所有匹配记录；通过 limit / offset / next_offset 对行进行分页
• 提供带恢复提示的类型化失败原因，以及区分“未发布数据”和“未发生任何事情”的 notice

已知限制

• 仅提供最近 36 个月的数据；更长时间范围的趋势需使用 data.police.uk 上的批量归档数据，本服务不会读取该数据
• 范围最多涵盖 12 个月，且 ukcrime_search_outcomes 一次只能查询一个月：如果某个月的结果近期未被请求过，data.police.uk 可能需要 10–53 秒才能响应
• Greater Manchester Police 不发布犯罪、结果或拦截与搜查数据；在该地区搜索只会返回其他警队或 British Transport Police 的记录
• Northern Ireland 没有结果数据，也没有拦截与搜查数据；除反社会行为外，所有犯罪的结果都带有占位值 Under investigation
• 不会发布 2019 年 6 月之后的法院结果
• 无论类别如何，如果某区域包含超过约 10,000 条记录，data.police.uk 都可能拒绝请求；地点半径固定为一英里，因此人口密集的市中心需要使用小于行政区的多边形
• API 会报告每月发布拦截与搜查数据的警队，但不会报告哪些警队提供了犯罪数据，因此跳过某个月的警队会导致相应区域数据稀少或为空；数量较少或为零可能意味着数据缺失
• 许多拦截记录的结果为空，会显示为 (not recorded)；拦截记录的 datetime 使用 UTC，而月份遵循英国当地时间

入门

公共托管实例

可使用公共实例 https://uk-police-crime.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任何 MCP 客户端连接到该实例：

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

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

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

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

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

或使用 Docker：

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

对于 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+）。
• 无需 API 密钥：data.police.uk 开放使用且无需密钥。

安装

1. 克隆仓库：

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

2. 进入目录：

cd uk-police-crime-mcp-server

3. 安装依赖项：

bun install

配置

该服务本身不读取任何环境变量。它会在整个进程范围内控制请求速率，遵守 data.police.uk 每秒 15 次（突发 30 次）的限制；调用会排队等待轮到自己。如果 data.police.uk 对服务进行速率限制，且 Retry-After 留给调用的时间足以再尝试一次，服务会等待该时间；如果等待时间更长，或速率限制持续时间超过重试期限，则调用会以 rate_limited 失败，并注明等待时间。此服务中的队列繁忙时，调用会以 pacer_shed 失败；上游服务中断时，会以 upstream_unavailable 失败；调用耗尽时间时，会以 retry_deadline_exceeded 失败。这四种情况都可重试；如果已知等待时间，提示会注明该时间。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	auto（.env.example 和 Docker 镜像设为 stateless）
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

常见框架覆盖项请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts），以及搜索工具共用的区域处理逻辑、输入词汇和输出结构。
src/services/police-api	data.police.uk 客户端：请求速率控制器、重试、缓存、上游架构、记录规范化、带日期的覆盖缺口表。
tests/	单元测试和集成测试。

开发指南

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

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 allToolDefinitions（src/mcp-server/tools/definitions/index.ts）中注册新工具；src/index.ts 会将其传递给 createApp()
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

数据：包含根据 Open Government Licence v3.0 授权的公共部门信息。来源：data.police.uk。每个工具响应都附带此归属信息；在注明归属信息的前提下，允许存储、缓存和重新分发数据。本项目独立于 Home Office、data.police.uk 和各警察机关。