mcp-statdb 1.3.2

package/llms.txt

@@ -0,0 +1,603 @@
+# mcp_cnbs - 中国国家统计局数据 MCP 服务器
+
+> 为 AI 助手提供中国国家统计局数据查询能力的 MCP (Model Context Protocol) 服务器
+> 
+> 基础地址：https://data.stats.gov.cn | 无需鉴权，公开访问
+
+---
+
+## 🚀 快速开始（必读）
+
+### 核心原则
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ⚠️  最重要：优先使用 cnbs_search 获取数据                    │
+│                                                              │
+│  搜索接口返回的 value 字段有值                                │
+│  cnbs_fetch_series 返回的 value 字段可能为空（API限制）       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 推荐工作流程
+
+```
+场景一：只需最新值（最常见）
+┌─────────────────────────────────────────────────────────┐
+│  cnbs_search(keyword="GDP")                              │
+│     ↓                                                    │
+│  直接获取 result[].value = 最新数据值                    │
+│  一次请求搞定！                                           │
+└─────────────────────────────────────────────────────────┘
+
+场景二：需要历史时间序列
+┌─────────────────────────────────────────────────────────┐
+│  cnbs_search(keyword="GDP")                              │
+│     ↓                                                    │
+│  从 result[].report 解析 zb=A010101                      │
+│     ↓                                                    │
+│  cnbs_fetch_series(setId, metricIds, periods)            │
+│     ↓                                                    │
+│  获取历史数据（注意：value 可能为空）                     │
+└─────────────────────────────────────────────────────────┘
+
+场景三：浏览分类体系
+┌─────────────────────────────────────────────────────────┐
+│  cnbs_fetch_nodes(category="3")  // 年度数据根节点       │
+│     ↓                                                    │
+│  递归下钻获取子节点                                       │
+│     ↓                                                    │
+│  isLeaf=true 的节点即为可查数据的数据集                   │
+└─────────────────────────────────────────────────────────┘
+
+场景四：批量查询多个指标
+┌─────────────────────────────────────────────────────────┐
+│  cnbs_batch_search(keywords=["GDP", "CPI", "人口"])      │
+│     ↓                                                    │
+│  一次性获取多个指标的最新数据                             │
+└─────────────────────────────────────────────────────────┘
+
+场景五：地区/时间对比
+┌─────────────────────────────────────────────────────────┐
+│  cnbs_compare(keyword="GDP", regions=["北京", "上海"])   │
+│     ↓                                                    │
+│  获取地区对比结果                                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📊 数据分类体系
+
+### 分类代码速查表
+
+| 代码 | 分类名称 | 时间粒度 | 典型数据 |
+|------|---------|---------|---------|
+| `1` | 月度数据 | 月 | CPI、PPI、工业增加值 |
+| `2` | 季度数据 | 季 | GDP季度值、PMI |
+| `3` | 年度数据 | 年 | GDP年度值、人口数据 |
+| `5` | 分省季度数据 | 季 | 各省GDP季度值 |
+| `6` | 分省年度数据 | 年 | 各省人口、GDP年度值 |
+| `7` | 其他数据 | - | 特殊统计 |
+| `8` | 主要城市年度数据 | 年 | 主要城市GDP |
+| `9` | 港澳台月度数据 | 月 | 港澳台月度统计 |
+| `10` | 港澳台年度数据 | 年 | 港澳台年度统计 |
+
+---
+
+## ⏰ 时间格式规范
+
+### 年度数据
+
+```
+格式：YYYY
+示例：2024, 2023, 2022
+范围：["2020YY-2024YY"]
+```
+
+### 季度数据
+
+```
+格式：YYYY + 季度标识
+示例：
+  2024A → 2024年第一季度
+  2024B → 2024年第二季度
+  2024C → 2024年第三季度
+  2024D → 2024年第四季度
+
+快捷范围：
+  LAST6  → 最近6个季度
+  LAST12 → 最近12个季度
+  LAST18 → 最近18个季度
+```
+
+### 月度数据
+
+```
+格式：YYYYMM + MM
+示例：
+  202401MM → 2024年1月
+  202412MM → 2024年12月
+范围：["202301MM-202412MM"]
+```
+
+---
+
+## 🗺️ 地区代码
+
+地区代码遵循 GB/T 2260 标准。使用 `cnbs_get_regions` 获取完整列表。
+
+常用地区代码：
+| 地区 | 代码 |
+|------|------|
+| 全国 | 000000000000 |
+| 北京 | 110000000000 |
+| 上海 | 310000000000 |
+| 广东 | 440000000000 |
+| 江苏 | 320000000000 |
+| 浙江 | 330000000000 |
+
+---
+
+## 🛠️ 工具详解
+
+### 1. cnbs_search（推荐优先使用）
+
+**功能**：关键词搜索统计指标，直接获取最新数据值
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| keyword | string | ✅ | 搜索关键词，如 "GDP"、"CPI"、"人口" |
+| pageNum | number | ❌ | 页码，默认1 |
+| pageSize | number | ❌ | 每页数量，默认10 |
+
+**返回字段解读**：
+```json
+{
+  "show_name": "人口出生率 (‰)",
+  "value": "6.77",           // ← 最新数据值！
+  "dt": "2024",              // 时间
+  "dt_name": "2024年",
+  "cid": "ffed4267...",      // 数据集ID（setId）
+  "indic_id": "3d4006d3...", // 指标ID（metricId）
+  "ek": "7a4cb403...",       // 指标唯一键
+  "type_text": "年度数据",
+  "explain": "数据说明..."
+}
+```
+
+**使用示例**：
+```
+// 查询GDP
+cnbs_search(keyword="GDP")
+
+// 查询人口出生率
+cnbs_search(keyword="出生率")
+
+// 查询65岁以上人口
+cnbs_search(keyword="65岁人口")
+```
+
+---
+
+### 2. cnbs_fetch_nodes
+
+**功能**：获取分类树节点，浏览数据分类体系
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| category | string | ✅ | 分类代码：1/2/3/5/6/7/8/9/10 |
+| parentId | string | ❌ | 父节点ID，空则从根节点开始 |
+
+**返回字段解读**：
+```json
+{
+  "_id": "bee83f19...",      // 节点ID
+  "name": "人口抽样调查",     // 节点名称
+  "isLeaf": true,            // true=叶子节点，可查数据
+  "treeinfo_pid": "父节点ID",
+  "treeinfo_level": 4
+}
+```
+
+---
+
+### 3. cnbs_fetch_metrics
+
+**功能**：获取数据集包含的所有指标列表
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| setId | string | ✅ | 数据集ID，来自搜索或节点 |
+| name | string | ❌ | 指标名称过滤 |
+
+---
+
+### 4. cnbs_fetch_series
+
+**功能**：获取时间序列历史数据
+
+**⚠️ 重要警告**：此接口返回的 `value` 字段可能为空！这是国家统计局API的设计限制。
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| setId | string | ✅ | 数据集ID |
+| metricIds | string[] | ✅ | 指标ID数组 |
+| periods | string[] | ✅ | 时间范围数组 |
+| areas | array | ❌ | 地区，默认全国 |
+
+**参数示例**：
+```json
+{
+  "setId": "ffed4267bba24830beea5991d4c9bcfc",
+  "metricIds": ["3d4006d356d94bdd9d75700b9788e230"],
+  "periods": ["2020YY-2024YY"],
+  "areas": [{"text": "全国", "code": "000000000000"}]
+}
+```
+
+---
+
+### 5. cnbs_fetch_end_nodes
+
+**功能**：递归获取指定分类下所有叶子节点
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| category | string | ✅ | 分类代码 |
+
+**警告**：此操作耗时较长，不建议频繁使用
+
+---
+
+### 6. cnbs_batch_search（新）
+
+**功能**：批量搜索多个关键词，一次性获取多个指标数据
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| keywords | string[] | ✅ | 搜索关键词数组 |
+| pageSize | number | ❌ | 每个关键词返回数量，默认5 |
+
+**使用示例**：
+```
+cnbs_batch_search(keywords=["GDP", "CPI", "出生率"])
+// 返回三个关键词各自的搜索结果
+```
+
+---
+
+### 7. cnbs_compare（新）
+
+**功能**：对比不同地区或不同时间的数据
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| keyword | string | ✅ | 搜索关键词 |
+| regions | string[] | ❌ | 对比地区数组，如 ["北京", "上海"] |
+| compareType | string | ❌ | "region"（地区对比）或 "time"（时间对比） |
+| years | string[] | ❌ | 时间对比时的年份数组 |
+
+**使用示例**：
+```
+// 地区对比
+cnbs_compare(keyword="GDP", regions=["北京", "上海", "广东"], compareType="region")
+
+// 时间对比
+cnbs_compare(keyword="GDP", compareType="time", years=["2022", "2023", "2024"])
+```
+
+---
+
+### 8. cnbs_get_regions（新）
+
+**功能**：获取可用的地区代码列表
+
+**参数**：
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| keyword | string | ❌ | 搜索关键词，过滤地区 |
+| level | string | ❌ | 地区级别：province/city/county |
+
+**使用示例**：
+```
+// 获取所有省份
+cnbs_get_regions()
+
+// 搜索包含"江"的省份
+cnbs_get_regions(keyword="江")
+// 返回：江苏、浙江、江西等
+```
+
+---
+
+### 9. cnbs_get_categories（新）
+
+**功能**：获取所有数据分类信息
+
+**参数**：无
+
+**返回**：分类列表，包含代码、名称、时间粒度类型
+
+---
+
+## 🔧 辅助工具
+
+| 工具 | 功能 |
+|------|------|
+| cnbs_get_guide | 获取本指南（建议首次使用时调用） |
+| cnbs_get_cache_stats | 获取缓存统计 |
+| cnbs_format_number | 格式化数字 |
+| cnbs_transform_unit | 单位转换 |
+| cnbs_compute_stats | 计算统计信息 |
+
+---
+
+## 📝 常见查询示例
+
+### 查询GDP
+
+```
+// 方法一：直接搜索（推荐）
+cnbs_search(keyword="GDP")
+// 返回最新GDP值
+
+// 方法二：获取历史数据
+1. cnbs_search(keyword="GDP") → 获取 cid 和 indic_id
+2. cnbs_fetch_series(setId=cid, metricIds=[indic_id], periods=["2020YY-2024YY"])
+```
+
+### 查询CPI
+
+```
+cnbs_search(keyword="CPI")
+cnbs_search(keyword="居民消费价格指数")
+```
+
+### 查询人口数据
+
+```
+cnbs_search(keyword="人口出生率")
+cnbs_search(keyword="65岁人口")
+cnbs_search(keyword="老龄化")
+cnbs_search(keyword="人口总数")
+```
+
+### 查询分省数据
+
+```
+// 先搜索指标
+cnbs_search(keyword="GDP 分省")
+
+// 或浏览分省年度数据分类
+cnbs_fetch_nodes(category="6")
+
+// 获取地区代码
+cnbs_get_regions(keyword="广东")
+```
+
+### 批量查询
+
+```
+cnbs_batch_search(keywords=["GDP", "CPI", "人口", "出生率"])
+```
+
+### 地区对比
+
+```
+cnbs_compare(keyword="GDP", regions=["北京", "上海", "广东"], compareType="region")
+```
+
+---
+
+## ⚠️ 常见问题
+
+### Q1: cnbs_fetch_series 返回的 value 为空？
+
+**原因**：这是国家统计局API的设计限制，不是代码问题。
+
+**解决方案**：
+1. 优先使用 `cnbs_search` 获取最新数据值
+2. 搜索结果的 `value` 字段始终有值
+3. 如需历史数据，可多次搜索不同年份的数据
+
+### Q2: 如何获取指标代码（zb code）？
+
+**方法一（推荐）**：从搜索结果解析
+```
+cnbs_search(keyword="GDP")
+// 返回结果中的 indic_id 或 ek 字段
+```
+
+**方法二**：遍历指标树
+```
+cnbs_fetch_nodes(category="3")
+// 递归下钻直到 isLeaf=true
+```
+
+### Q3: 时间范围怎么写？
+
+```
+年度：["2020YY-2024YY"]
+季度：["2023S1-2024S4"] 或使用快捷范围 ["LAST6"]
+月度：["202301MM-202412MM"]
+```
+
+### Q4: 如何处理分省数据？
+
+```
+// 分省年度数据
+cnbs_fetch_nodes(category="6")
+
+// areas 参数指定省份
+areas: [{"text": "北京市", "code": "110000000000"}]
+
+// 或使用地区查询工具
+cnbs_get_regions(keyword="北京")
+```
+
+### Q5: 如何批量查询多个指标？
+
+```
+cnbs_batch_search(keywords=["GDP", "CPI", "人口"])
+```
+
+### Q6: 如何对比不同地区的数据？
+
+```
+cnbs_compare(keyword="GDP", regions=["北京", "上海"], compareType="region")
+```
+
+---
+
+## 📚 数据指标编码规则
+
+### 指标编码规律
+
+```
+A01       → 一级分类（国民经济核算）
+A0101     → 二级分类
+A010101   → 叶子指标（国内生产总值_当季值）
+A010102   → 叶子指标（国内生产总值_累计值）
+
+规律：
+  - 位数越多层级越深
+  - 末尾奇数 = 当季值/当期值
+  - 末尾偶数 = 累计值
+```
+
+### 常用指标代码
+
+| 代码 | 指标名称 |
+|------|---------|
+| A01 | 国民经济核算 |
+| A010101 | GDP当季值 |
+| A010102 | GDP累计值 |
+| A02 | 人口 |
+| A03 | 就业与工资 |
+| A06 | 固定资产投资 |
+| A08 | 价格指数 |
+
+---
+
+## 📌 最佳实践总结
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. 优先使用 cnbs_search 获取数据                           │
+│     - 一次请求获取最新值                                    │
+│     - 返回的 value 字段有值                                 │
+│                                                              │
+│  2. cnbs_fetch_series 的 value 可能为空                     │
+│     - 这是API限制，不是代码问题                             │
+│     - 适合获取时间序列结构                                   │
+│                                                              │
+│  3. 选择正确的数据分类                                       │
+│     - 年度数据用 category="3"                               │
+│     - 季度数据用 category="2"                               │
+│     - 月度数据用 category="1"                               │
+│                                                              │
+│  4. 时间格式要正确                                          │
+│     - 年度：2024YY                                          │
+│     - 季度：2024S1, 2024S2, ...                             │
+│     - 月度：202401MM                                        │
+│                                                              │
+│  5. 缓存自动管理                                          │
+│     - 指标树变动频率低，自动缓存                           │
+│     - 缓存对多用户共享，减少API调用                        │
+│                                                              │
+│  6. 批量查询用 cnbs_batch_search                            │
+│     - 一次请求获取多个指标                                   │
+│     - 比多次调用 cnbs_search 更高效                         │
+│                                                              │
+│  7. 地区对比用 cnbs_compare                                  │
+│     - 支持地区对比和时间对比                                 │
+│     - 自动整理对比结果                                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔐 鉴权配置
+
+默认无需鉴权，公开访问。可通过 Bearer Token 启用鉴权保护服务。
+
+### 免费演示地址
+
+魔搭 ModelScope 提供免费演示服务，无需鉴权：
+```
+https://mcp.api-inference.modelscope.net/86a1a6b0b08741/mcp
+```
+
+配置示例：
+```json
+{
+  "mcpServers": {
+    "cnbs": {
+      "type": "streamable_http",
+      "url": "https://mcp.api-inference.modelscope.net/86a1a6b0b08741/mcp"
+    }
+  }
+}
+```
+
+魔搭主页：https://modelscope.cn/mcp/servers/thatcoder/cnbs
+
+### 配置方式
+
+| 部署方式 | 配置方法 |
+|---------|---------|
+| 本地 HTTP 模式 | `--auth-token <token>` 参数或 `MCP_CNBS_AUTH_TOKEN` 环境变量 |
+| Cloudflare Workers | `wrangler secret put MCP_CNBS_AUTH_TOKEN` 设置密钥 |
+
+### 使用示例
+
+```bash
+# 本地启动带鉴权
+npx mcp-cnbs --port 12345 --auth-token your-secret-token
+
+# 或使用环境变量
+MCP_CNBS_AUTH_TOKEN=your-secret-token npx mcp-cnbs --port 12345
+```
+
+### 请求格式
+
+启用鉴权后，HTTP 请求需包含 Authorization 头：
+
+```
+Authorization: Bearer your-secret-token
+```
+
+---
+
+## 🌐 技术说明
+
+- **运行环境**: Node.js 18+
+- **协议**: MCP (Model Context Protocol)
+- **数据源**: 中国国家统计局公开API
+- **基础地址**: https://data.stats.gov.cn
+- **鉴权**: 可选 Bearer Token 鉴权
+- **缓存**: 内置内存缓存，支持TTL
+
+---
+
+## ⚡ 速查表
+
+| 需求 | 工具 | 关键参数 |
+|------|------|---------|
+| 关键词找指标+最新值 | cnbs_search | keyword |
+| 浏览分类体系 | cnbs_fetch_nodes | category |
+| 获取指标列表 | cnbs_fetch_metrics | setId |
+| 查历史时间序列 | cnbs_fetch_series | setId, metricIds, periods |
+| 批量获取数据集 | cnbs_fetch_end_nodes | category |
+| 批量搜索多指标 | cnbs_batch_search | keywords |
+| 地区/时间对比 | cnbs_compare | keyword, regions/years |
+| 获取地区代码 | cnbs_get_regions | keyword |
+| 获取分类信息 | cnbs_get_categories | - |

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "mcp-statdb",
+  "version": "1.3.2",
+  "description": "MCP server for China National Bureau of Statistics (CNBS) data access",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "mcp-cnbs": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/index.js --port 12345",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "cf:dev": "wrangler dev",
+    "cf:deploy": "wrangler deploy"
+  },
+  "keywords": [
+    "mcp",
+    "statistics",
+    "china",
+    "nbs",
+    "cnbs",
+    "modelcontextprotocol",
+    "gdp",
+    "cpi",
+    "population"
+  ],
+  "author": "J.K.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icen-ai/mcp-cnbs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/icen-ai/mcp-cnbs/issues"
+  },
+  "homepage": "https://github.com/icen-ai/mcp-cnbs#readme",
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260404.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.19.0",
+    "axios": "^1.8.4",
+    "commander": "^14.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.0",
+    "wrangler": "^4.81.1",
+    "zod": "^3.24.2"
+  }
+}