npm - national-stats-mcp - Versions diffs - 1.0.2 → 1.1.0 - Mend

national-stats-mcp 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +46 -2
package/dist/api-client.js +14 -7
package/dist/index.js +1 -1
package/national-stats-mcp-1.1.0.tgz +0 -0
package/package.json +1 -1
package/zb.json +0 -226

package/README.md CHANGED Viewed

@@ -6,6 +6,7 @@
 主要特点：
 - ✅ 关键词搜索：直接搜索获取指标代码及最新值（推荐用于快速查询）
 - ✅ 树形分类：可浏览和递归获取所有分类/指标体系
+- ✅ 预遍历数据：提供完整的预遍历分类编码体系，可直接读取使用（减少递归调用）
 - ✅ 时间范围：可查询各数据库对应可用时间维度
 - ✅ 标准API：遵循国家统计局接口文档的全部规范
 - ✅ 容错机制：内置重试逻辑、请求延迟、数据验证等功能
@@ -76,15 +77,27 @@ node dist/index.js --port 8080
 ## 数据编码对应
 - `dbcode.json`: 存储数据库代码及其相应的名称
-- `zb.json`: 包含用于查询不同类型国家数据的类别和子类别代码
 - `wbcode.json`: 维度代码定义
+- **预遍历编码数据**:
+  - **npm包中不包含**: `nbs_data_repository/` （因文件体积较大）
+  - **需从GitHub获取**: 预先遍历获取的完整的国家统计局分类编码体系（可减少递归调用）
+    - 完整数据集在 GitHub 仓库中，请从 [GitHub 仓库](https://github.com/Ddhjx-code/notional_data) 下载
+    - `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` 或 `get_statistics_leaf_categories` 查看指标体系
+- **分类浏览**：使用 `get_statistics_categories` 获取分类体系；对于完整指标体系，可优先参考 `nbs_data_repository` 目录下的预遍历编码文件
+- **递归获取**：`get_statistics_leaf_categories` 用于递归获取所有叶子节点（由于已有预遍历数据，此功能使用频率较低）
 - **深度查询**：使用 `get_statistics_time_options` 和 `get_statistics_data` 获取历史序列数据
+- **预遍历数据**：`nbs_data_repository` 目录下已预存各类统计数据库的详细分类编码，可直接读取使用，避免实时API递归调用
 ## 开发
 进行开发时可使用：
@@ -92,6 +105,37 @@ node dist/index.js --port 8080
 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. **克隆完整仓库**:
+   ```bash
+   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 包的情况
 ## 贡献
 欢迎对本代码进行修改。请确保遵循项目的编码标准。

package/dist/api-client.js CHANGED Viewed

@@ -16,15 +16,16 @@ class StatsApiClient {
      * 搜索指标
      */
     async search(keyword, db = '', page = 0) {
-        const params = new URLSearchParams({
-            s: encodeURIComponent(keyword),
+        // 使用 axios 的 params 选项来避免编码问题
+        const params = {
+            s: keyword, // 让 axios 正确处理编码
             m: 'searchdata',
-            db: encodeURIComponent(db),
+            db,
             p: page.toString(),
-        });
-        const searchUrl = `${this.baseUrl}/search.htm?${params}`;
+        };
+        console.error(`GET Request URL (base): ${this.baseUrl}/search.htm with params:`, JSON.stringify(params));
         try {
-            const response = await axios_1.default.get(searchUrl);
+            const response = await axios_1.default.get(`${this.baseUrl}/search.htm`, { params });
             return response.data;
         }
         catch (error) {
@@ -69,6 +70,8 @@ class StatsApiClient {
             dbcode,
             wdcode
         };
+        console.error(`POST Request URL: ${this.baseUrl}/easyquery.htm`);
+        console.error(`POST Request Body:`, JSON.stringify(params));
         try {
             const response = await axios_1.default.post(`${this.baseUrl}/easyquery.htm`, new URLSearchParams(params));
             return response.data;
@@ -105,7 +108,7 @@ class StatsApiClient {
                 }
                 catch (error) {
                     retries++;
-                    console.log(`Category request failed for node ${nodeId}, attempt ${retries}/${maxRetries}.`);
+                    console.error(`Category request failed for node ${nodeId}, attempt ${retries}/${maxRetries}.`);
                     if (retries >= maxRetries) {
                         throw error;
                     }
@@ -127,6 +130,8 @@ class StatsApiClient {
             dbcode,
             wdcode
         };
+        console.error(`POST Request URL: ${this.baseUrl}/easyquery.htm`);
+        console.error(`POST Request Body:`, JSON.stringify(params));
         try {
             const response = await axios_1.default.post(`${this.baseUrl}/easyquery.htm`, new URLSearchParams(params));
             return response.data;
@@ -152,6 +157,7 @@ class StatsApiClient {
             k1: Date.now(), // 添加时间戳防止缓存
             h: 1
         };
+        console.error(`GET Request URL: ${this.baseUrl}/easyquery.htm with params:`, JSON.stringify(params));
         try {
             const response = await axios_1.default.get(`${this.baseUrl}/easyquery.htm`, { params });
             return response.data;
@@ -180,6 +186,7 @@ class StatsApiClient {
             k1: Date.now(), // 添加时间戳防止缓存
             h: 1
         };
+        console.error(`GET Request URL: ${this.baseUrl}/easyquery.htm with params:`, JSON.stringify(params));
         try {
             const response = await axios_1.default.get(`${this.baseUrl}/easyquery.htm`, { params });
             return response.data;

package/dist/index.js CHANGED Viewed

@@ -9,7 +9,7 @@ const api_client_1 = require("./api-client");
 const zod_1 = require("zod");
 const commander_1 = require("commander");
 // 获取版本号，这里使用package.json中的版本
-const VERSION = '1.0.0';
+const VERSION = '1.0.2';
 // 创建API客户端实例
 const apiClient = new api_client_1.StatsApiClient();
 // 创建MCP服务器

package/national-stats-mcp-1.1.0.tgz ADDED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "national-stats-mcp",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "MCP server for accessing National Bureau of Statistics data",
   "main": "dist/index.js",
   "bin": {

package/zb.json DELETED Viewed

@@ -1,226 +0,0 @@
-[
-    {
-        "dbcode": "hgnd",
-        "id": "A01",
-        "isParent": true,
-        "name": "综合",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A02",
-        "isParent": true,
-        "name": "国民经济核算",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A03",
-        "isParent": true,
-        "name": "人口",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A04",
-        "isParent": true,
-        "name": "就业人员和工资",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A05",
-        "isParent": true,
-        "name": "固定资产投资和房地产",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A06",
-        "isParent": true,
-        "name": "对外经济贸易",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A07",
-        "isParent": true,
-        "name": "能源",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A08",
-        "isParent": true,
-        "name": "财政",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A09",
-        "isParent": true,
-        "name": "价格指数",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0A",
-        "isParent": true,
-        "name": "人民生活",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0B",
-        "isParent": true,
-        "name": "城市概况",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0C",
-        "isParent": true,
-        "name": "资源和环境",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0D",
-        "isParent": true,
-        "name": "农业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0E",
-        "isParent": true,
-        "name": "工业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0F",
-        "isParent": true,
-        "name": "建筑业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0G",
-        "isParent": true,
-        "name": "运输和邮电",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0H",
-        "isParent": false,
-        "name": "社会消费品零售总额",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0I",
-        "isParent": true,
-        "name": "批发和零售业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0J",
-        "isParent": true,
-        "name": "住宿和餐饮业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0K",
-        "isParent": true,
-        "name": "旅游业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0L",
-        "isParent": true,
-        "name": "金融业",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0M",
-        "isParent": true,
-        "name": "教育",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0N",
-        "isParent": true,
-        "name": "科技",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0O",
-        "isParent": true,
-        "name": "卫生",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0P",
-        "isParent": true,
-        "name": "社会服务",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0Q",
-        "isParent": true,
-        "name": "文化",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0R",
-        "isParent": true,
-        "name": "体育",
-        "pid": "",
-        "wdcode": "zb"
-    },
-    {
-        "dbcode": "hgnd",
-        "id": "A0S",
-        "isParent": true,
-        "name": "公共管理、社会保障及其他",
-        "pid": "",
-        "wdcode": "zb"
-    }
-]