内容
# KOSIS/NABO 自然语言MCP服务器
KOSIS国家统计和NABOSTATS（国会预算政策处财政经济统计系统）数据的聊天机器人安全查找和使用MCP服务器。
用户可以通过自然语言提问，如“告诉我首尔的人口”、“比较经济增长率和生育率的趋势”等，聊天机器人通过该服务器查找统计表，确认所需的代码和期间，并查询实际的原始数据。
该项目的主要目标是**减少可能错误的统计答案**。MCP服务器不生成最终答案，而是将可在KOSIS/NABO中验证的原始数据和警告信号传递给聊天机器人。最终句子的编写由Gemma等LLM负责，但需要根据值、单位、期间、分母、估计情况和提供机构等依据来回答。
## 初次访问者摘要
- **是做什么的？**
搜索KOSIS和NABO统计表，查找统计表中的地区、性别、年龄、项目代码，并获取实际的统计原始数据。
- **为什么需要？**
统计问题中，“选择哪个表”、“期间是否正确”、“单位是什么”、“分母是什么”非常重要。该服务器有助于在响应中显示这些确认过程，以防止聊天机器人悄悄地给出错误答案。
- **谁可以使用？**
适合使用Gemma等本地LLM聊天机器人、Claude Desktop/Cursor/Windsurf MCP客户端、自动查询公共统计的分析工具的人。
- **最推荐的使用方式是什么？**
先使用`plan_query`分析问题，然后按照`select_table_for_query` → `resolve_concepts` → `query_table` → 需要时`compute_indicator`的顺序进行。
## 主要功能
- 将自然语言问题划分为统计查询过程。
例如：“告诉我首尔的人均GRDP” → 将指标、地区、所需分母、后续工具调用顺序分解。
- 保留包含多个指标的问题。
例如：“经济增长率、人口变化率和总生育率趋势” → 将三个指标分别留在`metrics[]`中，以便单独查找表格。
- 首先使用KOSIS元数据进行验证。
在查询值之前，确认统计表是否实际包含地区轴、年龄轴、项目代码。
- 返回原始数据。
`query_table`不进行求和、平均、解释等操作，而是将KOSIS原始数据连同期间、值、单位、分类信息一起返回。
- 需要计算时也显示限制。
像一人当量、比重、变化率这样的计算由`compute_indicator`执行，但如果需要单位转换或可加性判断，则用`mcp_output_contract`标记来指定调用者的责任。
- 不隐藏失败和模糊性。
数据不存在、期间不匹配、代码错误、估计数据、需要单位解释等状态在响应表面被揭示。
## 支持现状
- Tier A直接查询统计：189个，全部验证
- Tier B自然语言搜索路由：219个
- 同义词/日常语言映射：90个
- 主题浏览：16个主题
- 意图标签：23个
- 默认路由器：`NaturalLanguageRouter`
代表性问题：
```text
告诉我韩国的人口
分析最近5年失业率的趋势
比较中小企业数量和个体工商户数量
比较经济增长率、人口变化率和总生育率的趋势
查找与AI相关的统计数据
查找风力发电装机容量统计数据
告诉我赤字计算公式和所需的统计数据
```
## 术语解释
- **KOSIS**：统计청国家统计门户。多个机构的官方统计表汇集于此。
- **NABO / NABOSTATS**：国会预算政策处财政经济统计系统。提供财政和经济相关的统计表和术语词典。
- **MCP**：使聊天机器人可以调用外部工具的连接方式。
- **统计表**：KOSIS中的数据表。即使是相同的人口，也可能有多个表，如户籍人口、估计人口、人口普查人口。
- **代码映射**：将“首尔”、“女性”、“30岁”等词语转换为KOSIS表中的实际代码的过程。
- **raw rows / 原始数据**：MCP解释前的KOSIS查询结果。
- **marker**：“需要单位解释”、“估计数据”、“数据不存在”等注意信号。
## 0. 准备API密钥
KOSIS查询需要KOSIS OpenAPI认证密钥。该服务器通过环境变量`KOSIS_API_KEY`接收认证密钥。
如果还需要使用NABOSTATS（国会预算政策处财政经济统计系统），则需要设置`NABO_API_KEY`。如果不使用NABO工具，可以省略。
```powershell
$env:KOSIS_API_KEY="YOUR_KOSIS_API_KEY"
$env:NABO_API_KEY="YOUR_NABO_API_KEY"
```
macOS/Linux:
```bash
export KOSIS_API_KEY="YOUR_KOSIS_API_KEY"
export NABO_API_KEY="YOUR_NABO_API_KEY"
```
## 连接MCP前需要决定
MCP连接方式主要有两种。
| 方式 | 推荐对象 | 优点 | 需要 |
| --- | --- | --- | --- |
| 本地stdio MCP | Claude Desktop, Cursor, Windsurf, Claude Code在本地使用 | 设置简单，API密钥不会离开本地 | Python, `KOSIS_API_KEY`, 可选`NABO_API_KEY` |
| 远程HTTP MCP | Claude.ai网页连接器或多人使用同一个服务器 | 可以使用一个URL连接 | Render/Docker等部署环境, 服务器用的`KOSIS_API_KEY`, 可选`NABO_API_KEY`, 可选访问令牌 |
首次使用推荐**方法1. 简单安装后使用短配置**。如果已经有Git克隆并正在开发中，可以使用**方法2. Git克隆后连接到本地路径**。
MCP设置大多具有以下结构。
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "执行服务器的命令",
"args": ["需要时", "参数"],
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
重要点：
- `command`是执行MCP服务器的命令。
- `args`是执行文件后的参数。如果使用已安装的命令，如`kosis-analysis-mcp`，通常不需要。
- `env`中放入KOSIS API密钥。如果还计划使用NABO统计数据，则也放入`NABO_API_KEY`。请勿在查询窗口中直接写入API密钥。
- JSON文件中如果已有其他MCP服务器，则只需在`"mcpServers"`中添加`kosis-analysis`块。
## 方法1. 简单安装后使用短配置
如果要像korean-law MCP一样只写`command`，则需要先安装执行命令。
该命令**不是在Claude或Cursor的聊天窗口中输入，而是在本地计算机的终端中执行**。
打开终端的方法：
| 操作系统 | 在哪里执行？ |
| --- | --- |
| Windows | 从开始菜单打开`PowerShell`或`Windows Terminal`并执行 |
| macOS | 打开`应用程序` > `实用工具` > `终端`并执行 |
| Linux | 打开所用发行版的终端应用并执行 |
执行位置可以是任何文件夹。此方式是从GitHub获取包并安装到Python环境中的命令，因此无需进入特定项目文件夹。
Windows PowerShell示例：
```powershell
pip install "git+https://github.com/jaykim429/korea-statistic-MCP-cginside.git"
```
macOS/Linux终端示例：
```bash
pip install "git+https://github.com/jaykim429/korea-statistic-MCP-cginside.git"
```
如果找不到`pip`命令，可以使用以下方法：
Windows:
```powershell
python -m pip install "git+https://github.com/jaykim429/korea-statistic-MCP-cginside.git"
```
macOS/Linux:
```bash
python3 -m pip install "git+https://github.com/jaykim429/korea-statistic-MCP-cginside.git"
```
确认安装：
```powershell
kosis-analysis-mcp
```
该命令执行MCP stdio服务器，因此正常情况下不会像普通CLI一样输出结果。确认后使用`Ctrl+C`终止。
对于Claude Desktop, Cursor, Windsurf等MCP设置，添加如下内容：
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "kosis-analysis-mcp",
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
如果已有其他MCP服务器，则只需在`"mcpServers"`中添加以下块：
```json
"kosis-analysis": {
"command": "kosis-analysis-mcp",
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
```
如果找不到`kosis-analysis-mcp`命令，请使用以下命令查看安装位置：
```powershell
where kosis-analysis-mcp
```
在macOS/Linux上：
```bash
which kosis-analysis-mcp
```
## 方法2. Git克隆后连接到本地路径
此方式是下载代码并直接连接的方法。首先在终端中切换到工作文件夹。
例如，在Windows中切换到文档文件夹：
```powershell
cd "$HOME\Documents"
```
在macOS/Linux中切换到主文件夹：
```bash
cd ~
```
然后执行以下命令：
Windows PowerShell：
```powershell
git clone https://github.com/jaykim429/korea-statistic-MCP-cginside.git
cd korea-statistic-MCP-cginside
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
```
macOS/Linux：
```bash
git clone https://github.com/jaykim429/korea-statistic-MCP-cginside.git
cd korea-statistic-MCP-cginside
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
确认服务器文件路径：
```powershell
Resolve-Path .\kosis_mcp_server.py
```
Claude Desktop 配置文件位置：
| 操作系统 | 配置文件 |
| --- | --- |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
在Windows中打开：
```powershell
notepad "$env:APPDATA\Claude\claude_desktop_config.json"
```
在macOS中打开：
```bash
open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```
如果文件不存在，可以新建。 在设置文件中添加如下内容：
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "C:\\path\\to\\korea-statistic-MCP-cginside\\.venv\\Scripts\\python.exe",
"args": [
"C:\\path\\to\\korea-statistic-MCP-cginside\\kosis_mcp_server.py"
],
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
保存后完全退出Claude Desktop并重新启动。
在Claude Desktop中确认方法：
1. 重启Claude Desktop。
2. 打开新对话。
3. 检查工具/MCP列表中是否有`kosis-analysis`。
4. 输入类似“告诉我韩国的人口。使用KOSIS MCP确认。”的话。
5. 如果连接正常，Claude应该可以调用`plan_query`等工具。
## 方法3. 如果已有MCP设置
如果已有其他MCP服务器，可以在`"mcpServers"`中添加以下块。注意在现有服务器后添加逗号。
```json
"kosis-analysis": {
"command": "C:\\path\\to\\korea-statistic-MCP-cginside\\.venv\\Scripts\\python.exe",
"args": [
"C:\\path\\to\\korea-statistic-MCP-cginside\\kosis_mcp_server.py"
],
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
```
如果不使用虚拟环境，可以将`command`更改为`"python"`。但必须确保已安装依赖项。
常见错误是逗号位置错误。例如，如果已有服务器，则应如下所示：
```json
{
"mcpServers": {
"other-server": {
"command": "other-command"
},
"kosis-analysis": {
"command": "kosis-analysis-mcp",
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
## 方法4. 在Cursor/Windsurf中使用
Cursor和Windsurf使用相同的MCP JSON结构。
| 应用 | 配置文件 |
| --- | --- |
| Cursor | 项目文件夹中的`.cursor/mcp.json` |
| Windsurf | 项目文件夹中的`.windsurf/mcp.json` |
示例：
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "python",
"args": [
"/path/to/korea-statistic-MCP-cginside/kosis_mcp_server.py"
],
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
在Windows上，路径应为`C:\\path\\to\\...\\kosis_mcp_server.py`格式。
## 方法5. 在Claude Code中作为本地MCP使用
在Claude Code中，可以选择两种方式之一。最简单的方式是安装`kosis-analysis-mcp`命令并作为本地MCP服务器注册。
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "kosis-analysis-mcp",
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
## 方法6. 直接在终端中运行服务器
在连接MCP客户端之前，用于检查服务器是否可以导入。
```powershell
kosis-analysis-mcp
```
该命令执行MCP stdio服务器，因此正常情况下终端中不会像普通CLI一样输出结果。按`Ctrl+C`终止。
语法/导入确认：
```powershell
python -m py_compile kosis_mcp_server.py kosis_curation.py kosis_charts_extra.py
```
直接运行服务器时没有输出为正常现象。MCP stdio服务器是一个服务器，而不是用户在终端中输入命令的CLI。
## 方法7. 远程URL连接器方式
对于Claude.ai网页的自定义连接器或`mcp-remote`，请部署远程HTTP MCP服务器。该存储库包括提供`/mcp` Streamable HTTP端点的`kosis_http_server.py`。
Render部署：
1. 在Render上将此GitHub存储库连接为Web服务。
2. 使用`render.yaml`蓝图。
3. 在Render仪表板上将环境变量`KOSIS_API_KEY`添加为Secret。如果还使用NABO工具，请将`NABO_API_KEY`也添加为Secret。
4. 如果公开，请添加`KOSIS_MCP_AUTH_TOKEN`作为Secret，以保护`/mcp`调用。
5. `render.yaml`配置元缓存和扇出安全装置（`KOSIS_MCP_META_CACHE_TTL`, `KOSIS_MCP_QUERY_TABLE_MAX_FANOUT`, `KOSIS_MCP_QUERY_TABLE_CONCURRENCY`, `KOSIS_MCP_QUERY_TABLE_CALL_TIMEOUT`）。
6. 部署后的URL为`https://<your-service>.onrender.com/mcp`格式。
Docker/Fly.io部署：
```bash
docker build -t kosis-analysis-mcp .
docker run -p 8000:8000 \
-e KOSIS_API_KEY=YOUR_KOSIS_API_KEY \
-e NABO_API_KEY=YOUR_NABO_API_KEY \
-e KOSIS_MCP_AUTH_TOKEN=YOUR_CONNECTOR_TOKEN \
kosis-analysis-mcp
```
本地HTTP执行：
```powershell
kosis-analysis-mcp-http
```
在Claude Desktop上使用`mcp-remote`连接：
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-kosis-mcp.example.com/mcp"
]
}
}
}
```
从直接接收HTTP URL的客户端：
```json
{
"mcpServers": {
"kosis-analysis": {
"url": "https://your-kosis-mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_CONNECTOR_TOKEN"
}
}
}
}
```
远程服务器方式中，请勿将KOSIS/NABO密钥放入URL中，而仅使用环境变量`KOSIS_API_KEY`, `NABO_API_KEY`设置。如果设置了`KOSIS_MCP_AUTH_TOKEN`，则`/mcp`请求需要`Authorization: Bearer ...`或`x-kosis-mcp-token`头。
远程连接确认：
- 在浏览器中直接打开`/mcp`时，即使看不到人类可读的页面也属正常。MCP端点不是普通网页。
- Render免费计划可能会休眠，因此第一个请求可能会很慢。
- 在服务器日志中检查`uvicorn`是否启动成功，以及环境变量`KOSIS_API_KEY`和`NABO_API_KEY`是否已输入。
## 方法8. npx一行执行方式
无需安装，可以直接从GitHub存储库执行。 此方式尝试安装Python依赖项。
```powershell
npx -y github:jaykim429/korea-statistic-MCP-cginside
```
MCP设置：
```json
{
"mcpServers": {
"kosis-analysis": {
"command": "npx",
"args": [
"-y",
"github:jaykim429/korea-statistic-MCP-cginside"
],
"env": {
"KOSIS_API_KEY": "YOUR_KOSIS_API_KEY",
"NABO_API_KEY": "YOUR_NABO_API_KEY"
}
}
}
}
```
## 连接失败时检查
1. 是否输入了`KOSIS_API_KEY`？
- 检查MCP设置中的`env`是否已输入。
- 直接执行时，当前shell中必须有环境变量。
- 如果NABO工具出现`missing_api_key`，请以同样的方式添加`NABO_API_KEY`。
2. `command`路径是否正确？
- Windows: `where kosis-analysis-mcp`
- macOS/Linux: `which kosis-analysis-mcp`
- 如果找不到，请再次执行`pip install "git+https://github.com/jaykim429/korea-statistic-MCP-cginside.git"`。
3. JSON语法是否正确？
- 检查`{}`和`[]`是否已关闭。
- 添加新MCP服务器时，需要在现有服务器后添加逗号。
4. 是否完全重启了Claude Desktop？
- 修改设置文件后，需要退出并重新启动应用程序。
5. 直接运行服务器时是否有输出？
- 正常情况下可以是。`kosis-analysis-mcp`是MCP stdio服务器，不像普通CLI一样输出结果。
6. 是否出现`ModuleNotFoundError`？
- 如果使用Git克隆，请确认是否激活了虚拟环境并执行了`pip install -e .`。
- 检查设置中的`command`是否指向虚拟环境的Python。
7. 远程URL方式中出现401错误？
- 如果服务器设置了`KOSIS_MCP_AUTH_TOKEN`，客户端必须发送`Authorization: Bearer YOUR_CONNECTOR_TOKEN`或`x-kosis-mcp-token`头。
8. KOSIS查询失败？
- 确认API密钥是否正确，是否具有KOSIS OpenAPI使用权限。
- 如果响应中出现`missing_api_key`, `unsupported`, `validation_errors`, `search_empty`等标记，请先参考该标记的说明。
9. NABO查询失败？
- 确认是否设置了`NABO_API_KEY`。
- NABO统计表需要`STATBL_ID`和`DTACYCLE_CD`。首先使用`search_nabo_tables`或`search_stats`查找表格，确认项目代码后调用`explore_nabo_table`，然后调用`query_nabo_table`。
如果需要直接指定Python执行文件，请添加环境变量`KOSIS_PYTHON`。
## 方法9. Claude Code插件
该存储库还包含Claude Code插件结构。
```text
/plugin marketplace add jaykim429/korea-statistic-MCP-cginside
/plugin install kosis-analysis@kosis-analysis-marketplace
```
插件MCP服务器通过存储库的`.mcp.json`启动。在使用之前，请确保终端环境或Claude Code执行环境中已设置`KOSIS_API_KEY`。
```bash
export KOSIS_API_KEY="YOUR_KOSIS_API_KEY"
export NABO_API_KEY="YOUR_NABO_API_KEY"
```
Windows PowerShell:
```powershell
$env:KOSIS_API_KEY="YOUR_KOSIS_API_KEY"
$env:NABO_API_KEY="YOUR_NABO_API_KEY"
```
## 支持方式总结
| 方式 | 当前状态 | 备注 |
| --- | --- | --- |
| `kosis-analysis-mcp` 命令 | 支持 | 使用`pip install git+...`后使用 |
| Git 克隆 + Python stdio | 支持 | 当前默认方式 |
| Claude Desktop 配置 | 支持 | `command` + `args` + `env` |
| Cursor / Windsurf 配置 | 支持 | 相同的MCP JSON结构 |
| Claude Code 本地MCP | 支持 | 使用本地MCP设置方式 |
| Claude Code 插件市场 | 支持 | 包含`.claude-plugin`, `.mcp.json` |
| Claude.ai 网页URL连接器 | 部署后支持 | `kosis_http_server.py`, 包含Render/Docker文件 |
| npx 执行 | 支持 | 使用GitHub包规格，npm正式发布前 |
## 聊天机器人中推荐的调用顺序
使用本地LLM作为MCP客户端时，建议按照以下步骤逐步确认，而不是一次性生成答案。因为统计问题不仅需要“值”正确，还需要“表格、期间、单位、分母、地区代码”等都正确。
1. `plan_query`
用户首先读取问题，计划需要什么指标、地区、期间、分类，并计划调用哪些工具。此时不获取实际值。
2. `select_table_for_query`
选择与问题匹配的KOSIS统计表候选项。例如，如果用户询问“半导体出口”，则可以拒绝没有行业轴的表格。
3. `resolve_concepts`
将“首尔”、“30岁”、“女性”、“大都市”等词语转换为所选统计表的实际代码候选项。
4. `query_table`
使用验证的代码查询KOSIS原始数据。该工具不进行求和、平均、比率计算，而是返回原始数据。
5. `compute_indicator`
需要时执行一人当量、比重、变化率、CAGR等计算。单位转换或“是否可以求和”等解释通过调用者的标记留下。
即使有高速通道，也有区别“由MCP处理到什么程度”。
- 简单的Tier A查询使用`quick_stat`, 时间序列使用`quick_trend`
- 地域比较使用`quick_region_compare`
- 自然语言便利响应由`answer_query`处理。 默认`verbose=false`，返回`data`, `metadata`, `notes`, `diagnostics`等薄响应。
- 复合分析材料使用`analyze_trend`, `stat_time_compare`, `correlate_stats`, `forecast_stat`, `detect_outliers`
- 图表使用`chart_line`, `chart_compare_regions`, `chart_correlation`, `chart_heatmap`, `chart_distribution`, `chart_dual_axis`, `chart_dashboard`
## 示例
聊天机器人可以向用户提出以下自然语言问题:
```text
plan_query("2020年 서울 30대 여성 인구")
plan_query("서울 1인당 GRDP 알려줘")
plan_query("광역시 중 고령화 비중이 가장 빠른 곳")
plan_query("경제성장률, 인구 변화율, 합계출산율 추이")
query_table("101", "DT_1DA7004S", filters={"ITEM": ["T80"], "A": ["00"]}, period_range=["2025", "2025"])
```
用户也可以直接提问，以下是更多示例:
```text
answer_query("최근 기준 중소기업 수와 소상공인 사업체 수를 함께 보여줘")
answer_query("중소기업 사업체수를 시도별로 비교해줘")
answer_query("2020년 서울 중소기업 매출액 알려줘")
answer_query("서울 집값 전월 대비 변화율 알려줘")
answer_query("2019년 대비 2023년 중소기업 매출액 증가율")
answer_query("중소기업 사업체수가 가장 많은 5곳 알려줘")
answer_query("서울 중소기업 매출액이 전국에서 차지하는 비중")
answer_query("서울과 경기 중소기업 사업체수 합계")
answer_query("AI 관련 통계 찾아줘")
answer_query("최근 5년간 실업률 추이 분석해줘")
answer_query("서울 인구 알려줘", verbose=true)
quick_region_compare("중소기업 사업체수")
quick_stat("주택매매가격지수", region="서울", period="2026.03")
detect_outliers("합계출산율", method="detrended_zscore")
indicator_dependency_map("폐업률")
chart_line("고령인구", region="전국", years=5)
```
`plan_query`的响应不会返回实际值，而是返回一个类似以下的程序化响应：
- `status: "planned"`
- `intent`: `single_value`, `trend`, `comparison`, `computed_indicator`等
- `analysis_mode`: `simple_lookup`, `analytical_single_metric`, `composite_analysis`, `needs_clarification`
- `intended_dimensions`: 问题中检测到的`region`, `age`, `sex`, `time`, `industry`等
- `table_required_dimensions`: 候选统计表中必须具备的KOSIS元数据轴含义（`year`, `month`, `quarter`等时间单位作为轴传递，而非作为`time_request.granularity`保留）
- `semantic_dimensions`: LLM需要理解的语义维度（`regions`, `region_group`, `industry`等）
- `concepts`: 后续`resolve_concepts`将转换为代码的自然语言概念
- `metrics`: 问题中请求的指标候选。availability在`select_table_for_query`通过KOSIS元数据验证之前为`unknown`
- `indicator_candidates`: 在明确的多指标问题中，保留每个分段的指标候选。对于单指标问题，不会附加此项。
- `quarantined_metrics`: 因可能导致路由器污染而在执行计划中排除的候选（例如，在`GRDP`问题中混入`R&D投资规模`）
- `analysis_tasks`: `trend`, `rank`, `per_capita`, `share_by_group`, `growth_rate`, `compare_metrics`等后续分析意图
- `evidence_workflow`: `select_table_for_query` → `resolve_concepts` → `query_table` → 如有必要`compute_indicator`
- `next_call`: Gemma可以直接遵循的下一个工具调用模板
- `mcp_output_contract`: 暴露失败/警告标记和机器可读信号。该字段用于内部诊断，不强制最终答案文本。
简而言之，`plan_query`是一个“答案规划书”，而非“答案”。即使`answer`为`null`，也属于正常情况。
对于多指标问题，如果`mcp_output_contract.current_signals.markers_present`中存在`multi_metric_request`，则Gemma会将每个指标视为单独的`select_table_for_query`路径进行处理。只有当KOSIS元数据证明表格相同 时，才会共享同一表格。
`query_table`的响应仅用于原始数据提取：
- `verification_level: "explored_raw"`
- `confidence`: 不是值的质量，而是代码映射和调用条件的验证级别
- `aggregation: "none"`
- `metadata_source`: 使用的KOSIS元数据端点、查询时间、原始URL
- `rows[]`: 返回KOSIS原始行数据，包含期间、值、单位、维度等。`"*"`, `"-"`等非数值和非公开值会作为`value: null`, `value_raw`, `value_numeric`, `missing_reason`进行分割。
- `data_nature`, `period_nature`: 像未来人口预测这样的预测值会标记为`projection_data`，以指示它们不像实际值一样。
`query_table`的默认值为`include_raw=false`。因此，每行只包含`period`, `value`, `unit`, `dimensions`, `value_raw`, `missing_reason`等用于分析的标准化字段。只有当需要KOSIS原始响应字段时，才传递`include_raw=true`。
如果输入错误的`OBJ_ID`或`ITM_ID`，则不会调用KOSIS值，而是返回`status: "unsupported"`，`validation_errors`，`suggested_codes`。
总之，该服务器更倾向于事先告知用户“此代码在该表格中不存在”，“该期间不受支持”，“此数据是预测的”，而非生成看似合理的虚假数据。
## 统计解释注意事项
官方统计数据即使基于不同的表格定义和计算标准，也可能得出不同的数字。在提供答案时，建议向用户说明以下事项：
- 企业数量、营业体数量和自雇者数量是不同的总体。
- 比例、停业率、创业率和生存率需要确认分母和计算机构的公式。
- 相关性、回归和政策效果分析并不自动意味着因果关系。
- “最新”问题是基于KOSIS统计表的最新记录时间来回答的。
- 诸如“2020年”、“2026年3月”、“与去年同期比”、“与上月比”等期间明确的问题会按照指定期间或期间比较进行处理。如果没有数据，则不会用最新值代替。
例如，“韩国GDP增加了吗？”这个问题不仅仅是寻找一个数字的问题。需要确认使用哪个GDP表格，比较期间是与去年同期还是与上季度比较，单位是原始值还是指数。该服务器通过标记和契约指出这些确认点。
## 验证脚本
实时KOSIS API回归验证：
```powershell
$env:KOSIS_API_KEY="YOUR_KOSIS_API_KEY"
python scripts\regression_smoke.py
python scripts\eval_plan_query_pipeline.py
python scripts\eval_gemma_workflow.py
python scripts\comprehensive_api_matrix.py
python scripts\temporal_edge_cases.py
python scripts\natural_language_battery.py --summary-only
```
如果还需要测试NABO工具，请在同一终端设置`NABO_API_KEY`并运行`scripts/eval_tool_contracts.py`：
```powershell
$env:NABO_API_KEY="YOUR_NABO_API_KEY"
python scripts\eval_tool_contracts.py
```
`eval_plan_query_pipeline.py`是Gemma的`plan_query`本地回归测试，目前包含36个测试用例，涵盖以下模式：
- 防止`mcp_output_contract.current_signals`在无指标或澄清状态下的误报。
- 验证`year`, `month`, `quarter`不会流入KOSIS表格轴。
- 确保`simple_lookup` / `analytical_single_metric` / `composite_analysis`模式和`evidence_bundle`的一致性。
- 测试`PPI`, `GRDP`, `CPI`等缩写和日常问题，如“有多少家鸡肉店？”。
- 隔离路由器污染的`GRDP` ↔ `R&D 投资规模`。
- 回归排名、期间范围、多区域比较、公式+排名组合。
- 在多指标问题中同步`metrics[]`, `concepts`, `analysis_tasks[].metrics`。
`eval_gemma_workflow.py`是基于Gemma程序化工作流的评估集，重点评估必要的维度、概念和后续工具序列是否在以下测试案例中保持一致：
- 多轴切片（2020年 서울 30대 여성）。
- 1人あたりGRDP。
- 광역시 고령화 비중。
- 英语查询。
- 缩写词 CPI/GRDP。
- 日常问题，如“多少家鸡肉店？”。
`natural_language_battery.py`是一个仅调用`answer_query`的自然语言测试集，能够一次性验证10多个意图类别（单值、时间序列、增长率、地区比较、Top N、比例、合计、复合、搜索回退、防护和意图不匹配）。可以通过`--group <name>`或`--name <case>`进行过滤。
## 文件构成
- `kosis_mcp_server.py`: MCP服务器和工具定义。
- `kosis_http_server.py`: Streamable HTTP MCP服务器入口。
- `kosis_curation.py`: 自然语言路由器、Tier A/B策划、概念图。
- `kosis_charts_extra.py`: 额外的SVG图表辅助函数。
- `docs/chatbot_integration.md`: Gemma聊天机器人MCP工具清单和一致性规则。
- `scripts/regression_smoke.py`, `scripts/eval_gemma_workflow.py`, `scripts/comprehensive_api_matrix.py`, `scripts/temporal_edge_cases.py`, `scripts/natural_language_battery.py`: 现实API/工作流回归验证脚本。
- `pyproject.toml`: `kosis-analysis-mcp`运行命令和包元数据。
- `package.json`, `bin/`, `scripts/`: npx/npm包装器。
- `.claude-plugin/`, `.mcp.json`, `skills/`: Claude Code插件配置。
- `render.yaml`, `Dockerfile`, `fly.toml.example`: 远程部署示例。
- `requirements.txt`: 运行时依赖。
- `mcp_config.example.json`: MCP客户端配置示例。
- `.env.example`: 环境变量示例。
- `.gitignore`: 默认忽略`artifacts/`，因此不会将其纳入分发或软件包中。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器