Ucdp

@pipeworx/ucdp

乌普萨拉冲突数据计划（UCDP）——自 1989 年以来每个国家的武装冲突伤亡人数、活跃冲突和地理编码暴力事件，数据来自已发布的 UCDP 年度数据集、每月 GED Candidate 版本，以及 UCDP API（需要令牌）。

属于 Pipeworx——一个将 AI Agent 接入 1684+ 个实时数据源的 MCP 网关。

工具

• ucdp_fatalities_summary(country, year? | from?/to?) — 某个国家某年的有组织暴力死亡人数：最佳估计、低值/高值，按国家间冲突、非国家冲突和单方面暴力分类，并区分战斗人员与平民以及列出具名交战双方。可回答“2024 年苏丹战争中有多少人遇难”。
• ucdp_conflicts(country?, year?, intensity?) — 某年活跃的 UCDP/PRIO 武装冲突，包含各方、冲突目标、类型、强度、冲突阶段日期和战斗相关死亡人数。
• ucdp_countries(query?, region?, min_deaths?) — 199 个已编码国家，包含 Gleditsch-Ward 代码、数据覆盖年份和最近年份的死亡人数（按死亡人数排序）。
• ucdp_recent_events(country?, type_of_violence?, min_deaths?, limit?) — 最新每月 GED Candidate 文件中的单起事件（初步数据，当前年份）。
• ucdp_events(country, start?, end?, type_of_violence?, limit?, page?, version?, _apiKey) — 通过 UCDP API 获取 1989 年以来任意日期范围的 GED 事件。需要 API 密钥。

身份验证

前四个工具无需密钥。ucdp_events 仅支持自带密钥：将 UCDP API 访问令牌作为 _apiKey 传入（以 x-ucdp-access-token 标头发送）。这是既定决策，并非缺失功能：Bruce 于 2026-09-03 决定采用 BYOK（fleet #1226），因此 Pipeworx 不会申请平台令牌；未提供令牌时的拒绝消息会提示“需要 API 密钥”，并指向 https://ucdp.uu.se/apidocs。

激活注意事项

UCDP 令牌无法自行获取。自 2025 年起，每次 API 调用都需要令牌；获取令牌需要向 API 维护人员发送电子邮件，说明预期用途（地址和模板见 https://ucdp.uu.se/apidocs）；申请会在 3–5 个工作日内得到答复。没有令牌时，每次对 ucdpapi.pcr.uu.se 的调用都会返回 HTTP 401“需要 API 令牌”——这是供应商的访问限制，并非服务中断。

如果今后重新审议该决定并提供了平台令牌：在网关上设置 PLATFORM_UCDP_TOKEN，并在同一次部署中将 platformKeyEnv: 'PLATFORM_UCDP_TOKEN' 添加到该 pack 的 MCP_PACKS 条目中。如果声明了 platformKeyEnv，但未设置密钥，则该 pack 中的所有工具（包括无需密钥的工具）都会被密钥拦截，无法进行路由。

数据源

• https://ucdp.uu.se/downloads/ — 下载索引。每个隔离环境读取一次，以发现最新的年度版本（organizedviolencecy-<NNN>-csv.zip，每年 6 月重新发布为 vNN.1）和最新的月度 GED Candidate 文件（candidateged/GEDEvent_v<major>_<minor>_<month>.csv）。如果无法读取该页面，则回退到固定版本 v26.1 / 26.0.7。
• https://ucdp.uu.se/downloads/organizedviolencecy/organizedviolencecy-261-csv.zip — Organized Violence Country-Year 数据集（167 KB zip，7,132 行，1989–2025）。为 ucdp_fatalities_summary 和 ucdp_countries 提供数据。
• https://ucdp.uu.se/downloads/ucdpprio/ucdp-prio-acd-261-csv.zip — UCDP/PRIO Armed Conflict Dataset（1946–2025）。
• https://ucdp.uu.se/downloads/brd/ucdp-brd-conf-261-csv.zip — Battle-Related Deaths，冲突级别（1989–2025）。通过 conflict_id + year 与 ACD 联接。
• https://ucdp.uu.se/downloads/candidateged/GEDEvent_v26_0_7.csv — 月度 GED Candidate（约 1.4 MB，包含一个月的初步事件）。不会获取季度文件（GEDEvent_v26_01_26_06.csv，约 8 MB）。
• https://ucdpapi.pcr.uu.se/api/gedevents/ — 通过 API 获取 GED。筛选条件：Country=<GW code>（可指定多个）、StartDate/EndDate（YYYY-MM-DD，按 date_end 匹配）、TypeOfViolence=1|2|3、pagesize + page（从 1 开始）。请求超出 TotalPages 的页码会返回服务器错误，而不是空结果。结果顺序不固定。

注意事项：

• 完整 GED 压缩包（ged261-csv.zip）大小为 39 MB，解压后远超 Worker 的可承载范围——当前月份之前的事件历史需要通过 API 获取。
• UCDP 按历史沿革为国家命名：“Russia (Soviet Union)”、“Yemen (North Yemen)”、“DR Congo (Zaire)”、“Myanmar (Burma)”。解析器接受常用名称和别名（DRC、USA、UK、Côte d'Ivoire、Eswatini、Czechia、Türkiye、Timor-Leste……）以及 Gleditsch-Ward 代码；由于 UCDP 仅为主权国家分配代码，Palestine/Gaza/West Bank 会映射到 Israel。
• sb_dyad_names / ns_dyad_names / os_dyad_names 在一个 CSV 字段中以 ; 分隔。
• 所有 UCDP 计数都采用每个冲突方组合每年 25 人死亡的纳入门槛；存在真实但分散暴力的国家可能显示为零。

快速开始

添加到 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "ucdp": {
      "url": "https://gateway.pipeworx.io/ucdp/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/ucdp/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于上表所列：目前，单个工具包端点除了该工具包自身的工具，还会列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，是当天情况的权威依据。

这是有意设计的，并非意外复用。这些元工具让限定范围的连接也能回答本工具包未涵盖的问题——通过可跨整个目录路由的 ask_pipeworx，无需再添加第二个 MCP 服务。目前无法挂载不包含这些元工具的工具包端点；如果额外的架构定义占用的上下文比路由功能带来的价值更大，请连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出每个工具包的所有工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会接入同一个网关和相同的 1684+ 个数据源。唯一的区别是直接列出哪些工具包的工具；通过任一入口，ask_pipeworx 都可以访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/ucdp_fatalities_summary \
  -H 'Content-Type: application/json' \
  -d '{"country":"Sudan","year":2024}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/ucdp_fatalities_summary。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行，无需 Pipeworx 账户，也无需经过网关往返：

{
  "mcpServers": {
    "ucdp": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-ucdp"]
    }
  }
}

也可以直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-ucdp

它通过 stdin/stdout 使用 MCP 通信，并针对仅限此软件包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接所添加的任何共享元工具。相同的源代码，相同的工具，无需 ask_pipeworx 路由。

使用 ask_pipeworx

你也可以用通俗的英语提问，而不是直接调用工具——这既适用于上方的软件包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Ucdp data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT