national-stats-mcp 1.2.0 → 2.0.0

package/README.md

@@ -187,7 +187,7 @@ enum CategoryCode {
 - 搜索接口 `/external/query` 用于关键词搜索和快速定位cid
 - 树遍历接口 `/new/queryIndexTreeAsync` 用于浏览分类树和获取cid
 - 指标查询接口 `/new/queryIndicatorsByCid` 用于获取指标列表
-- 数据查询接口 `/getEsDataByCidAndDt` 用于批量获取时间序列数据
+- 数据查询接口 `/stream/esData` 用于批量获取时间序列数据
 - 内置缓存机制：树结构24小时，指标列表12小时
 - UUID标识符系统和时间分片机制
 - 完整的错误处理和重试逻辑

package/dist/api-client.js

@@ -408,10 +408,10 @@ class NewStatsApiClient {
             showType: params.showType || '1',
             rootId: params.rootId || this.rootId,
         };
-        console.error(`Data Request: ${this.baseUrl}/getEsDataByCidAndDt`);
+        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}/getEsDataByCidAndDt`, payload, {
+            const response = await axios_1.default.post(`${this.baseUrl}/stream/esData`, payload, {
                 timeout: this.timeout,
                 headers: {
                     'Content-Type': 'application/json',

package/dist/index.js

@@ -8,60 +8,151 @@ const mcp_http_server_1 = require("mcp-http-server");
 const api_client_1 = require("./api-client");
 const zod_1 = require("zod");
 const commander_1 = require("commander");
-// 获取版本号，这里使用package.json中的版本
-const VERSION = '1.0.2';
-// 创建API客户端实例
-const apiClient = new api_client_1.StatsApiClient();
+// 获取版本号
+const VERSION = '2.0.0';
+// 创建新版API客户端实例
+const apiClient = new api_client_1.NewStatsApiClient();
+// 31省 das 常量
+const PROVINCE_LIST = [
+    { text: '北京', value: '110000000000' },
+    { text: '天津', value: '120000000000' },
+    { text: '河北', value: '130000000000' },
+    { text: '山西', value: '140000000000' },
+    { text: '内蒙古', value: '150000000000' },
+    { text: '辽宁', value: '210000000000' },
+    { text: '吉林', value: '220000000000' },
+    { text: '黑龙江', value: '230000000000' },
+    { text: '上海', value: '310000000000' },
+    { text: '江苏', value: '320000000000' },
+    { text: '浙江', value: '330000000000' },
+    { text: '安徽', value: '340000000000' },
+    { text: '福建', value: '350000000000' },
+    { text: '江西', value: '360000000000' },
+    { text: '山东', value: '370000000000' },
+    { text: '河南', value: '410000000000' },
+    { text: '湖北', value: '420000000000' },
+    { text: '湖南', value: '430000000000' },
+    { text: '广东', value: '440000000000' },
+    { text: '广西', value: '450000000000' },
+    { text: '海南', value: '460000000000' },
+    { text: '重庆', value: '500000000000' },
+    { text: '四川', value: '510000000000' },
+    { text: '贵州', value: '520000000000' },
+    { text: '云南', value: '530000000000' },
+    { text: '西藏', value: '540000000000' },
+    { text: '陕西', value: '610000000000' },
+    { text: '甘肃', value: '620000000000' },
+    { text: '青海', value: '630000000000' },
+    { text: '宁夏', value: '640000000000' },
+    { text: '新疆', value: '650000000000' },
+];
+// 全国
+const NATIONAL = { text: '全国', value: '000000000000' };
+/**
+ * 根据 region 参数构造 das 数组
+ */
+function buildDas(region) {
+    if (!region || region === '全国' || region === 'all') {
+        return [NATIONAL];
+    }
+    if (region === '31省' || region === '分省' || region === 'provinces') {
+        return PROVINCE_LIST;
+    }
+    // 支持单个省名或逗号分隔的多个省名
+    const names = region.split(',').map(s => s.trim());
+    const result = [];
+    for (const name of names) {
+        if (name === '全国') {
+            result.push(NATIONAL);
+            continue;
+        }
+        const found = PROVINCE_LIST.find(p => p.text === name || p.text === name.replace(/[市省区]$/, ''));
+        if (found) {
+            result.push(found);
+        }
+        else {
+            // 尝试模糊匹配
+            const fuzzy = PROVINCE_LIST.find(p => p.text.includes(name) || name.includes(p.text));
+            if (fuzzy) {
+                result.push(fuzzy);
+            }
+        }
+    }
+    return result.length > 0 ? result : [NATIONAL];
+}
+/**
+ * 确定 showType: 多地区用 "2"（按地区分组），单地区用 "1"（按时间分组）
+ */
+function getShowType(das) {
+    return das.length > 1 ? '2' : '1';
+}
 // 创建MCP服务器
 exports.server = new mcp_js_1.McpServer({
     name: 'national-stats-mcp',
     version: VERSION,
-    description: '国家统计局数据查询API'
+    description: '国家统计局数据查询API (V2.0 新版)'
 });
 // 设置服务器instructions
 exports.server.instructions = `
-    该服务主要用于帮助用户查询国家统计局的统计数据。
+    该服务主要用于帮助用户查询国家统计局的统计数据（使用V2.0新版API）。
 
     主要工具包括：
-    - search_statistics: 通过关键词搜索国家统计局数据（推荐用于快速查询）
-    - get_statistics_categories: 获取统计指标分类
-    - get_statistics_leaf_categories: 获取所有叶子指标（递归获取）
-    - get_statistics_time_options: 获取特定数据库可选的时间范围
-    - get_statistics_data: 获取特定统计指标的数据
-    - batch_get_statistics: 批量获取统计数据
+    - search_statistics: 通过关键词搜索数据集，获取cid
+    - browse_tree: 浏览指标分类树，支持月度/季度/年度/分省数据
+    - get_indicators: 根据cid获取可用指标列表
+    - get_data: 获取具体统计数据（支持全国/分省/指定省份）
+    - search_and_get: 一步到位：搜索 + 获取数据
+
+    使用流程：
+    1. 用 search_statistics 搜索关键词找到 cid
+    2. 用 get_indicators 获取该 cid 下的指标 ID
+    3. 用 get_data 传入 cid、indicatorIds、时间范围和地区获取数据
+
+    快捷方式：
+    - search_and_get 可以一步完成上述流程（适合简单查询）
+    - browse_tree 可以浏览完整的分类体系
+
+    地区参数说明（region）：
+    - "全国" 或不传: 查全国数据
+    - "31省" 或 "分省": 查所有31省数据
+    - "北京" / "广东" 等: 查单个省份
+    - "北京,上海,广东": 逗号分隔查多个省份
 
-    使用说明：
-    - 对于快速查询，直接使用search_statistics根据关键词查找数据和指标code
-    - 如需浏览分类体系，调用get_statistics_categories获取分类树
-    - 要获取特定分类下的所有叶子指标，使用get_statistics_leaf_categories
-    - 查看可用时间范围调用get_statistics_time_options
-    - 根据指标代码查询具体数据使用get_statistics_data
+    时间格式说明（dts）：
+    - 年度: "2020YY-2024YY"
+    - 季度: "2024ASS-2025BSS" (A=1季度, B=2季度, C=3季度, D=4季度)
+    - 月度: "202401MM-202412MM"
 
-    配置选项：
-    - dbcode: 数据库代码，hgnd (年度数据)、hgjd (季度数据) 等
-    - zb: 指标代码，通过分类或搜索获取
-    - sj: 时间范围，如 LAST6 (最近6个季度)、2025 (指定年份) 等
+    分类代码（code）：
+    - 1: 月度数据
+    - 2: 季度数据
+    - 3: 年度数据
+    - 5: 分省季度数据
+    - 6: 分省年度数据
+    - 7: 其他/普查数据
   `;
-// 注册搜索统计指标的工具（最推荐使用）
-exports.server.tool('search_statistics', '通过关键词搜索国家统计局指标和数据。可以快速查找指标及其最新值。', {
-    keyword: zod_1.z.string().describe('搜索关键词，如 "GDP"、"人均可支配收入" 等'),
-    db: zod_1.z.string().optional().default('').describe('数据库筛选，空=全部，可选 "年度数据" 或 "季度数据"'),
-    page: zod_1.z.number().optional().default(0).describe('页码，从0开始'),
+// ====== 工具1: 搜索数据集 ======
+exports.server.tool('search_statistics', '通过关键词搜索国家统计局数据集，返回匹配的数据集及其cid。用于定位要查询的数据。', {
+    keyword: zod_1.z.string().describe('搜索关键词，如 "GDP"、"CPI"、"人口"、"居民消费价格" 等'),
+    pageSize: zod_1.z.number().optional().default(10).describe('每页结果数，默认10'),
+    pagenum: zod_1.z.number().optional().default(1).describe('页码，从1开始'),
 }, async (args) => {
-    const { keyword, db = '', page = 0 } = args;
+    const { keyword, pageSize = 10, pagenum = 1 } = args;
     try {
-        // 执行搜索
-        const searchResult = await apiClient.search(keyword, db, page);
-        // 解析搜索结果
-        const parsedResults = apiClient.parseSearchResult(searchResult);
+        const results = await apiClient.search({ search: keyword, pageSize, pagenum });
         return {
             content: [
                 {
                     type: 'text',
                     text: JSON.stringify({
-                        pagecount: searchResult.pagecount,
-                        pagecurrent: searchResult.pagecurrent,
-                        results: parsedResults
+                        count: results.length,
+                        results: results.map(r => ({
+                            name: r.show_name,
+                            type: r.type_text,
+                            cid: r.cid || null,
+                            globalid: r.treeinfo_globalid,
+                            timeRange: r.sdate && r.edate ? `${r.sdate} - ${r.edate}` : null,
+                        }))
                     }, null, 2)
                 }
             ],
@@ -69,169 +160,233 @@ exports.server.tool('search_statistics', '通过关键词搜索国家统计局
     }
     catch (error) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
         };
     }
 });
-// 注册获取统计分类的工具
-exports.server.tool('get_statistics_categories', '获取国家统计局的统计指标分类，返回分类树结构（第一层）', {
-    dbcode: zod_1.z.string()
-        .describe('数据库代码，指定数据类型：hgnd(年度数据), hgjd(季度数据)等'),
-    wdcode: zod_1.z.string()
-        .default('zb')
-        .describe('维度代码，默认为zb(指标)'),
+// ====== 工具2: 浏览分类树 ======
+exports.server.tool('browse_tree', '浏览国家统计局指标分类树。可逐层钻取获取子节点，叶子节点的_id即为cid。', {
+    code: zod_1.z.string().default('3').describe('分类代码: 1=月度, 2=季度, 3=年度, 5=分省季度, 6=分省年度, 7=其他'),
+    pid: zod_1.z.string().optional().describe('父节点ID，不传则获取顶层节点'),
 }, async (args) => {
-    const { dbcode, wdcode = 'zb' } = args;
+    const { code, pid } = args;
     try {
-        const data = await apiClient.getCategories(dbcode, wdcode);
+        const nodes = await apiClient.getTree({ code, pid });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(data, null, 2)
+                    text: JSON.stringify({
+                        count: nodes.length,
+                        nodes: nodes.map(n => ({
+                            id: n._id,
+                            name: n.name,
+                            isLeaf: n.isLeaf,
+                            timeRange: n.sdate && n.edate ? `${n.sdate} - ${n.edate}` : n.sdate || null,
+                        }))
+                    }, null, 2)
                 }
             ],
         };
     }
     catch (error) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
         };
     }
 });
-// 注册获取统计指标叶子节点的工具（递归获取所有叶子指标）
-exports.server.tool('get_statistics_leaf_categories', '递归获取国家统计局特定数据库的所有叶子指标节点（可查看分类下所有可查询指标）', {
-    dbcode: zod_1.z.string()
-        .describe('数据库代码，指定数据类型：hgnd(年度数据), hgjd(季度数据)等'),
+// ====== 工具3: 获取指标列表 ======
+exports.server.tool('get_indicators', '根据cid获取数据集下的所有可用指标（含指标ID、名称、单位、统计口径）。', {
+    cid: zod_1.z.string().describe('数据集ID（从搜索结果或树节点的_id获取）'),
 }, async (args) => {
-    const { dbcode } = args;
+    const { cid } = args;
     try {
-        const data = await apiClient.getLeafCategories(dbcode);
+        const indicators = await apiClient.getIndicators({ cid });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(data, null, 2)
+                    text: JSON.stringify({
+                        cid,
+                        count: indicators.length,
+                        indicators: indicators.map(ind => ({
+                            id: ind._id,
+                            name: ind.i_showname,
+                            mark: ind.i_mark || null,
+                            order: ind.order,
+                        }))
+                    }, null, 2)
                 }
             ],
         };
     }
     catch (error) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
         };
     }
 });
-// 注册获取统计时间维度选项的工具
-exports.server.tool('get_statistics_time_options', '获取指定数据库可选的时间范围维度', {
-    dbcode: zod_1.z.string()
-        .describe('数据库代码，指定数据类型：hgnd(年度数据), hgjd(季度数据)等'),
+// ====== 工具4: 获取数据（核心工具）======
+exports.server.tool('get_data', '获取统计数据。支持全国/31省/指定省份。需提供cid和indicatorIds（通过get_indicators获取）。', {
+    cid: zod_1.z.string().describe('数据集ID'),
+    indicatorIds: zod_1.z.array(zod_1.z.string()).describe('指标ID数组（从get_indicators获取）'),
+    dts: zod_1.z.string().describe('时间范围，如 "2020YY-2024YY"（年度）、"202401MM-202412MM"（月度）'),
+    region: zod_1.z.string().optional().default('全国').describe('地区: "全国"(默认), "31省"/"分省"(全部省份), "北京"(单省), "北京,上海,广东"(多省逗号分隔)'),
 }, async (args) => {
-    const { dbcode } = args;
+    const { cid, indicatorIds, dts, region } = args;
     try {
-        const data = await apiClient.getTimeDimensions(dbcode);
+        const das = buildDas(region);
+        const showType = getShowType(das);
+        const data = await apiClient.getData({
+            cid,
+            indicatorIds,
+            das,
+            dts: [dts],
+            showType,
+        });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(data, null, 2)
+                    text: JSON.stringify({
+                        query: { cid, indicatorIds, dts, region: region || '全国', showType },
+                        count: data.length,
+                        data: data.map(d => ({
+                            code: d.code,
+                            name: d.name,
+                            values: d.values.map(v => ({
+                                indicator: v.i_showname || v._id,
+                                value: v.value,
+                                region: v.da_name || d.name,
+                                unit: v.du_name,
+                            }))
+                        }))
+                    }, null, 2)
                 }
             ],
         };
     }
     catch (error) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
         };
     }
 });
-// 注册获取统计数据的工具
-exports.server.tool('get_statistics_data', '获取国家统计局特定指标的数据', {
-    zb: zod_1.z.string().describe('指标代码，通过分类或搜索获取'),
-    dbcode: zod_1.z.string()
-        .describe('数据库代码，指定数据类型：hgnd(年度数据), hgjd(季度数据)等'),
-    sj: zod_1.z.string()
-        .default('LAST30')
-        .describe('时间范围，例如 LAST6 (最近6季度), 2025 (指定年份), LAST30 (最近30年) 等'),
+// ====== 工具5: 搜索并获取数据（快捷工具）======
+exports.server.tool('search_and_get', '一步到位：根据关键词搜索 → 定位cid → 获取指标 → 查询数据。适合快速查询。支持指定地区。', {
+    keyword: zod_1.z.string().describe('搜索关键词，如 "GDP"、"人口"、"CPI"'),
+    indicatorName: zod_1.z.string().optional().describe('指标名称过滤（模糊匹配），不传则取第一个指标'),
+    startTime: zod_1.z.string().optional().describe('起始时间，如 "2020YY"、"202401MM"'),
+    endTime: zod_1.z.string().optional().describe('结束时间，如 "2024YY"、"202412MM"'),
+    region: zod_1.z.string().optional().default('全国').describe('地区: "全国"(默认), "31省", "北京", "北京,上海,广东"'),
 }, async (args) => {
-    const { zb, dbcode, sj = 'LAST30' } = args;
+    const { keyword, indicatorName, startTime, endTime, region } = args;
     try {
-        const data = await apiClient.getData(zb, dbcode, sj);
+        // 1. 搜索定位cid
+        const searchResults = await apiClient.search({ search: keyword, pageSize: 10 });
+        if (!searchResults || searchResults.length === 0) {
+            throw new Error(`未找到与 "${keyword}" 相关的数据集`);
+        }
+        // 优先选择最新的数据集
+        const target = searchResults.reduce((latest, current) => {
+            if (!latest.edate)
+                return current;
+            if (!current.edate)
+                return latest;
+            return current.edate > latest.edate ? current : latest;
+        });
+        // 提取 cid
+        const cid = target.cid || extractCidFromGlobalId(target.treeinfo_globalid);
+        if (!cid) {
+            throw new Error('无法从搜索结果中提取 cid');
+        }
+        // 2. 获取指标列表
+        const indicators = await apiClient.getIndicators({ cid });
+        if (!indicators || indicators.length === 0) {
+            throw new Error(`cid ${cid} 下没有找到指标`);
+        }
+        // 筛选指标
+        let targetIndicator = indicatorName
+            ? indicators.find(ind => ind.i_showname.includes(indicatorName))
+            : indicators[0];
+        if (!targetIndicator) {
+            throw new Error(`未找到包含 "${indicatorName}" 的指标。可用指标: ${indicators.map(i => i.i_showname).join(', ')}`);
+        }
+        // 3. 构造时间范围
+        const timeRange = startTime && endTime
+            ? `${startTime}-${endTime}`
+            : `${target.sdate || '2020'}YY-${target.edate || '2024'}YY`;
+        // 4. 构造地区维度
+        const das = buildDas(region);
+        const showType = getShowType(das);
+        // 5. 查询数据
+        const data = await apiClient.getData({
+            cid,
+            indicatorIds: [targetIndicator._id],
+            das,
+            dts: [timeRange],
+            showType,
+        });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(data, null, 2)
+                    text: JSON.stringify({
+                        dataset: target.show_name,
+                        cid,
+                        indicator: {
+                            id: targetIndicator._id,
+                            name: targetIndicator.i_showname,
+                            mark: targetIndicator.i_mark || null,
+                        },
+                        timeRange,
+                        region: region || '全国',
+                        count: data.length,
+                        data: data.map(d => ({
+                            code: d.code,
+                            name: d.name,
+                            values: d.values.map(v => ({
+                                indicator: v.i_showname || targetIndicator.i_showname,
+                                value: v.value,
+                                region: v.da_name || d.name,
+                                unit: v.du_name,
+                            }))
+                        }))
+                    }, null, 2)
                 }
             ],
         };
     }
     catch (error) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
         };
     }
 });
-// 注册批量获取统计数据的工具
-exports.server.tool('batch_get_statistics', '批量获取国家统计局多个指标的数据', {
-    queries: zod_1.z.array(zod_1.z.object({
-        zb: zod_1.z.string().describe('指标代码'),
-        dbcode: zod_1.z.string().describe('数据库代码'),
-        sj: zod_1.z.string().optional().default('LAST30').describe('时间范围'),
-    })).describe('查询参数数组')
-}, async (args) => {
-    const { queries } = args;
-    try {
-        const results = await apiClient.batchGet(queries.map(q => ({
-            zb: q.zb,
-            dbcode: q.dbcode,
-            sj: q.sj || 'LAST30'
-        })));
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(results, null, 2)
-                }
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error.message}`,
-                },
-            ],
-        };
-    }
+// ====== 工具6: 获取省份列表 ======
+exports.server.tool('list_provinces', '获取31省份代码列表，用于了解可用的地区参数。', {}, async () => {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    national: NATIONAL,
+                    provinces: PROVINCE_LIST,
+                    usage: '在 get_data 和 search_and_get 的 region 参数中使用省份名称，如 "北京" 或 "31省"'
+                }, null, 2)
+            }
+        ],
+    };
 });
+/**
+ * 从 globalid 提取 cid (最后一段)
+ */
+function extractCidFromGlobalId(globalId) {
+    if (!globalId)
+        return null;
+    const parts = globalId.split('.');
+    return parts[parts.length - 1] || null;
+}
 // 启动服务器
 async function startServer() {
     const program = new commander_1.Command();
@@ -240,7 +395,6 @@ async function startServer() {
         .option('-h, --host <host>', 'Host to listen on for HTTP/SSE mode', 'localhost')
         .parse();
     const options = program.opts();
-    // 通过端口参数判断是否使用HTTP模式还是STDIO模式
     if (options.port) {
         await (0, mcp_http_server_1.startSseAndStreamableHttpMcpServer)({
             host: options.host,
@@ -251,7 +405,6 @@ async function startServer() {
         });
     }
     else {
-        // 使用STDIO模式
         const transport = new stdio_js_1.StdioServerTransport();
         await exports.server.connect(transport);
     }

package/dist/types.d.ts

@@ -82,7 +82,7 @@ export interface DataValue {
     du_name?: string;
 }
 /**
- * 数据点 - 来自 getEsDataByCidAndDt
+ * 数据点 - 来自 stream/esData
  */
 export interface DataPoint {
     code: string;
@@ -95,6 +95,8 @@ export interface DataPoint {
 export interface DataResponse {
     data: DataPoint[];
     success: boolean;
+    state?: number;
+    message?: string;
 }
 /**
  * 数据查询请求参数

package/nbs_api_v2_guide.md

@@ -0,0 +1,481 @@
+# 国家统计局新版数据接口使用文档
+
+> **基础地址**: `https://data.stats.gov.cn/dg/website/publicrelease/web/external`
+> **鉴权**: 无需鉴权，公开访问
+> **版本**: V2.0 (2026.06.05更新)
+> **特点**: 采用 UUID 标识符，支持时间分片，元数据与数据分离，批量查询效率高。
+
+### 变更记录
+
+| 日期 | 变更内容 |
+|------|---------|
+| 2026.06.05 | 数据查询接口从 `/getEsDataByCidAndDt` 迁移至 `/stream/esData`；`showType` 变为必填参数；响应新增 `state`、`message` 字段 |
+| 2026.03.27 | V2.0 发布，采用 UUID 标识符架构 |
+
+---
+
+## 目录
+
+- [核心概念](#核心概念)
+- [接口概览](#接口概览)
+- [接口详解](#接口详解)
+- [编码与ID规律](#编码与id规律)
+- [使用示例](#使用示例)
+- [最佳实践](#最佳实践)
+
+---
+
+## 核心概念
+
+新版 API 摒弃了旧版的层级代码（如 `A0101`），转而使用 **UUID** 作为唯一标识。数据获取遵循 **"树形导航 -> 指标元数据 -> 批量取值"** 的三步走策略。
+
+### 1. 关键标识符
+
+| 标识符 | 全称 | 含义 | 来源接口 |
+| :--- | :--- | :--- | :--- |
+| **`pid`** | Parent ID | **父节点 ID**。用于在目录树中向下展开。初始请求时为空或根节点 ID。 | `queryIndexTreeAsync` 返回节点的 `_id` |
+| **`cid`** | Catalog ID | **数据集 ID**。代表一个**叶子节点**（Leaf Node）。<br>通常对应：**特定指标 + 特定地区 + 特定时间分段**。<br>*注意：同一业务指标因时间分段不同会有多个 `cid`。* | `queryIndexTreeAsync` 返回中 `isLeaf: true` 节点的 `_id` |
+| **`indicatorId`** | Indicator ID | **具体指标 ID**。代表数据集中的某一列（如"同比增长"、"累计值"）。 | `queryIndicatorsByCid` 返回列表中的 `_id` |
+| **`du`** | Unit ID | **单位 ID**。指向数据单位的唯一标识（如 `%`, `亿元`）。 | `queryIndicatorsByCid` 返回 |
+
+### 2. 时间分片机制 (Time Slicing)
+
+这是新版 API 最显著的特征。**同一个业务指标（如 CPI）会被拆分成多个 `cid`**，通常按 5 年或统计制度变革周期分割。
+
+*   **现象**: 搜索 "CPI" 可能会得到多个 `cid`：
+    *   `cid_A`: 2016-2020
+    *   `cid_B`: 2021-2025
+    *   `cid_C`: 2026-至今
+*   **影响**: 获取长期历史数据时，必须**分别请求**这些 `cid`，然后在本地按时间拼接。
+
+### 3. 时间编码格式
+
+在 `stream/esData` 接口中使用：
+
+*   **月度**: `YYYYMM` (如 `202602`)，后缀 `MM` (如 `202602MM`)
+*   **季度**: `YYYYQ` (如 `20254` 表示第四季度)，后缀 `SS` (如 `202504SS`，注意这里 Q4 可能编码为 04)
+*   **年度**: `YYYY` (如 `2025`)，后缀 `YY` (如 `2025YY`)
+*   **范围**: `Start-End` (如 `202501MM-202602MM`)
+
+---
+
+## 接口概览
+
+| 步骤 | 接口路径 | 方法 | 用途 | 关键入参 |
+| :--- | :--- | :--- | :--- | :--- |
+| **1. 遍历目录** | `/new/queryIndexTreeAsync` | GET | 获取分类树，找到目标数据集 (`cid`) | `pid`, `code` |
+| **2. 获取指标** | `/new/queryIndicatorsByCid` | GET | 获取某数据集下的所有指标列表 (`indicatorId`) | `cid` |
+| **3. 查询数据** | `/stream/esData` | POST | 批量获取具体数值 | `cid`, `indicatorIds`, `dts`, `das`, `showType` |
+| *(可选)* | `/external/query` | GET | 关键词搜索，快速定位 `cid` | `search`, `pagenum` |
+
+---
+
+## 接口详解
+
+### 1. 遍历目录树 (Get Tree)
+
+用于从根节点开始，层层下钻，直到找到 `isLeaf: true` 的节点。
+
+```http
+GET /new/queryIndexTreeAsync?pid={parent_id}&code={category_code}
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `pid` | string | ❌ | 父节点 ID。首次请求可为空字符串 `""` 或根节点 ID。 |
+| `code` | string | ✅ | 顶级分类代码。常见值：<br>`1`: 月度数据<br>`2`: 季度数据<br>`3`: 年度数据<br>`5`: 分省季度<br>`6`: 分省年度<br>`7`: 其他/普查 |
+
+**响应关键字段**
+
+```json
+{
+  "data": [
+    {
+      "_id": "fc982599...",
+      "name": "价格指数",
+      "isLeaf": false,
+      "treeinfo_globalid": "...",
+      "sdate": "2021",
+      "edate": "2025"
+    }
+  ],
+  "success": true
+}
+```
+
+**字段说明**
+
+| 字段 | 说明 |
+|------|------|
+| `_id` | 节点唯一标识。若 `isLeaf=false`，则作为下一次请求的 `pid`；若 `isLeaf=true`，则作为 `cid`。 |
+| `isLeaf` | `true`=叶子节点（可查数据），`false`=目录节点（需继续下钻）。 |
+| `sdate/edate` | 该数据集覆盖的时间范围，用于判断是否包含所需年份。 |
+
+---
+
+### 2. 获取指标列表 (Get Indicators)
+
+拿到 `cid` 后，查询该数据集包含哪些具体指标。
+
+```http
+GET /new/queryIndicatorsByCid?cid={catalog_id}&dt=&name=
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `cid` | string | ✅ | 数据集 ID (来自步骤 1 的叶子节点 `_id`) |
+| `dt` | string | ❌ | 时间过滤，通常留空 |
+| `name` | string | ❌ | 指标名称过滤，通常留空 |
+
+**响应关键字段**
+
+```json
+{
+  "data": {
+    "list": [
+      {
+        "_id": "6d249959...",
+        "i_showname": "规上工业增加值同比增长 (%) ",
+        "i_mark": "统计口径说明...",
+        "du": "414774...",
+        "dp": "11",
+        "order": 1
+      }
+    ]
+  }
+}
+```
+
+**字段说明**
+
+| 字段 | 说明 |
+|------|------|
+| `_id` | 指标唯一 ID，后续查询数据时必须传入。 |
+| `i_showname` | 指标显示名称，含单位。 |
+| `i_mark` | **统计口径说明**。非常重要，解释了数据的计算方法和适用范围。 |
+| `du` | 单位 ID，需结合其他接口或常识解析（如 `%`）。 |
+
+---
+
+### 3. 查询具体数据 (Get Data)
+
+**核心接口**。支持批量查询多个指标、多个时间点的数据。
+
+```http
+POST /stream/esData
+Content-Type: application/json
+```
+
+**请求体 (Body)**
+
+```json
+{
+  "cid": "e2d9463aceae483eb122794e53180bf9",
+  "indicatorIds": [
+    "6d249959166b4b07aad922e2aa51097d",
+    "f991aa39485440158f761a71e39b03a1"
+  ],
+  "das": [
+    {
+      "text": "全国",
+      "value": "000000000000"
+    }
+  ],
+  "dts": ["202501MM-202602MM"],
+  "showType": "1",
+  "rootId": "fc982599aa684be7969d7b90b1bd0e84"
+}
+```
+
+**参数说明**
+
+| 字段 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `cid` | string | ✅ | 数据集 ID |
+| `indicatorIds` | array | ✅ | 指标 ID 数组 (来自步骤 2) |
+| `das` | array | ✅ | 地区维度。`value`: `000000000000` 代表全国。如果是分省数据，需传入具体省份代码。 |
+| `dts` | array | ✅ | 时间范围数组。格式 `Start-End`。 |
+| `showType` | string | ✅ | 显示类型，固定传 `"1"`（必填，不传会返回 500） |
+| `rootId` | string | ✅ | 根节点 ID。通常固定为月度数据的根 ID，可通过第一次树请求获取。 |
+
+**响应结构**
+
+```json
+{
+  "data": [
+    {
+      "code": "202602MM",
+      "name": "2026年2月",
+      "values": [
+        {
+          "_id": "6d249959...",
+          "i_showname": "规上工业增加值同比增长 (%) ",
+          "value": "5.8",
+          "da_name": "全国",
+          "du_name": "%"
+        },
+        {
+          "_id": "f991aa39...",
+          "value": "6.1"
+        }
+      ]
+    },
+    {
+      "code": "202601MM",
+      "name": "2026年1月",
+      "values": [ ... ]
+    }
+  ],
+  "success": true,
+  "state": 20000,
+  "message": "成功"
+}
+```
+
+**注意事项**
+*   如果某个月份数据未发布，`values` 可能为空数组 `[]`。
+*   返回数据按时间倒序或正序排列，需根据 `code` 自行排序。
+*   `showType` 为必填参数，不传将返回 HTTP 500 错误。
+
+---
+
+## 编码与ID规律
+
+由于 ID 均为 UUID，无法通过算法推导，必须通过遍历获取。但存在以下业务规律：
+
+### 1. `cid` 与时间的关系
+*   同一类指标（如 CPI），通常会按 `5年` 或 `10年` 切割成不同的 `cid`。
+*   检查 `queryIndexTreeAsync` 返回的 `sdate` 和 `edate` 字段，可以判断该 `cid` 覆盖的时间范围。
+
+### 2. `indicatorId` 的稳定性
+*   在同一个 `cid` 内，`indicatorId` 是稳定的。
+*   **跨 `cid` 不保证稳定**：2021-2025 的 "GDP" 指标 ID 可能与 2026- 的 "GDP" 指标 ID 不同。**建议每个 `cid` 都重新调用 `queryIndicatorsByCid` 获取映射。**
+
+### 3. 地区代码 (`da`)
+*   `000000000000`: 全国
+*   分省数据的 `cid` 通常位于"分省年度/季度数据"目录下。
+
+### 4. 根节点 ID (`rootId`)
+*   月度数据根节点通常为: `fc982599aa684be7969d7b90b1bd0e84`
+*   可通过 `GET /new/queryIndexTreeAsync?pid=` (空) 获取第一级节点确认。
+
+---
+
+## 使用示例
+
+### 示例一：搜索定位并获取最新 CPI 数据
+
+> 场景：快速获取最近几个月的全国居民消费价格指数 (CPI)
+
+**Step 1: 关键词搜索定位 `cid`**
+
+```bash
+curl "https://data.stats.gov.cn/dg/website/publicrelease/web/external/query?search=CPI&pagenum=1&pageSize=5"
+```
+
+*解析*: 在返回结果中寻找 `type_text` 为 "月度数据" 且 `show_name` 包含 "居民消费价格" 的项。假设找到最新时间段 (2026-) 的 `cid` 为 `5c745282...`。
+
+**Step 2: 获取指标 ID**
+
+```bash
+curl "https://data.stats.gov.cn/dg/website/publicrelease/web/external/new/queryIndicatorsByCid?cid=5c7452825c7c4dcba391db5ca7f335c5"
+```
+
+*解析*: 找到 `i_showname` 为 "居民消费价格指数 (上年同月=100) " 的项，记录其 `_id`，假设为 `ind_cpi_total` (`53180dfb...`)。
+
+**Step 3: 查询数据**
+
+```bash
+curl -X POST "https://data.stats.gov.cn/dg/website/publicrelease/web/external/stream/esData" \
+-H "Content-Type: application/json" \
+-d '{
+  "cid": "5c7452825c7c4dcba391db5ca7f335c5",
+  "indicatorIds": ["53180dfb9c14411ba4b762307c85920c"],
+  "das": [{"text": "全国", "value": "000000000000"}],
+  "dts": ["202601MM-202603MM"],
+  "showType": "1",
+  "rootId": "fc982599aa684be7969d7b90b1bd0e84"
+}'
+```
+
+---
+
+### 示例二：遍历树获取所有月度数据 CID (Python)
+
+> 场景：构建本地索引，获取所有可用的月度数据集 ID
+
+```python
+import requests
+import time
+import json
+
+BASE_URL = "https://data.stats.gov.cn/dg/website/publicrelease/web/external"
+
+def get_tree(pid="", code="1"):
+    """递归获取树结构，收集所有叶子节点 (cid)"""
+    url = f"{BASE_URL}/new/queryIndexTreeAsync"
+    params = {"pid": pid, "code": code}
+    try:
+        resp = requests.get(url, params=params, timeout=10)
+        nodes = resp.json().get('data', [])
+    except Exception as e:
+        print(f"Error fetching tree for pid={pid}: {e}")
+        return []
+
+    cids = []
+    for node in nodes:
+        if node.get('isLeaf'):
+            cids.append({
+                "name": node['name'],
+                "cid": node['_id'],
+                "sdate": node.get('sdate'),
+                "edate": node.get('edate')
+            })
+        else:
+            time.sleep(0.5)
+            sub_cids = get_tree(pid=node['_id'], code=code)
+            cids.extend(sub_cids)
+    return cids
+
+# 执行遍历 (慎用，耗时较长)
+# all_cids = get_tree(code="1")
+# with open('nbs_cids_monthly.json', 'w', encoding='utf-8') as f:
+#     json.dump(all_cids, f, ensure_ascii=False, indent=2)
+```
+
+---
+
+## 最佳实践
+
+### 1. 优先使用搜索接口定位 `cid`
+
+全量遍历树非常耗时（可能有数千个节点）。如果已知关键词（如 "GDP", "CPI", "人口"），先用 `/external/query` 搜索，从结果中提取相关的 `cid` 或线索，再精准查询。
+
+```
+❌ 低效方式：
+   从根节点开始递归遍历整棵树，寻找 "GDP"
+
+✅ 高效方式：
+   search.htm?s=GDP
+   → 从结果中提取 cid 或相关线索
+   → 直接调用 queryIndicatorsByCid
+```
+
+### 2. 处理"时间分片"
+
+**不要假设一个 `cid` 能查到所有历史数据。**
+*   **策略**: 当发现数据缺失（如 `values` 为空）或需要更长历史时，检查相邻的 `cid`（通过树结构查找同级节点，或通过搜索查看是否有其他年份范围的同类指标）。
+*   **合并**: 在客户端按时间戳合并不同 `cid` 返回的数据。
+
+### 3. 缓存元数据
+
+*   **树结构 (`queryIndexTreeAsync`)**: 变化极慢，建议本地缓存 24 小时以上。
+*   **指标列表 (`queryIndicatorsByCid`)**: 变化较慢，建议按 `cid` 缓存。
+*   **数据 (`stream/esData`)**: 每月更新，建议设置较短缓存或按需请求。
+
+### 4. 批量请求减少 IO
+
+`stream/esData` 支持 `indicatorIds` 数组。
+*   ❌ **错误**: 循环调用接口，每次查 1 个指标。
+*   ✅ **正确**: 一次性传入该 `cid` 下所有需要的指标 ID（如 CPI 的总指数、食品、居住等 10 个子类），一次请求拿回所有数据。
+
+### 5. 关注 `i_mark` (统计口径)
+
+在 `queryIndicatorsByCid` 返回的 `i_mark` 字段中，包含了至关重要的统计说明（如"按不变价计算"、"基期为 2020 年"等）。展示数据时务必附带此说明，否则可能导致误读。
+
+### 6. 完整封装示例 (JavaScript/Node.js)
+
+```javascript
+class NbsNewClient {
+  constructor() {
+    this.base = 'https://data.stats.gov.cn/dg/website/publicrelease/web/external';
+    this.rootId = 'fc982599aa684be7969d7b90b1bd0e84';
+  }
+
+  async searchCid(keyword) {
+    const url = `${this.base}/query?search=${encodeURIComponent(keyword)}&pagenum=1&pageSize=10`;
+    const res = await fetch(url);
+    const json = await res.json();
+    return json.data?.data?.map(item => ({
+      name: item.show_name,
+      cid: item.cid || this.extractCidFromGlobalId(item.treeinfo_globalid),
+      type: item.type_text
+    })) || [];
+  }
+
+  extractCidFromGlobalId(globalId) {
+    if (!globalId) return null;
+    const parts = globalId.split('.');
+    return parts[parts.length - 1];
+  }
+
+  async getIndicators(cid) {
+    const url = `${this.base}/new/queryIndicatorsByCid?cid=${cid}`;
+    const res = await fetch(url);
+    const json = await res.json();
+    return json.data?.list || [];
+  }
+
+  async getData(cid, indicatorIds, startTime, endTime, regionCode = "000000000000") {
+    const payload = {
+      cid,
+      indicatorIds,
+      das: [{ text: "全国", value: regionCode }],
+      dts: [`${startTime}-${endTime}`],
+      showType: "1",
+      rootId: this.rootId
+    };
+
+    const res = await fetch(`${this.base}/stream/esData`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+    const json = await res.json();
+
+    if (!json.success) throw new Error(json.message);
+    return json.data;
+  }
+}
+
+// 使用示例
+const client = new NbsNewClient();
+
+async function main() {
+  const results = await client.searchCid("居民消费价格");
+  console.log("Found CIDs:", results);
+
+  const targetCid = results[0].cid;
+
+  const indicators = await client.getIndicators(targetCid);
+  const cpiIndicator = indicators.find(i => i.i_showname.includes("居民消费价格指数 (上年同月=100)"));
+
+  if (cpiIndicator) {
+    const data = await client.getData(
+      targetCid,
+      [cpiIndicator._id],
+      "202601MM",
+      "202603MM"
+    );
+    console.log("CPI Data:", data);
+  }
+}
+
+main();
+```
+
+---
+
+## 接口速查表
+
+| 需求 | 接口 | 关键参数 |
+|------|------|---------|
+| 关键词找数据集 | `GET /query` | `search`, `pagenum` |
+| 浏览分类体系 | `GET /new/queryIndexTreeAsync` | `pid`, `code` |
+| 拿指标 ID | `GET /new/queryIndicatorsByCid` | `cid` |
+| 查历史时间序列 | `POST /stream/esData` | `cid`, `indicatorIds`, `dts`, `showType` |
+| 获取根节点 ID | `GET /new/queryIndexTreeAsync?pid=` | `pid` (空) |

package/package.json

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