matrix-api-mcp 1.1.0__py3-none-any.whl

matrix_api_mcp-1.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: matrix-api-mcp
+Version: 1.1.0
+Summary: MatriX MCP 工具层（AI 助手接入金融数据查询）
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=2.3
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# MatriX
+V1.1.0-Beta Build 20261105
+
+© 2026-2026 Xu Rendong. All Rights Reserved.
+
+### Project Summary
+Quantitative Financial Data Framework.
+
+### Contact Information
+WeChat：xrd_ustc，~~QQ：277195007~~，~~E-mail：xrd@ustc.edu~~

matrix_api_mcp-1.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+matrix_mcp/__init__.py,sha256=hX6p77_JSjgdttxrVVe9xMn_Q4_QvwAM1jL3aFSXsEc,796
+matrix_mcp/__main__.py,sha256=L8ZS9V7TgfRqw-EymCNtQ0WkQ2N9GzTgofbHRLjqIPw,1111
+matrix_mcp/estimate.py,sha256=U9jWihRRqTojCoxRxvZzqis-PO_Xe50sz4wDjGgFzeY,3250
+matrix_mcp/license.txt,sha256=NXw_PcSZFOoVDB3BuDrTXVanE0XIxFtQD6LzGZV77lI,1482
+matrix_mcp/readme.md,sha256=k-t_dPTo_YnmD-v9XqPglFMBCcFwPwPpR3FvjRU2e1M,245
+matrix_mcp/server.py,sha256=U5vwpKqeBUJLQsJ1AOMrnAiafg159cuGJ9jnPfhg84g,2353
+matrix_mcp/tools.py,sha256=22HpfxlQzEtLDofK_BokOUJU860tR9lJqP6FisQygdQ,14926
+matrix_api_mcp-1.1.0.dist-info/METADATA,sha256=Z8inc267Xbli8dwQWoydTfO75umPNVWLVCyOF4INX3E,594
+matrix_api_mcp-1.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+matrix_api_mcp-1.1.0.dist-info/top_level.txt,sha256=iXDu1bAB-6kjRV_0qT-XcOYLFTRKLx4VBWqcZpYjWog,11
+matrix_api_mcp-1.1.0.dist-info/RECORD,,

matrix_api_mcp-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

matrix_api_mcp-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+matrix_mcp

matrix_mcp/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2026 the MatriX authors
+# All rights reserved.
+#
+# The project sponsor and lead author is Xu Rendong.
+# E-mail: xrd@ustc.edu, QQ: 277195007, WeChat: ustc_xrd
+# See the contributors file for names of other contributors.
+#
+# Commercial use of this code in source and binary forms is
+# governed by a LGPL v3 license. You may get a copy from the
+# root directory. Or else you should get a specific written
+# permission from the project author.
+#
+# Individual and educational use of this code in source and
+# binary forms is governed by a 3-clause BSD license. You may
+# get a copy from the root directory. Certainly welcome you
+# contribute code of all sorts.
+#
+# Be sure to retain the above copyright notice and conditions.
+
+# matrix_mcp：MCP Server 封装

matrix_mcp/__main__.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2026 the MatriX authors
+# All rights reserved.
+#
+# The project sponsor and lead author is Xu Rendong.
+# E-mail: xrd@ustc.edu, QQ: 277195007, WeChat: ustc_xrd
+# See the contributors file for names of other contributors.
+#
+# Commercial use of this code in source and binary forms is
+# governed by a LGPL v3 license. You may get a copy from the
+# root directory. Or else you should get a specific written
+# permission from the project author.
+#
+# Individual and educational use of this code in source and
+# binary forms is governed by a 3-clause BSD license. You may
+# get a copy from the root directory. Certainly welcome you
+# contribute code of all sorts.
+#
+# Be sure to retain the above copyright notice and conditions.
+
+# MCP Server 命令行入口：python -m matrix_mcp（设计 5.4.4）。
+# 实际装配在 server.py（MCPServer stdio + 启动清理），此处只做转发，
+# 保持入口单一（whl 分发后各 IDE 以 args ["-m","matrix_mcp"] 拉起）。
+
+from matrix_mcp import server
+
+def Main():
+    server.Main()
+
+if __name__ == "__main__":
+    Main()

matrix_mcp/estimate.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2026 the MatriX authors
+# All rights reserved.
+#
+# The project sponsor and lead author is Xu Rendong.
+# E-mail: xrd@ustc.edu, QQ: 277195007, WeChat: ustc_xrd
+# See the contributors file for names of other contributors.
+#
+# Commercial use of this code in source and binary forms is
+# governed by a LGPL v3 license. You may get a copy from the
+# root directory. Or else you should get a specific written
+# permission from the project author.
+#
+# Individual and educational use of this code in source and
+# binary forms is governed by a 3-clause BSD license. You may
+# get a copy from the root directory. Certainly welcome you
+# contribute code of all sorts.
+#
+# Be sure to retain the above copyright notice and conditions.
+
+# MCP 行数预算三层机制（设计 5.4.2）：客户端识别（默认自动）→ env 覆盖（唯一配置项）
+# → 动态估算（硬保证）。预算只需量级正确：偏大有硬顶兜底、偏小多一跳截断，
+# 模型看到截断提示即自适应（缩小范围/limit 分页/to_file），故不做模型级配置。
+
+import os
+
+# ── 预算常量（5.4.2）──────────────────────────────────────────────────
+ENV_CONTEXT_TOKENS = "MATRIX_MCP_CONTEXT_TOKENS" # 唯一配置项：客户端级上下文预算覆盖
+
+SAFETY_RATIO    = 0.2   # 预算安全系数：数据最多占上下文的 20%
+TOKENS_PER_ROW  = 20    # markdown 表格行实测平均 15~25 token，取中值作估算基线
+MAX_ROWS        = 1000  # 绝对硬顶：无论预算多大，单次回传行数不超此值
+MAX_CHARS       = 32000 # 绝对硬顶：渲染后总字符数上限（双保险）
+UNKNOWN_BUDGET  = 32000 # 未知客户端的保守默认预算
+
+# 已知客户端 → 预算映射（按 initialize 握手 clientInfo.name 子串匹配，小写）。
+# 只列主流大上下文客户端；新客户端默认走 UNKNOWN_BUDGET，无需维护本表也安全。
+CLIENT_BUDGETS = {
+    "claude":    200000,
+    "codex":     200000,
+    "trae":      200000,
+    "workbuddy": 200000,
+    "cursor":    128000,
+    "windsurf":  128000,
+    "vscode":    128000,
+}
+
+def ResolveBudget(client_name = None):
+    # 三层解析：env 覆盖 > 客户端识别表 > 保守默认。
+    # 返回 (预算 token 数, 来源标签)；来源标签进输出头部元信息，模型可见
+    env_val = os.environ.get(ENV_CONTEXT_TOKENS, "").strip()
+    if env_val.isdigit() and int(env_val) > 0:
+        return int(env_val), "env"
+    name = (client_name or "").lower()
+    for key, tokens in CLIENT_BUDGETS.items():
+        if key in name:
+            return tokens, "客户端表"
+    return UNKNOWN_BUDGET, "保守默认"
+
+def AllowedRows(budget, requested = None):
+    # 预算层行数上限：预算×安全系数/每行token，再压绝对硬顶 MAX_ROWS；
+    # requested（Agent 显式 limit）只会更小不会放大。下限保 1 行（预览语义）
+    rows = int(budget * SAFETY_RATIO / TOKENS_PER_ROW)
+    if rows < 1:
+        rows = 1
+    if rows > MAX_ROWS:
+        rows = MAX_ROWS
+    if requested is not None and requested > 0:
+        rows = min(rows, requested)
+    return rows

matrix_mcp/license.txt

@@ -0,0 +1,26 @@
+3-clause BSD License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  * Neither the name of Redis nor the names of its contributors may be used
+    to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+

matrix_mcp/readme.md

@@ -0,0 +1,10 @@
+# MatriX
+V1.1.0-Beta Build 20261105
+
+© 2026-2026 Xu Rendong. All Rights Reserved.
+
+### Project Summary
+Quantitative Financial Data Framework.
+
+### Contact Information
+WeChat：xrd_ustc，~~QQ：277195007~~，~~E-mail：xrd@ustc.edu~~

matrix_mcp/server.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2026 the MatriX authors
+# All rights reserved.
+#
+# The project sponsor and lead author is Xu Rendong.
+# E-mail: xrd@ustc.edu, QQ: 277195007, WeChat: ustc_xrd
+# See the contributors file for names of other contributors.
+#
+# Commercial use of this code in source and binary forms is
+# governed by a LGPL v3 license. You may get a copy from the
+# root directory. Or else you should get a specific written
+# permission from the project author.
+#
+# Individual and educational use of this code in source and
+# binary forms is governed by a 3-clause BSD license. You may
+# get a copy from the root directory. Certainly welcome you
+# contribute code of all sorts.
+#
+# Be sure to retain the above copyright notice and conditions.
+
+# MCP Server 实例与生命周期（设计 5.4）：stdio 传输（所有目标 IDE 均支持），
+# 复用 SDK 走 HTTP API 访问数据服务，不直连数据库。使用 mcp 2.x 官方库
+# （FastMCP 已在其 2.x 更名为 MCPServer，能力等价：tool 装饰器 + stdio 运行）。
+
+import asyncio
+import os
+
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+
+from matrix_api import define
+from matrix_api import fileio
+from matrix_mcp import tools
+
+def CleanupAtStartup():
+    # 启动静默清理 >TTL 的 to_file 历史产出（5.4.5）：文件归调用方管理，
+    # 此策略仅防磁盘膨胀，任何失败不阻断启动
+    env_dir = os.environ.get("MATRIX_MCP_FILE_DIR", "").strip()
+    env_ttl = os.environ.get("MATRIX_MCP_FILE_TTL_DAYS", "").strip()
+    ttl = int(env_ttl) if env_ttl.isdigit() and int(env_ttl) > 0 else 7
+    try:
+        fileio.CleanupOldFiles(directory = Path(env_dir) if env_dir else None, ttl_days = ttl)
+    except Exception:
+        pass
+
+def BuildServer():
+    server = MCPServer(
+        name = "matrix",
+        version = define.APP_VERSION,
+        instructions = "MatriX 金融数据库（A股/基金/期货/期权日频数据）。"
+                       "先用 matrix_dataset_info 了解数据集与字段，再用 matrix_query_data "
+                       "或 matrix_get_daily_quotes 取数；大结果用 to_file=True 落盘后代码读取。",
+    )
+    tools.RegisterTools(server)
+    return server
+
+def Main():
+    CleanupAtStartup()
+    server = BuildServer()
+    asyncio.run(server.run_stdio_async())

matrix_mcp/tools.py

@@ -0,0 +1,306 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2026 the MatriX authors
+# All rights reserved.
+#
+# The project sponsor and lead author is Xu Rendong.
+# E-mail: xrd@ustc.edu, QQ: 277195007, WeChat: ustc_xrd
+# See the contributors file for names of other contributors.
+#
+# Commercial use of this code in source and binary forms is
+# governed by a LGPL v3 license. You may get a copy from the
+# root directory. Or else you should get a specific written
+# permission from the project author.
+#
+# Individual and educational use of this code in source and
+# binary forms is governed by a 3-clause BSD license. You may
+# get a copy from the root directory. Certainly welcome you
+# contribute code of all sorts.
+#
+# Be sure to retain the above copyright notice and conditions.
+
+# MCP 工具定义（设计 5.4.1）：五个工具全部复用 SDK 门面（matrix_api.wind），
+# 本模块只做三件事——上下文预算裁剪（estimate 三层）、markdown 渲染、
+# to_file 落盘摘要。工具 docstring 即 Agent 看到的说明（自解释，5.4.2），
+# 是编码风格中唯一的 docstring 例外。函数定义为模块级（便于单测直取），
+# 由 RegisterTools 统一挂到 MCPServer；ctx 参数标注 Context 类型，
+# MCP 框架据此注入会话上下文（并自动排除出 JSON schema）。
+
+import os
+
+from pathlib import Path
+
+from mcp.server.mcpserver import Context
+
+import matrix_api
+
+from matrix_api import define
+from matrix_api import fileio
+from matrix_mcp import estimate
+
+# 预算来源 → 人读标签（元信息行展示，5.4.2）
+SOURCE_LABELS = {
+    "env": "环境变量 %s" % estimate.ENV_CONTEXT_TOKENS,
+    "客户端表": "客户端识别表",
+    "保守默认": "保守默认(32k)",
+}
+
+TRUNCATE_HINT = ("⚠ 结果已按上下文预算截断。建议：缩小日期范围 / 减少代码数量 / "
+                 "用 limit 参数分页 / 改用 to_file=True 落盘后用代码读取全量数据。")
+
+_wind = None
+
+def GetWind():
+    # 进程级 SDK 会话：MCP 无状态，stdio 进程随客户端会话启停，单会话够用。
+    # 认证码经环境变量 MATRIX_TOKEN 透传（mcp.json 的 env 保存，SDK 侧读取）；
+    # User-Agent 自报 matrix-mcp 渠道，服务端访问日志据此区分来源
+    global _wind
+    if _wind is None:
+        _wind = matrix_api.wind(user_agent = "matrix_mcp/%s" % define.APP_VERSION)
+    return _wind
+
+def ClientName(ctx):
+    # initialize 握手的 clientInfo.name 是识别层唯一输入；mcp 2.x pydantic
+    # 字段为 snake_case（client_info），1.x 风格 camelCase 一并兼容；
+    # 测试环境/异常链路任何一环缺失都回退空串（走保守默认预算）
+    try:
+        params = ctx.request_context.session.client_params
+        info = getattr(params, "client_info", None) or getattr(params, "clientInfo", None)
+        return getattr(info, "name", "") or ""
+    except Exception:
+        return ""
+
+def ErrorText(result):
+    # 门面永不抛异常，失败统一渲染为人读文本（模型可读错误码自助纠正）
+    return "查询失败（错误码 %d）：%s" % (result.code, result.msg)
+
+def RenderValue(value):
+    # 单元格 → markdown 安全字符串：空值/NaN 置空，竖线与换行转义
+    if value is None:
+        return ""
+    if isinstance(value, float) and value != value:
+        return ""
+    text = str(value)
+    return text.replace("|", "\\|").replace("\n", " ")
+
+def RenderDataFrame(df, cap_rows, cap_chars):
+    # DataFrame → markdown 表格文本；双重上限（行数/字符数）取先到者。
+    # 返回 (行文本列表, 实际展示行数)——字符硬顶触发时展示行数 < cap_rows
+    header = "| " + " | ".join(str(c) for c in df.columns) + " |"
+    sep = "|" + "|".join(["---"] * len(df.columns)) + "|"
+    lines = [header, sep]
+    total = len(header) + len(sep)
+    shown = 0
+    for i in range(min(len(df), cap_rows)):
+        row = "| " + " | ".join(RenderValue(v) for v in df.iloc[i].tolist()) + " |"
+        if shown >= 1 and total + len(row) > cap_chars:
+            break
+        lines.append(row)
+        total += len(row)
+        shown += 1
+    return lines, shown
+
+def MetaLine(title, total_text, shown, cap, source):
+    # 头部元信息行（5.4.2）：总行数/返回数/上限/预算来源，模型据此自主决策
+    return "【MatriX】%s ｜ 总行数 %s ｜ 本次返回 %d 行 ｜ 回传上限 %d 行 ｜ 预算来源：%s" % (
+        title, total_text, shown, cap, SOURCE_LABELS.get(source, source))
+
+def TotalText(df):
+    # 服务端 LIMIT+1 探测只告知是否截断、不告知截断后总数，
+    # 诚实展示 "≥N" 而非假总数
+    truncated = bool(df.attrs.get("truncated", False))
+    if truncated:
+        return "≥%d（已截断）" % len(df)
+    return str(len(df))
+
+def RenderQuery(dataset, r, cap, source, preview_only = False, title = None):
+    # 查询类工具公共渲染：元信息行 + markdown 表 + 截断提示
+    df = r.data
+    if df is None or len(df) == 0:
+        return "查询成功但无数据（数据集 %s，可能该区间无记录，可放宽条件重试）" % dataset
+    if preview_only:
+        cap = min(cap, 5) # 预览模式：只给元信息 + 前 5 行样本
+    lines, shown = RenderDataFrame(df, cap, estimate.MAX_CHARS)
+    out = [MetaLine(title or ("数据集 %s（版本 %s）" % (dataset, r.version or "?")),
+                    TotalText(df), shown, cap, source)]
+    out.extend(lines)
+    if shown < len(df) or bool(df.attrs.get("truncated", False)):
+        out.append(TRUNCATE_HINT)
+    return "\n".join(out)
+
+def ResolveFileDir(output_dir):
+    # to_file 目录：显式参数 > env MATRIX_MCP_FILE_DIR > SDK 缺省路径
+    if output_dir:
+        return Path(output_dir)
+    env_dir = os.environ.get("MATRIX_MCP_FILE_DIR", "").strip()
+    if env_dir:
+        return Path(env_dir)
+    return None
+
+def matrix_dataset_info(dataset: str = None) -> str:
+    """查询 MatriX 金融数据库的数据集元信息。
+
+    不传 dataset：返回全部数据集清单（名称/中文说明/类别/频率/可用版本）。
+    传 dataset（如 stock_daily_quotes）：返回该数据集详情——字段清单
+    （英文名/中文说明/类型/别名）、时间列与代码列、支持的复权方式、
+    可用交易所与版本，并附查询示例。
+
+    典型用法：先不传参浏览全部数据集，再传名称看字段明细，
+    然后用 matrix_query_data 取数。"""
+    r = GetWind().dataset_info(dataset)
+    if not r.ok:
+        return ErrorText(r)
+    data = r.data
+    if dataset is None:
+        rows = ["| 数据集 | 说明 | 类别 | 频率 | 字段数 | 版本 |",
+                "|---|---|---|---|---|---|"]
+        for item in data or []:
+            rows.append("| %s | %s | %s | %s | %s | %s |" % (
+                item.get("name", ""), item.get("title", ""), item.get("category", ""),
+                item.get("freq", ""), item.get("field_count", ""),
+                ",".join(item.get("versions", []))))
+        head = "【MatriX】全部数据集清单 ｜ 共 %d 个（详情传 dataset 参数）" % len(data or [])
+        return "\n".join([head] + rows)
+    rows = ["| 字段 | 说明 | 类型 | 别名 |", "|---|---|---|---|"]
+    for f in data.get("fields", []):
+        rows.append("| %s | %s | %s | %s |" % (
+            f.get("name", ""), f.get("desc", ""), f.get("type", ""),
+            ",".join(f.get("aliases", []))))
+    head = "【MatriX】数据集 %s（%s）｜ 类别 %s ｜ 频率 %s ｜ 时间列 %s ｜ 代码列 %s ｜ 复权 %s ｜ 版本 %s" % (
+        data.get("name", ""), data.get("title", ""), data.get("category", ""),
+        data.get("freq", ""), data.get("time_field", "") or "无",
+        data.get("symbol_field", "") or "无",
+        "/".join(data.get("adjust", [])) or "不支持",
+        ",".join(data.get("versions", [])))
+    example = ("查询示例：matrix_query_data(dataset=\"%s\", symbols=\"600519.SH\", "
+               "start_date=\"20261008\", end_date=\"20261027\", fields=\"date_t,symbol,close\")"
+               % data.get("name", ""))
+    return "\n".join([head] + rows + ["", example])
+
+def matrix_query_data(dataset: str, symbols: str = None, start_date: str = None,
+                      end_date: str = None, fields: str = None, limit: int = None,
+                      version: str = None, preview_only: bool = False,
+                      to_file: bool = False, output_dir: str = None,
+                      ctx: Context = None) -> str:
+    """通用数据查询（MatriX 金融数据库，PostgreSQL 日频数据）。
+
+    参数：
+    - dataset（必填）：数据集名，如 stock_daily_quotes（股票日行情）、
+      index_daily_quotes（指数日行情）、fund_daily_quotes（基金日行情）、
+      future_daily_quotes（期货日行情）。全部清单用 matrix_dataset_info 查看。
+    - symbols：逗号分隔的证券代码，如 "600519.SH,000001.SZ"；不传=全市场。
+    - start_date / end_date：日期 YYYYMMDD（如 20261008）。
+    - fields：逗号分隔的字段名，如 "date_t,symbol,close"；不传=全部字段。
+    - limit：本次最多返回行数（会再受上下文预算约束）。
+    - version：数据版本（一般不传，用当前版本）。
+    - preview_only=True：只返回元信息与前 5 行样本（探查数据形态用）。
+    - to_file=True：大数据模式——全量数据不受预算裁剪，直接落盘为本地
+      Parquet 文件，只返回文件摘要包（路径/行数/列/样本/读取示例），
+      之后用代码 pd.read_parquet(路径) 读取分析，数据不进对话上下文。
+
+    返回：markdown 表格，头部含总行数/返回行数/回传上限/预算来源；
+    被截断时会提示缩小范围、分页或改用 to_file。
+
+    示例：matrix_query_data(dataset="stock_daily_quotes", symbols="600519.SH",
+    start_date="20261008", end_date="20261027", fields="date_t,close")"""
+    budget, source = estimate.ResolveBudget(ClientName(ctx))
+    if to_file:
+        # to_file 不受上下文预算裁剪（数据不进上下文，5.4.5），
+        # 受服务端 max_rows 硬顶与 statement_timeout 约束
+        r = GetWind().get_data(dataset, symbols = symbols, fields = fields,
+                               start_date = start_date, end_date = end_date,
+                               version = version)
+        if not r.ok or r.data is None or len(r.data) == 0:
+            return ErrorText(r) if not r.ok else "查询成功但无数据，未落盘"
+        try:
+            path = fileio.SaveParquet(r, path = ResolveFileDir(output_dir))
+        except Exception as e:
+            return "落盘失败：%s" % e
+        return fileio.BuildSummary(r.data, path)
+    cap = estimate.AllowedRows(budget, limit)
+    r = GetWind().get_data(dataset, symbols = symbols, fields = fields,
+                           start_date = start_date, end_date = end_date,
+                           version = version, limit = cap)
+    if not r.ok:
+        return ErrorText(r)
+    return RenderQuery(dataset, r, cap, source, preview_only = preview_only)
+
+def matrix_get_daily_quotes(symbol: str, start_date: str, end_date: str,
+                            fields: str = None, adjust: str = None,
+                            ctx: Context = None) -> str:
+    """取单个证券的日行情时间序列（最常用快捷方式）。
+
+    参数：
+    - symbol（必填）：证券代码，如 "600519.SH"（贵州茅台）、"IM_S"（股指期货主力连续）。
+    - start_date / end_date（必填）：日期 YYYYMMDD，闭区间。
+    - fields：逗号分隔字段，如 "date_t,close,volume"；不传=全部字段。
+    - adjust：复权方式——None 不复权；"forward" 前复权；"backward" 后复权（仅股票/基金）。
+
+    返回：markdown 表格，头部含总行数/返回行数/回传上限；区间太长被截断时，
+    请缩小日期范围或改用 matrix_query_data(..., to_file=True) 落盘全量。
+
+    示例：matrix_get_daily_quotes(symbol="600519.SH", start_date="20261008",
+    end_date="20261027", fields="date_t,close", adjust="forward")"""
+    budget, source = estimate.ResolveBudget(ClientName(ctx))
+    cap = estimate.AllowedRows(budget, None)
+    r = GetWind().wsd(symbol, fields, start = start_date, end = end_date, adjust = adjust)
+    if not r.ok:
+        return ErrorText(r)
+    return RenderQuery("日行情 %s" % symbol, r, cap, source,
+                       title = "%s 日行情（版本 %s）" % (symbol, r.version or "?"))
+
+def matrix_trading_dates(start_date: str, end_date: str, ctx: Context = None) -> str:
+    """查询交易日历（闭区间，升序）。
+
+    参数：
+    - start_date / end_date（必填）：日期 YYYYMMDD，如 20260101~20261231。
+
+    返回：交易日列表（同样受上下文预算截断保护，年份范围很大时会被截断，
+    可分段查询）。
+
+    示例：matrix_trading_dates(start_date="20261001", end_date="20261031")"""
+    budget, source = estimate.ResolveBudget(ClientName(ctx))
+    cap = estimate.AllowedRows(budget, None)
+    r = GetWind().get_trading_dates(start = start_date, end = end_date)
+    if not r.ok:
+        return ErrorText(r)
+    dates = r.data or []
+    if not dates:
+        return "查询成功但该区间无交易日"
+    shown = dates[:cap]
+    head = MetaLine("交易日历 %s~%s" % (start_date, end_date),
+                    str(len(dates)), len(shown), cap, source)
+    lines = [head, "| trading_date |", "|---|"]
+    lines.extend("| %s |" % d for d in shown)
+    if len(shown) < len(dates):
+        lines.append("⚠ 已截断至 %d 行，请分段查询。" % cap)
+    return "\n".join(lines)
+
+def matrix_is_trading_date(date: str) -> str:
+    """判断指定日期是否为A股交易日，并给出最近的已过去交易日。
+
+    参数：
+    - date（必填）：日期 YYYYMMDD，如 20261003。
+
+    返回：是/否 + 最近交易日（≤该日期的最后一个交易日）。
+
+    示例：matrix_is_trading_date(date="20261003")"""
+    r = GetWind().get_trading_dates(end = date)
+    if not r.ok:
+        return ErrorText(r)
+    dates = r.data or []
+    if not dates:
+        return "查询失败：交易日历为空"
+    iso = "%s-%s-%s" % (date[:4], date[4:6], date[6:8]) if len(date) == 8 else date
+    if iso in dates:
+        return "%s 是交易日（即最近交易日）" % iso
+    return "%s 不是交易日，最近交易日为 %s" % (iso, dates[-1])
+
+# 注册顺序即 Agent 工具列表展示顺序（5.4.1 清单顺序）
+ALL_TOOLS = (matrix_dataset_info, matrix_query_data, matrix_get_daily_quotes,
+             matrix_trading_dates, matrix_is_trading_date)
+
+def RegisterTools(server):
+    # 由 server.py 调用：模块级工具统一挂载（名称取函数名，说明取 docstring）
+    for fn in ALL_TOOLS:
+        server.tool()(fn)