national-stats-mcp 1.1.0 → 2.0.0

package/README.md

@@ -1,9 +1,18 @@
 # 国家统计局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 (向后兼容)
 - ✅ 关键词搜索：直接搜索获取指标代码及最新值（推荐用于快速查询）
 - ✅ 树形分类：可浏览和递归获取所有分类/指标体系
 - ✅ 预遍历数据：提供完整的预遍历分类编码体系，可直接读取使用（减少递归调用）
@@ -62,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` 用于获取指标列表
+- 数据查询接口 `/stream/esData` 用于批量获取时间序列数据
+- 内置缓存机制：树结构24小时，指标列表12小时
+- UUID标识符系统和时间分片机制
+- 完整的错误处理和重试逻辑
+
+### 旧版 API (向后兼容)
+项目严格实现旧版API接口规范：
 - 搜索接口 `/search.htm` 用于关键词查找和快速获取最新值
 - 分类接口 `/easyquery.htm` 用于遍历指标分类树
 - 数据接口 `/easyquery.htm` 用于查询历史时间序列

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 {
@@ -224,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}/stream/esData`);
+        console.error(`Payload:`, JSON.stringify(payload, null, 2));
+        try {
+            const response = await axios_1.default.post(`${this.baseUrl}/stream/esData`, 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