内容
# WID MCP 服务器
非官方本地 MCP 服务器，用于实时查询 [世界不平等数据库](https://wid.world/)。
该服务器**不**捆绑或重新分发 WID 数据集。它是一个小型适配器，向 WID 请求当前数据，并将结构化行返回给 MCP 客户端。
## 为什么在不捆绑数据的情况下有效
默认情况下，服务器使用官方 WID R 包：
```text
客户端 -> WID MCP -> 本地 R 包 `wid` -> WID 数据
```
这保持了该存储库的清洁：
- 没有提交 WID 数据集。
- 没有提交 WID 内部凭证。
- 用户获得与官方 R 包公开的访问路径相同。
如果您有 WID API 凭证，服务器也可以使用直接 API 模式。
## 示例
询问您的 MCP 客户端：
> 1980 年至今巴西的财富/收入比率是多少？
MCP 可以调用：
```json
{
"country": "巴西",
"metric": "财富/收入比率",
"start_year": 1980
}
```
服务器将该请求映射到：
- 国家：`巴西` -> `BR`
- 指标：`wealth_income_ratio` -> `wnweal_p0p100_999_i`
- 输出：干净的行，包括年份、值、单位（如果有）和外推标志（如果有）
对于不太明显的提示，请要求 MCP 先解析：
```json
{
"country": "巴西",
"query": "前 1% 的税前收入份额"
}
```
`wid_resolve_metric` 仅在置信度高时返回一个确切的 WID 变量代码。如果提示很宽泛，例如 `income`，它返回候选变量而不是猜测。
对于广泛的提示，AI 客户端应传递从对话中提取的简短上下文：
```json
{
"country": "巴西",
"query": "收入",
"context": "用户正在比较不同国家的平均收入水平。"
}
```
这给了 MCP 足够的信息来解释 `income` 为平均税前国民收入，适用于平等分配的成年人。响应包括解释和替代方案，以便调用者可以披露或修订选择。
如果上下文表明用户正在研究顶层集中度，则解析器会转向收入份额变量。 如果上下文仍然不足，解析器会返回一个聚焦的澄清问题。
## 世界地区默认值
WID 世界聚合使用带有货币后缀的地区代码：
- `WO-PPP`：以购买力平价（PPP）计算的世界聚合。
- `WO-MER`：以市场汇率计算的世界聚合。
诸如 `World`、`global`、`worldwide` 和 `whole world` 之类的广泛国家别名默认为 `WO-MER`，这是市场价值的金融权力、美元资产负债表和全球资产市场比较的更好默认值。
当国家是世界别名且提示或 `context` 清楚地指向购买力比较时，服务器解析为 `WO-PPP` 而不是。 示例包括 `购买力平价`、`实际收入`、`生活水平`、`本地购买力` 和 `人们可以购买的东西`。
调用者可以通过显式传递 `WO-PPP` 或 `WO-MER` 来绕过此解析器。
## 工具
- `wid_get_series`：通过自然语言指标、内置别名或确切的 WID 变量代码获取系列。 可选的 `context` 帮助使用对话上下文解析广泛的提示。
- `wid_search_metrics`：在 WID 代码语义和实时国家可用性方面搜索自然语言指标文本。
- `wid_resolve_metric`：在置信度高时，将自然语言指标解析为一个确切的 WID 变量代码。 返回解释假设、替代方案和澄清问题（如果有）。
- `wid_search_indicators`：发现国家和指标的可用 WID 变量组合。
- `wid_fetch_data`：获取确切的 WID 变量代码。
- `wid_get_metadata`：获取单位、来源、方法、质量和描述元数据。
- `wid_explain_codes`：解释内置别名和 WID 代码结构。
## 指标解析工作原理
WID 变量代码编码：
```text
系列类型 + 概念 _ 百分位 _ 年龄 _ 人口
```
例如，`sptinc_p99p100_992_j` 表示：
- `s`：份额
- `ptinc`：税前国民收入
- `p99p100`：前 1%
- `992`：成年人
- `j`：平等分配成年人
服务器使用 WID 的公共代码结构作为字典，然后根据请求的国家验证可能的变量并检查 WID 的可用性。 它仅为最佳候选变量获取元数据，因此不会下载或存储 WID 数据集。
如果 `wid_get_series` 解析或接收到特定的变量代码，但该确切的组合为请求的年份窗口返回没有行，则它会尝试最近可用的相同概念变量。 相同概念的备用方案意味着指标和百分位保持不变，而年龄或人口单位可能会发生变化。 响应包括一个 `fallback` 对象，解释请求的 代码、选择的 代码和更改的维度。 服务器不会静默地切换到不同的指标或百分位。
## 上下文和澄清
MCP 服务器无法自动查看完整的聊天历史记录。 当用户的指标很宽泛时，AI 客户端应传递一个简短的 `context` 字符串。
好的上下文示例：
- `用户正在比较不同国家的平均收入水平。`
- `用户正在研究前 1% 的税前收入份额。`
- `用户正在询问收入不平等问题，但尚未选择基尼系数或收入份额。`
有了足够的上下文，解析器获取可能的变量并返回假设。 对于平均收入上下文，这些假设是:
- 收入意味着平均税前国民收入
- 百分位意味着整个成年人口
- 年龄意味着成年人
- 人口单位意味着平等分配成年人
在没有足够上下文的情况下，广泛的提示需要澄清。 例如，`收入不平等` 可以指基尼系数、收入份额、底部收入份额或顶部与底部的比率，因此解析器返回替代方案而不是沉默地选择。
`assumption_policy` 仍然被接受以保持向后兼容性，但新客户端应更喜欢 `context`。
## 设置
安装 Node 依赖项并构建：
```bash
npm install
npm run build
```
安装官方 WID R 包：
```r
install.packages("wid")
```
默认后端是 `auto`：
- 如果设置了 `WID_API_KEY_BASE64` 或 `WID_API_KEY_HEX`，则使用直接 API 模式。
- 否则使用官方 R 包模式。
您可以强制使用 R 模式：
```bash
export WID_BACKEND=r
```
如果 `Rscript` 不在您的 `PATH` 上，请设置：
```bash
export WID_RSCRIPT_BIN="/path/to/Rscript"
```
## 可选的直接 API 模式
直接 API 模式是可选的，需要 WID API 凭证：
```bash
export WID_BACKEND=api
export WID_API_KEY_BASE64="..."
# 或
export WID_API_KEY_HEX="..."
```
使用官方 R 包后端时，不需要 API 凭证。
## MCP 配置
使用 R 模式的示例 stdio 配置：
```json
{
"mcpServers": {
"wid": {
"command": "node",
"args": ["/path/to/wid-mcp-server/dist/index.js"],
"env": {
"WID_BACKEND": "r"
}
}
}
}
```
使用自定义 `Rscript` 路径的示例：
```json
{
"mcpServers": {
"wid": {
"command": "node",
"args": ["/path/to/wid-mcp-server/dist/index.js"],
"env": {
"WID_BACKEND": "r",
"WID_RSCRIPT_BIN": "/usr/local/bin/Rscript"
}
}
}
}
```
## 烟雾测试
安装官方 R 包后：
```bash
npm run smoke
```
烟雾测试获取巴西的 `wealth_income_ratio` 从 1980 年开始，并打印一个简洁的 JSON 样例。
## 开发
```bash
npm test -- --run
npm run build
```
单元测试使用伪造的 WID 响应。 烟雾脚本是实时 WID 检查。
## 数据源
数据来自 [WID.world](https://wid.world/)，一个由世界不平等实验室和合作者维护的开放访问不平等数据库。
有用的 WID 参考资料：
- [WID 数据页面](https://wid.world/data/)
- [WID 代码词典](https://wid.world/codes-dictionary/)
- [WID 方法论](https://wid.world/methodology/)
- [官方 WID R 包](https://cloud.r-project.org/package=wid)
该项目与 WID.world 或世界不平等实验室无关，也不由其支持或维护。
