national-stats-mcp 1.0.2 → 1.2.0

package/README.md

@@ -1,11 +1,21 @@
 # 国家统计局MCP/Agent数据获取工具
 
 ## 项目概述
-本项目是一个基于MCP（Model Context Protocol）协议的国家统计局数据获取服务，为AI Agent提供直接访问国家统计局API的功能。项目支持获取各种统计数据，包含关键词搜索、分类浏览、时间维度查询等功能，遵循国家统计局官方API接口最佳实践。
+本项目是一个基于MCP（Model Context Protocol）协议的国家统计局数据获取服务，为AI Agent提供直接访问国家统计局API的功能。项目**同时支持新版API (V2.0)和旧版API**，支持获取各种统计数据，包含关键词搜索、分类浏览、时间维度查询等功能。
 
-主要特点：
+### 🆕 新版 API V2.0 (2026.03.27更新)
+新版API采用UUID标识符架构，具有以下特点：
+- ✅ **UUID标识**: 使用UUID作为唯一标识符，摒弃旧的层级代码系统
+- ✅ **三步查询**: 树形导航 → 指标元数据 → 批量取值
+- ✅ **时间分片**: 同一指标按5年或统计制度变革周期分割，支持更精细的数据管理
+- ✅ **批量查询**: 支持一次性查询多个指标、多个时间点数据
+- ✅ **缓存优化**: 内置智能缓存机制，提升查询效率
+- ✅ **完整元数据**: 包含统计口径说明、单位信息等关键元数据
+
+### 旧版 API (向后兼容)
 - ✅ 关键词搜索：直接搜索获取指标代码及最新值（推荐用于快速查询）
 - ✅ 树形分类：可浏览和递归获取所有分类/指标体系
+- ✅ 预遍历数据：提供完整的预遍历分类编码体系，可直接读取使用（减少递归调用）
 - ✅ 时间范围：可查询各数据库对应可用时间维度
 - ✅ 标准API：遵循国家统计局接口文档的全部规范
 - ✅ 容错机制：内置重试逻辑、请求延迟、数据验证等功能
@@ -61,12 +71,129 @@ node dist/index.js --port 8080
 批量获取多个统计指标的数据。
 - 参数：`queries`（必需）- 查询参数数组
 
+## 🆕 新版 API V2.0 使用指南
+
+### 核心概念
+
+新版API引入以下关键概念：
+
+| 标识符 | 说明 |
+|--------|------|
+| **pid** | 父节点ID，用于在目录树中向下展开 |
+| **cid** | 数据集ID，代表一个叶子节点（特定指标+地区+时间段） |
+| **indicatorId** | 具体指标ID，代表数据集中的某一列 |
+| **时间分片** | 同一指标按时间分成多个cid（如2021-2025, 2026-至今） |
+
+### 新版API客户端使用示例
+
+```typescript
+import { NewStatsApiClient, CategoryCode } from './src/api-client';
+
+// 创建客户端实例
+const client = new NewStatsApiClient();
+
+// 方式一：一步到位查询（推荐）
+async function quickQuery() {
+  const result = await client.searchAndGet(
+    'CPI',                    // 关键词
+    '居民消费价格指数',        // 指标名称（可选）
+    '202601MM',               // 起始时间（可选）
+    '202603MM'                // 结束时间（可选）
+  );
+  
+  console.log('数据集ID:', result.cid);
+  console.log('指标信息:', result.indicator);
+  console.log('数据:', result.data);
+}
+
+// 方式二：分步查询（适合复杂场景）
+async function stepByStep() {
+  // 1. 搜索定位数据集
+  const searchResults = await client.search({ 
+    search: 'GDP',
+    pageSize: 10 
+  });
+  
+  // 2. 获取树结构（遍历分类）
+  const treeNodes = await client.getTree({
+    code: CategoryCode.MONTHLY,  // 月度数据
+    pid: ''  // 根节点
+  });
+  
+  // 3. 获取指标列表
+  const indicators = await client.getIndicators({
+    cid: 'your-cid-here'
+  });
+  
+  // 4. 查询数据
+  const data = await client.getData({
+    cid: 'your-cid-here',
+    indicatorIds: ['indicator-id-1', 'indicator-id-2'],
+    das: [{ text: '全国', value: '000000000000' }],
+    dts: ['202601MM-202612MM']
+  });
+}
+
+// 方式三：获取所有叶子节点（慎用，耗时）
+async function getAllLeafs() {
+  const leafs = await client.getAllLeafNodes(CategoryCode.MONTHLY);
+  console.log(`共找到 ${leafs.length} 个数据集`);
+}
+```
+
+### 时间编码格式
+
+新版API使用特定的时间编码格式：
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 月度 | YYYYMM + MM | 202602MM (2026年2月) |
+| 季度 | YYYYQ + SS | 20254SS (2025年第4季度) |
+| 年度 | YYYY + YY | 2025YY (2025年) |
+| 范围 | Start-End | 202601MM-202612MM |
+
+### 分类代码
+
+```typescript
+enum CategoryCode {
+  MONTHLY = '1',            // 月度数据
+  QUARTERLY = '2',          // 季度数据
+  YEARLY = '3',             // 年度数据
+  PROVINCE_QUARTERLY = '5', // 分省季度
+  PROVINCE_YEARLY = '6',    // 分省年度
+  OTHER = '7',              // 其他/普查
+}
+```
+
+### 最佳实践
+
+1. **优先使用搜索接口**: 用 `search()` 快速定位cid，避免全量遍历树
+2. **处理时间分片**: 同一指标可能有多个cid，需按时间拼接数据
+3. **批量请求**: `getData()` 支持多个indicatorIds，一次请求获取多个指标
+4. **关注元数据**: 查看indicator的`i_mark`字段了解统计口径
+5. **利用缓存**: 客户端内置缓存，树结构和指标列表会自动缓存
+
 ## 模块介绍
 - `src/index.ts`: MCP服务器主入口，实现MCP协议规范
-- `src/api-client.ts`: 国家统计局API交互模块，提供完整的数据获取功能，包括搜索、分类、数据查询等
+- `src/api-client.ts`: 国家统计局API交互模块，提供完整的数据获取功能
+  - **NewStatsApiClient**: 新版API V2.0客户端（推荐）
+  - **StatsApiClient**: 旧版API客户端（向后兼容）
+- `src/types.ts`: 完整的类型定义，包含新旧两版API的数据结构
 
 ## 遵循国家统计局API标准
-项目严格实现api_introduce.md中的接口规范，包含：
+
+### 新版 API V2.0
+项目严格实现新版API接口规范：
+- 搜索接口 `/external/query` 用于关键词搜索和快速定位cid
+- 树遍历接口 `/new/queryIndexTreeAsync` 用于浏览分类树和获取cid
+- 指标查询接口 `/new/queryIndicatorsByCid` 用于获取指标列表
+- 数据查询接口 `/getEsDataByCidAndDt` 用于批量获取时间序列数据
+- 内置缓存机制：树结构24小时，指标列表12小时
+- UUID标识符系统和时间分片机制
+- 完整的错误处理和重试逻辑
+
+### 旧版 API (向后兼容)
+项目严格实现旧版API接口规范：
 - 搜索接口 `/search.htm` 用于关键词查找和快速获取最新值
 - 分类接口 `/easyquery.htm` 用于遍历指标分类树
 - 数据接口 `/easyquery.htm` 用于查询历史时间序列
@@ -76,15 +203,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 +231,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.d.ts

@@ -39,7 +39,7 @@ export interface StatsSearchResult {
         report: string;
     }>;
 }
-export interface SearchResponse {
+export interface ParsedSearchResult {
     name: string;
     value: string;
     time: string;
@@ -80,7 +80,7 @@ export declare class StatsApiClient {
     /**
      * 解析搜索结果
      */
-    parseSearchResult(result: StatsSearchResult): SearchResponse[];
+    parseSearchResult(result: StatsSearchResult): ParsedSearchResult[];
     /**
      * 获取指标分类树
      */
@@ -118,4 +118,69 @@ export declare class StatsApiClient {
         error?: string;
     }>>;
 }
+import { TreeNode, Indicator, DataQueryParams, SearchItem, TreeQueryParams, IndicatorQueryParams, SearchQueryParams, CategoryCode, NewApiClientConfig, DataPoint } from './types';
+/**
+ * 新版国家统计局API客户端 (V2.0)
+ * 基于UUID标识符的新架构
+ */
+export declare class NewStatsApiClient {
+    private baseUrl;
+    private timeout;
+    private rootId;
+    private treeCache;
+    private indicatorsCache;
+    private readonly DEFAULT_TREE_TTL;
+    private readonly DEFAULT_INDICATORS_TTL;
+    constructor(config?: NewApiClientConfig);
+    /**
+     * 搜索数据集
+     * 用于快速定位 cid
+     */
+    search(params: SearchQueryParams): Promise<SearchItem[]>;
+    /**
+     * 获取树结构
+     * 用于遍历目录树,获取叶子节点(cid)
+     */
+    getTree(params: TreeQueryParams): Promise<TreeNode[]>;
+    /**
+     * 递归获取所有叶子节点(cid)
+     * 注意:此方法耗时较长,慎用
+     */
+    getAllLeafNodes(code: CategoryCode): Promise<TreeNode[]>;
+    /**
+     * 获取指标列表
+     * 根据 cid 获取所有可用指标
+     */
+    getIndicators(params: IndicatorQueryParams): Promise<Indicator[]>;
+    /**
+     * 查询数据
+     * 批量获取多个指标、多个时间点的数据
+     */
+    getData(params: DataQueryParams): Promise<DataPoint[]>;
+    /**
+     * 辅助方法: 搜索并获取数据
+     * 一步到位:搜索关键词 -> 获取cid -> 获取指标 -> 查询数据
+     */
+    searchAndGet(keyword: string, indicatorName?: string, startTime?: string, endTime?: string): Promise<{
+        cid: string;
+        indicator: Indicator;
+        data: DataPoint[];
+    }>;
+    /**
+     * 辅助方法: 从 globalid 提取 cid (最后一段)
+     */
+    private extractCidFromGlobalId;
+    /**
+     * 清除所有缓存
+     */
+    clearCache(): void;
+    /**
+     * 设置根节点ID
+     */
+    setRootId(rootId: string): void;
+    /**
+     * 获取当前根节点ID
+     */
+    getRootId(): string;
+}
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StatsApiClient = void 0;
+exports.NewStatsApiClient = exports.StatsApiClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 // 国家统计局API客户端
 class StatsApiClient {
@@ -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;
@@ -217,4 +224,294 @@ class StatsApiClient {
     }
 }
 exports.StatsApiClient = StatsApiClient;
+// ============= 新版 API 客户端 (V2.0) =============
+const types_1 = require("./types");
+/**
+ * 简单的内存缓存实现
+ */
+class SimpleCache {
+    cache = new Map();
+    get(key) {
+        const item = this.cache.get(key);
+        if (!item)
+            return null;
+        if (Date.now() > item.expireAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return item.data;
+    }
+    set(key, data, ttl) {
+        this.cache.set(key, {
+            data,
+            expireAt: Date.now() + ttl,
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * 新版国家统计局API客户端 (V2.0)
+ * 基于UUID标识符的新架构
+ */
+class NewStatsApiClient {
+    baseUrl;
+    timeout;
+    rootId;
+    // 缓存实例
+    treeCache;
+    indicatorsCache;
+    // 默认配置
+    DEFAULT_TREE_TTL = 24 * 60 * 60 * 1000; // 24小时
+    DEFAULT_INDICATORS_TTL = 12 * 60 * 60 * 1000; // 12小时
+    constructor(config) {
+        this.baseUrl = config?.baseUrl || types_1.NEW_API_BASE_URL;
+        this.timeout = config?.timeout || 30000;
+        this.rootId = config?.rootId || 'fc982599aa684be7969d7b90b1bd0e84'; // 月度数据根节点
+        // 初始化缓存
+        this.treeCache = new SimpleCache();
+        this.indicatorsCache = new SimpleCache();
+    }
+    /**
+     * 搜索数据集
+     * 用于快速定位 cid
+     */
+    async search(params) {
+        const url = new URL(`${this.baseUrl}/query`);
+        url.searchParams.set('search', params.search);
+        url.searchParams.set('pagenum', (params.pagenum || 1).toString());
+        url.searchParams.set('pageSize', (params.pageSize || 10).toString());
+        console.error(`Search Request: ${url.toString()}`);
+        try {
+            const response = await axios_1.default.get(url.toString(), {
+                timeout: this.timeout,
+            });
+            return response.data.data?.data || [];
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw new Error(`Search request failed: ${error.response?.data || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 获取树结构
+     * 用于遍历目录树,获取叶子节点(cid)
+     */
+    async getTree(params) {
+        // 检查缓存
+        const cacheKey = `tree_${params.code}_${params.pid || 'root'}`;
+        const cached = this.treeCache.get(cacheKey);
+        if (cached) {
+            console.error(`Tree cache hit for ${cacheKey}`);
+            return cached;
+        }
+        const url = new URL(`${this.baseUrl}/new/queryIndexTreeAsync`);
+        if (params.pid) {
+            url.searchParams.set('pid', params.pid);
+        }
+        url.searchParams.set('code', params.code);
+        console.error(`Tree Request: ${url.toString()}`);
+        try {
+            const response = await axios_1.default.get(url.toString(), {
+                timeout: this.timeout,
+            });
+            const nodes = response.data.data || [];
+            // 缓存结果
+            this.treeCache.set(cacheKey, nodes, this.DEFAULT_TREE_TTL);
+            return nodes;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw new Error(`Tree request failed: ${error.response?.data || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 递归获取所有叶子节点(cid)
+     * 注意:此方法耗时较长,慎用
+     */
+    async getAllLeafNodes(code) {
+        const allLeaves = [];
+        const getRecursively = async (pid) => {
+            try {
+                // 添加延迟避免请求过于频繁
+                await new Promise(resolve => setTimeout(resolve, 300));
+                const nodes = await this.getTree({ pid, code });
+                for (const node of nodes) {
+                    if (node.isLeaf) {
+                        allLeaves.push(node);
+                    }
+                    else {
+                        await getRecursively(node._id);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`Error in recursive tree traversal for pid=${pid}:`, error);
+                throw error;
+            }
+        };
+        await getRecursively();
+        return allLeaves;
+    }
+    /**
+     * 获取指标列表
+     * 根据 cid 获取所有可用指标
+     */
+    async getIndicators(params) {
+        // 检查缓存
+        const cacheKey = `indicators_${params.cid}`;
+        const cached = this.indicatorsCache.get(cacheKey);
+        if (cached) {
+            console.error(`Indicators cache hit for ${cacheKey}`);
+            return cached;
+        }
+        const url = new URL(`${this.baseUrl}/new/queryIndicatorsByCid`);
+        url.searchParams.set('cid', params.cid);
+        if (params.dt) {
+            url.searchParams.set('dt', params.dt);
+        }
+        if (params.name) {
+            url.searchParams.set('name', params.name);
+        }
+        console.error(`Indicators Request: ${url.toString()}`);
+        try {
+            const response = await axios_1.default.get(url.toString(), {
+                timeout: this.timeout,
+            });
+            const indicators = response.data.data?.list || [];
+            // 缓存结果
+            this.indicatorsCache.set(cacheKey, indicators, this.DEFAULT_INDICATORS_TTL);
+            return indicators;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw new Error(`Indicators request failed: ${error.response?.data || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 查询数据
+     * 批量获取多个指标、多个时间点的数据
+     */
+    async getData(params) {
+        const payload = {
+            cid: params.cid,
+            indicatorIds: params.indicatorIds,
+            das: params.das,
+            dts: params.dts,
+            showType: params.showType || '1',
+            rootId: params.rootId || this.rootId,
+        };
+        console.error(`Data Request: ${this.baseUrl}/getEsDataByCidAndDt`);
+        console.error(`Payload:`, JSON.stringify(payload, null, 2));
+        try {
+            const response = await axios_1.default.post(`${this.baseUrl}/getEsDataByCidAndDt`, payload, {
+                timeout: this.timeout,
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.data.success) {
+                throw new Error('Data query failed: API returned success=false');
+            }
+            return response.data.data || [];
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw new Error(`Data request failed: ${error.response?.data || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 辅助方法: 搜索并获取数据
+     * 一步到位:搜索关键词 -> 获取cid -> 获取指标 -> 查询数据
+     */
+    async searchAndGet(keyword, indicatorName, startTime, endTime) {
+        // 1. 搜索定位cid
+        const searchResults = await this.search({ search: keyword, pageSize: 10 });
+        if (!searchResults || searchResults.length === 0) {
+            throw new Error(`No results found for keyword: ${keyword}`);
+        }
+        // 优先选择最新的数据集(通过edate判断)
+        const target = searchResults.reduce((latest, current) => {
+            if (!latest.edate)
+                return current;
+            if (!current.edate)
+                return latest;
+            return current.edate > latest.edate ? current : latest;
+        });
+        // 从 globalid 提取 cid (如果搜索结果没有直接提供cid)
+        const cid = target.cid || this.extractCidFromGlobalId(target.treeinfo_globalid);
+        if (!cid) {
+            throw new Error('Failed to extract cid from search result');
+        }
+        // 2. 获取指标列表
+        const indicators = await this.getIndicators({ cid });
+        if (!indicators || indicators.length === 0) {
+            throw new Error(`No indicators found for cid: ${cid}`);
+        }
+        // 筛选目标指标
+        let targetIndicator;
+        if (indicatorName) {
+            targetIndicator = indicators.find(ind => ind.i_showname.includes(indicatorName));
+        }
+        else {
+            targetIndicator = indicators[0]; // 默认取第一个
+        }
+        if (!targetIndicator) {
+            throw new Error(`Indicator not found: ${indicatorName}`);
+        }
+        // 3. 查询数据
+        const timeRange = startTime && endTime
+            ? `${startTime}-${endTime}`
+            : `${target.sdate || '202001'}MM-${target.edate || '202612'}MM`;
+        const data = await this.getData({
+            cid,
+            indicatorIds: [targetIndicator._id],
+            das: [{ text: '全国', value: '000000000000' }],
+            dts: [timeRange],
+        });
+        return {
+            cid,
+            indicator: targetIndicator,
+            data,
+        };
+    }
+    /**
+     * 辅助方法: 从 globalid 提取 cid (最后一段)
+     */
+    extractCidFromGlobalId(globalId) {
+        if (!globalId)
+            return null;
+        const parts = globalId.split('.');
+        return parts[parts.length - 1] || null;
+    }
+    /**
+     * 清除所有缓存
+     */
+    clearCache() {
+        this.treeCache.clear();
+        this.indicatorsCache.clear();
+    }
+    /**
+     * 设置根节点ID
+     */
+    setRootId(rootId) {
+        this.rootId = rootId;
+    }
+    /**
+     * 获取当前根节点ID
+     */
+    getRootId() {
+        return this.rootId;
+    }
+}
+exports.NewStatsApiClient = NewStatsApiClient;
 //# sourceMappingURL=api-client.js.map

package/dist/index.js

@@ -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/dist/types.d.ts

@@ -22,4 +22,169 @@ export interface StdioServerTransport {
     new (): StdioServerTransport;
 }
 export type StartHttpServerFn = (options: SseAndStreamableHttpMcpServerOptions) => Promise<void>;
+/**
+ * 新版API基础URL
+ */
+export declare const NEW_API_BASE_URL = "https://data.stats.gov.cn/dg/website/publicrelease/web/external";
+/**
+ * 树节点 - 来自 queryIndexTreeAsync
+ */
+export interface TreeNode {
+    _id: string;
+    name: string;
+    isLeaf: boolean;
+    treeinfo_globalid?: string;
+    sdate?: string;
+    edate?: string;
+}
+/**
+ * 树查询响应
+ */
+export interface TreeResponse {
+    data: TreeNode[];
+    success: boolean;
+}
+/**
+ * 指标信息 - 来自 queryIndicatorsByCid
+ */
+export interface Indicator {
+    _id: string;
+    i_showname: string;
+    i_mark?: string;
+    du?: string;
+    dp?: string;
+    order?: number;
+}
+/**
+ * 指标列表响应
+ */
+export interface IndicatorsResponse {
+    data: {
+        list: Indicator[];
+    };
+    success: boolean;
+}
+/**
+ * 地区维度项
+ */
+export interface RegionDimension {
+    text: string;
+    value: string;
+}
+/**
+ * 数据值项
+ */
+export interface DataValue {
+    _id: string;
+    i_showname?: string;
+    value?: string;
+    da_name?: string;
+    du_name?: string;
+}
+/**
+ * 数据点 - 来自 getEsDataByCidAndDt
+ */
+export interface DataPoint {
+    code: string;
+    name: string;
+    values: DataValue[];
+}
+/**
+ * 数据查询响应
+ */
+export interface DataResponse {
+    data: DataPoint[];
+    success: boolean;
+}
+/**
+ * 数据查询请求参数
+ */
+export interface DataQueryParams {
+    cid: string;
+    indicatorIds: string[];
+    das: RegionDimension[];
+    dts: string[];
+    showType?: string;
+    rootId?: string;
+}
+/**
+ * 搜索结果项 - 来自 /external/query
+ */
+export interface SearchItem {
+    show_name: string;
+    type_text: string;
+    treeinfo_globalid?: string;
+    cid?: string;
+    sdate?: string;
+    edate?: string;
+}
+/**
+ * 搜索响应
+ */
+export interface SearchResponse {
+    data: {
+        data: SearchItem[];
+        total?: number;
+    };
+    success?: boolean;
+}
+/**
+ * 树查询参数
+ */
+export interface TreeQueryParams {
+    pid?: string;
+    code: string;
+}
+/**
+ * 指标查询参数
+ */
+export interface IndicatorQueryParams {
+    cid: string;
+    dt?: string;
+    name?: string;
+}
+/**
+ * 搜索查询参数
+ */
+export interface SearchQueryParams {
+    search: string;
+    pagenum?: number;
+    pageSize?: number;
+}
+/**
+ * 时间编码格式枚举
+ */
+export declare enum TimeFormat {
+    MONTHLY = "MM",// 月度: YYYYMM, 后缀 MM
+    QUARTERLY = "SS",// 季度: YYYYQ, 后缀 SS
+    YEARLY = "YY"
+}
+/**
+ * 分类代码枚举
+ */
+export declare enum CategoryCode {
+    MONTHLY = "1",// 月度数据
+    QUARTERLY = "2",// 季度数据
+    YEARLY = "3",// 年度数据
+    PROVINCE_QUARTERLY = "5",// 分省季度
+    PROVINCE_YEARLY = "6",// 分省年度
+    OTHER = "7"
+}
+/**
+ * 缓存配置
+ */
+export interface CacheConfig {
+    treeTTL?: number;
+    indicatorsTTL?: number;
+    dataTTL?: number;
+}
+/**
+ * API客户端配置
+ */
+export interface NewApiClientConfig {
+    baseUrl?: string;
+    timeout?: number;
+    cache?: CacheConfig;
+    rootId?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,3 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CategoryCode = exports.TimeFormat = exports.NEW_API_BASE_URL = void 0;
+// ============= 新版 API 类型定义 (V2.0) =============
+/**
+ * 新版API基础URL
+ */
+exports.NEW_API_BASE_URL = 'https://data.stats.gov.cn/dg/website/publicrelease/web/external';
+/**
+ * 时间编码格式枚举
+ */
+var TimeFormat;
+(function (TimeFormat) {
+    TimeFormat["MONTHLY"] = "MM";
+    TimeFormat["QUARTERLY"] = "SS";
+    TimeFormat["YEARLY"] = "YY";
+})(TimeFormat || (exports.TimeFormat = TimeFormat = {}));
+/**
+ * 分类代码枚举
+ */
+var CategoryCode;
+(function (CategoryCode) {
+    CategoryCode["MONTHLY"] = "1";
+    CategoryCode["QUARTERLY"] = "2";
+    CategoryCode["YEARLY"] = "3";
+    CategoryCode["PROVINCE_QUARTERLY"] = "5";
+    CategoryCode["PROVINCE_YEARLY"] = "6";
+    CategoryCode["OTHER"] = "7";
+})(CategoryCode || (exports.CategoryCode = CategoryCode = {}));
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "national-stats-mcp",
-  "version": "1.0.2",
-  "description": "MCP server for accessing National Bureau of Statistics data",
+  "version": "1.2.0",
+  "description": "MCP server for accessing National Bureau of Statistics data (supports both new V2.0 and legacy API)",
   "main": "dist/index.js",
   "bin": {
     "national-stats-mcp": "dist/index.js"

package/zb.json

@@ -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"
-    }
-]