国家统计局MCP/Agent数据获取工具

项目概述

本项目是一个基于MCP（Model Context Protocol）协议的国家统计局数据获取服务，为AI Agent提供直接访问国家统计局API的功能。项目支持获取各种统计数据，包含关键词搜索、分类浏览、时间维度查询等功能，遵循国家统计局官方API接口最佳实践。

主要特点：

• ✅ 关键词搜索：直接搜索获取指标代码及最新值（推荐用于快速查询）
• ✅ 树形分类：可浏览和递归获取所有分类/指标体系
• ✅ 预遍历数据：提供完整的预遍历分类编码体系，可直接读取使用（减少递归调用）
• ✅ 时间范围：可查询各数据库对应可用时间维度
• ✅ 标准API：遵循国家统计局接口文档的全部规范
• ✅ 容错机制：内置重试逻辑、请求延迟、数据验证等功能

环境要求

• Node.js 18+
• npm or yarn

安装指南

安装所需依赖，请运行以下命令：

npm install

服务启动

启动MCP服务器：

# 构建项目
npm run build

# 启动服务器（STDIO模式 - 适用于Claude Desktop等）
npm start

# 或启动HTTP服务器（端口模式）
node dist/index.js --port 8080

可用工具

search_statistics（推荐）

通过关键词搜索国家统计局指标和数据。可以快速查找指标及其最新值。

• 参数：keyword（必需）- 搜索关键词，如 "GDP"、"人均可支配收入" 等
• 参数：db（可选）- 数据库筛选，空=全部，可选"年度数据"或"季度数据"
• 参数：page（可选）- 页码，从0开始

get_statistics_categories

获取统计指标分类树，返回国家统计局分类体系（第一层）。

• 参数：dbcode（必需）- 数据库代码，wdcode（可选）- 维度代码

get_statistics_leaf_categories

递归获取特定数据库的所有叶子指标节点（分类下全部可查询指标）。

• 参数：dbcode（必需）- 数据库代码

get_statistics_time_options

获取指定数据库可选的时间范围维度。

• 参数：dbcode（必需）- 数据库代码

get_statistics_data

获取国家统计局特定指标的数据。

• 参数：zb（必需）- 指标代码，dbcode（必需）- 数据库代码，sj（可选）- 时间范围

batch_get_statistics

批量获取多个统计指标的数据。

• 参数：queries（必需）- 查询参数数组

模块介绍

• src/index.ts: MCP服务器主入口，实现MCP协议规范
• src/api-client.ts: 国家统计局API交互模块，提供完整的数据获取功能，包括搜索、分类、数据查询等

遵循国家统计局API标准

项目严格实现api_introduce.md中的接口规范，包含：

• 搜索接口 /search.htm 用于关键词查找和快速获取最新值
• 分类接口 /easyquery.htm 用于遍历指标分类树
• 数据接口 /easyquery.htm 用于查询历史时间序列
• 通过 k1 时间戳防缓存参数
• URL编码处理 wds 和 dfwds 参数
• 数据验证与错误处理最佳实践

数据编码对应

• dbcode.json: 存储数据库代码及其相应的名称
• wbcode.json: 维度代码定义
• 预遍历编码数据:
  • npm包中不包含: nbs_data_repository/ （因文件体积较大）
  • 需从GitHub获取: 预先遍历获取的完整的国家统计局分类编码体系（可减少递归调用）
    • 完整数据集在 GitHub 仓库中，请从 GitHub 仓库 下载
    • csnd/, csyd/: 城市统计数据（年度、月度）
    • fsnd/, fsyd/: 分省年度、月度数据
    • hgnd/, hgjd/, hgyd/: 国民经济核算数据（年度、季度、月度）
    • gjnd/, gjyd/, gatnd/, gatyd/: 国际、港澳台统计数据（年度、月度）
    • 每个数据库目录下包含预遍历的分类编码（以JSON文件形式存储）:
      • 如 nbs_data_repository/hgjd/A01.json 包含A01分类下的具体指标
      • 文件内容格式: [{"id": "指标ID", "pid": "父级ID", "name": "指标名", "isParent": 是否为父级}]

为AI Agent的使用

本项目专门设计为MCP服务器，可以直接集成到AI Agent系统中，提供国家统计局数据查询能力。Agent可根据使用场景选择最合适的工具：

• 快速查询：使用 search_statistics 直接通过关键词获取指标和最新值
• 分类浏览：使用 get_statistics_categories 获取分类体系；对于完整指标体系，可优先参考 nbs_data_repository 目录下的预遍历编码文件
• 递归获取：get_statistics_leaf_categories 用于递归获取所有叶子节点（由于已有预遍历数据，此功能使用频率较低）
• 深度查询：使用 get_statistics_time_options 和 get_statistics_data 获取历史序列数据
• 预遍历数据：nbs_data_repository 目录下已预存各类统计数据库的详细分类编码，可直接读取使用，避免实时API递归调用

开发

进行开发时可使用：

npm run dev

使用建议

对于AI Agent开发者，根据使用方式采用不同策略：

npm 包使用（核心库）：

1. 安装: npm install national-stats-mcp
2. 功能: 使用 API 工具进行动态数据查询
3. 使用: search_statistics、get_statistics_data 等
4. 递归调用: 当需要完整分类体系时，使用 get_statistics_leaf_categories

GitHub 仓库使用（完整版本）：

1. 克隆完整仓库:

   git clone https://github.com/Ddhjx-code/notional_data.git

2. 优先使用预遍历数据: 从 nbs_data_repository 目录直接读取已存在的分类编码信息
3. 快速查询: 使用 search_statistics 工具进行关键词搜索
4. 实时数据获取: 使用 get_statistics_data 获取具体统计数据
5. 递归调用: 仅在预遍历数据不满足需求时使用 get_statistics_leaf_categories

预遍历数据优势（当可访问完整数据集时）：

• ✅ 快速访问：无需等待实时API调用和递归遍历
• ✅ 大数据量：包含国家统计局完整分类体系
• ✅ 稳定性好：离线数据访问不受API限制
• ✅ 减少API调用：降低对国家统计局服务器压力

递归API使用场景：

• 临时获取最新指标（若预遍历数据未及时更新）
• 特殊查询需求超出预遍历数据范围
• 在较小环境中仅安装了 npm 包的情况

贡献

欢迎对本代码进行修改。请确保遵循项目的编码标准。

开源协议

MIT License