tushare-mcp-server 1.0.0

package/server.py

@@ -0,0 +1,736 @@
+"""
+Tushare MCP Server - 提供 Tushare 金融数据 API 接口
+通过 MCP 协议暴露 Tushare Pro API，支持沪深股票、指数、基金、期货、期权等数据查询。
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# ── 配置 ──────────────────────────────────────────────────────────────
+TUSHARE_API_URL = "http://api.tushare.pro"
+
+# 支持 .env 文件加载 token
+def _load_env_token() -> str:
+    """从 .env 文件或环境变量读取 TUSHARE_TOKEN"""
+    token = os.environ.get("TUSHARE_TOKEN", "")
+    if token:
+        return token
+    env_path = Path(__file__).parent / ".env"
+    if env_path.exists():
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            if k.strip() == "TUSHARE_TOKEN":
+                return v.strip().strip("'\"")
+    return ""
+
+TUSHARE_TOKEN = _load_env_token()
+
+mcp = FastMCP(
+    "Tushare",
+    instructions=(
+        "Tushare 金融数据 MCP 服务器。提供 A 股、指数、基金、期货、期权、债券、"
+        "外汇、港股、美股、宏观经济等全方位金融数据查询。\n"
+        "使用前请确保已设置 TUSHARE_TOKEN 环境变量。\n"
+        "所有日期参数格式为 YYYYMMDD，股票代码格式如 000001.SZ、600000.SH。\n"
+        "如需查看某个接口的详细参数说明，请使用 search_api_docs 工具搜索关键词。"
+    ),
+)
+
+# ── 加载爬取的文档与索引 ──────────────────────────────────────────────
+DOCS_DIR = Path(__file__).parent / "docs"
+_docs_cache: dict[str, str] = {}  # filename_stem -> content
+_api_index: dict[str, dict] = {}  # api_name -> {title, doc_id, description, file}
+
+
+def _load_docs() -> dict[str, str]:
+    """加载 docs/ 目录下所有 Markdown 文档到内存"""
+    if _docs_cache:
+        return _docs_cache
+    if not DOCS_DIR.exists():
+        return _docs_cache
+    for f in sorted(DOCS_DIR.glob("*.md")):
+        if f.name.startswith("_"):
+            continue
+        _docs_cache[f.stem] = f.read_text(encoding="utf-8")
+    return _docs_cache
+
+
+def _load_api_index() -> dict[str, dict]:
+    """加载 api_name -> 文档信息 的结构化索引"""
+    if _api_index:
+        return _api_index
+    index_path = DOCS_DIR / "_api_index.json"
+    if index_path.exists():
+        import json as _json
+        data = _json.loads(index_path.read_text(encoding="utf-8"))
+        _api_index.update(data)
+    return _api_index
+
+
+# ── 复用 httpx 客户端 ─────────────────────────────────────────────────
+_http_client: httpx.AsyncClient | None = None
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _http_client
+    if _http_client is None or _http_client.is_closed:
+        _http_client = httpx.AsyncClient(timeout=30)
+    return _http_client
+
+
+# ── 核心请求函数 ──────────────────────────────────────────────────────
+async def _call_tushare(
+    api_name: str,
+    params: dict[str, Any] | None = None,
+    fields: str = "",
+    limit: int = 5000,
+) -> dict[str, Any]:
+    """调用 Tushare HTTP API 并返回结果。"""
+    if not TUSHARE_TOKEN:
+        return {"error": "未设置 TUSHARE_TOKEN 环境变量，请在启动 MCP 时配置，或在项目根目录创建 .env 文件。"}
+
+    payload: dict[str, Any] = {
+        "api_name": api_name,
+        "token": TUSHARE_TOKEN,
+        "params": params or {},
+    }
+    if fields:
+        payload["fields"] = fields
+
+    client = _get_client()
+    try:
+        resp = await client.post(TUSHARE_API_URL, json=payload)
+        resp.raise_for_status()
+    except httpx.TimeoutException:
+        return {"error": "请求超时，Tushare API 响应过慢。", "hint": "请稍后重试，或缩小查询范围（添加日期/代码过滤）。"}
+    except httpx.HTTPStatusError as e:
+        return {"error": f"HTTP {e.response.status_code}", "hint": "Tushare API 服务异常，请稍后重试。"}
+    except httpx.HTTPError as e:
+        return {"error": f"网络错误: {type(e).__name__}", "hint": "请检查网络连接。"}
+    data = resp.json()
+
+    if data.get("code") != 0:
+        msg = data.get("msg", "未知错误")
+        error_info: dict[str, Any] = {"error": msg, "code": data.get("code")}
+        # 为常见错误添加恢复建议
+        if "权限" in msg or "积分" in msg:
+            error_info["hint"] = "此接口需要更高积分权限。请在 tushare.pro 查看积分要求，或使用替代接口。"
+        elif "频率" in msg or "每分钟" in msg:
+            error_info["hint"] = "请求过于频繁，请稍后重试。建议：减少请求频率，或缩小查询范围。"
+        elif "参数" in msg:
+            error_info["hint"] = f"请用 get_api_doc('{api_name}') 查看正确的参数格式。"
+        return error_info
+
+    # 将 fields + items 转换为易读的 records 格式
+    result = data.get("data", {})
+    columns = result.get("fields", [])
+    items = result.get("items", [])
+
+    if not items:
+        return {"columns": columns, "records": [], "total": 0}
+
+    shown = min(len(items), limit)
+    records = [dict(zip(columns, row)) for row in items[:shown]]
+    out: dict[str, Any] = {
+        "columns": columns,
+        "records": records,
+        "total": len(items),
+        "shown": shown,
+    }
+    if len(items) > shown:
+        out["hint"] = f"共 {len(items)} 条记录，仅显示前 {shown} 条。可通过 start_date/end_date 缩小范围分批获取。"
+    return out
+
+
+# ── 通用查询工具 ──────────────────────────────────────────────────────
+@mcp.tool()
+async def tushare_query(
+    api_name: str,
+    params: dict[str, Any] | None = None,
+    fields: str = "",
+) -> str:
+    """通用 Tushare API 查询工具，可调用任意 Tushare Pro 接口。
+
+    使用流程：
+    1. 先用 get_api_doc(api_name) 查看接口的详细参数说明
+    2. 或用 search_api_docs(keyword) 按关键词搜索接口
+    3. 然后用本工具传入 api_name 和 params 执行查询
+
+    通用说明：
+    - 日期格式: YYYYMMDD (如 20241231)
+    - 股票代码: 000001.SZ(深) 600000.SH(沪) 830799.BJ(北)
+    - 指数代码: 000001.SH(上证综指) 399001.SZ(深证成指)
+    - 基金代码: 510050.SH(场内ETF) 000001.OF(场外)
+    - 期货代码: CU2401.SHF(沪铜) IF2401.CFX(股指)
+
+    Args:
+        api_name: Tushare 接口名称，如 'daily', 'stock_basic', 'income' 等
+        params: 接口参数字典，如 {"ts_code": "000001.SZ", "start_date": "20240101"}
+        fields: 指定返回字段(逗号分隔)，为空则返回全部默认字段
+    """
+    result = await _call_tushare(api_name, params, fields)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：股票基础 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_stock_list(
+    list_status: str = "L",
+    exchange: str = "",
+) -> str:
+    """获取 A 股股票列表。
+
+    Args:
+        list_status: 上市状态。L-上市 D-退市 P-暂停上市，默认 L
+        exchange: 交易所。SSE-上交所 SZSE-深交所 BSE-北交所，留空返回全部
+    """
+    result = await _call_tushare(
+        "stock_basic",
+        {"exchange": exchange, "list_status": list_status},
+        "ts_code,symbol,name,area,industry,market,list_date,list_status",
+    )
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_trade_calendar(
+    exchange: str = "SSE",
+    start_date: str = "",
+    end_date: str = "",
+    is_open: str = "",
+) -> str:
+    """获取交易日历。
+
+    Args:
+        exchange: 交易所代码。SSE-上交所 SZSE-深交所 CFFEX-中金所 SHFE-上期所
+                  CZCE-郑商所 DCE-大商所 INE-上能源
+        start_date: 开始日期 YYYYMMDD
+        end_date: 结束日期 YYYYMMDD
+        is_open: 是否交易 '0'休市 '1'交易，留空返回全部
+    """
+    params: dict[str, Any] = {"exchange": exchange}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    if is_open:
+        params["is_open"] = is_open
+    result = await _call_tushare("trade_cal", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：行情数据 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_daily_bars(
+    ts_code: str = "",
+    trade_date: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取 A 股日线行情（未复权），交易日 15 点后更新。
+
+    Args:
+        ts_code: 股票代码(如 000001.SZ)，支持多个逗号分隔。与 trade_date 二选一
+        trade_date: 交易日期 YYYYMMDD，获取当天全市场行情。与 ts_code 二选一
+        start_date: 开始日期 YYYYMMDD
+        end_date: 结束日期 YYYYMMDD
+    """
+    params: dict[str, Any] = {}
+    if ts_code:
+        params["ts_code"] = ts_code
+    if trade_date:
+        params["trade_date"] = trade_date
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("daily", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_daily_basic(
+    ts_code: str = "",
+    trade_date: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取每日指标：PE/PB/PS/总市值/流通市值/换手率/股息率等。
+
+    Args:
+        ts_code: 股票代码(如 000001.SZ)。与 trade_date 二选一
+        trade_date: 交易日期 YYYYMMDD。与 ts_code 二选一
+        start_date: 开始日期 YYYYMMDD
+        end_date: 结束日期 YYYYMMDD
+    """
+    params: dict[str, Any] = {}
+    if ts_code:
+        params["ts_code"] = ts_code
+    if trade_date:
+        params["trade_date"] = trade_date
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("daily_basic", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：财务数据 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_income(
+    ts_code: str,
+    period: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取上市公司利润表。
+
+    Args:
+        ts_code: 股票代码(如 600000.SH)
+        period: 报告期 YYYYMMDD(如 20231231 表示2023年报)
+        start_date: 公告开始日期
+        end_date: 公告结束日期
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if period:
+        params["period"] = period
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("income", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_balancesheet(
+    ts_code: str,
+    period: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取上市公司资产负债表。
+
+    Args:
+        ts_code: 股票代码
+        period: 报告期 YYYYMMDD
+        start_date: 公告开始日期
+        end_date: 公告结束日期
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if period:
+        params["period"] = period
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("balancesheet", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_cashflow(
+    ts_code: str,
+    period: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取上市公司现金流量表。
+
+    Args:
+        ts_code: 股票代码
+        period: 报告期 YYYYMMDD
+        start_date: 公告开始日期
+        end_date: 公告结束日期
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if period:
+        params["period"] = period
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("cashflow", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_fina_indicator(
+    ts_code: str,
+    period: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取上市公司财务指标(ROE/ROA/毛利率/净利率等综合指标)。
+
+    Args:
+        ts_code: 股票代码
+        period: 报告期 YYYYMMDD
+        start_date: 公告开始日期
+        end_date: 公告结束日期
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if period:
+        params["period"] = period
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("fina_indicator", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：指数 ───────────────────────────────────────────────────
+@mcp.tool()
+async def get_index_daily(
+    ts_code: str,
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取指数日线行情。
+
+    常用指数代码:
+    - 000001.SH 上证综指
+    - 399001.SZ 深证成指
+    - 399006.SZ 创业板指
+    - 000300.SH 沪深300
+    - 000905.SH 中证500
+    - 000688.SH 科创50
+
+    Args:
+        ts_code: 指数代码
+        start_date: 开始日期 YYYYMMDD
+        end_date: 结束日期 YYYYMMDD
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("index_daily", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：资金流向 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_moneyflow(
+    ts_code: str = "",
+    trade_date: str = "",
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取个股资金流向数据。
+
+    Args:
+        ts_code: 股票代码。与 trade_date 二选一
+        trade_date: 交易日期 YYYYMMDD。与 ts_code 二选一
+        start_date: 开始日期
+        end_date: 结束日期
+    """
+    params: dict[str, Any] = {}
+    if ts_code:
+        params["ts_code"] = ts_code
+    if trade_date:
+        params["trade_date"] = trade_date
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("moneyflow", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：概念板块 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_concept(src: str = "ts") -> str:
+    """获取概念股分类，分析市场热点主题。
+
+    Args:
+        src: 来源。ts-Tushare sina-新浪
+    """
+    result = await _call_tushare("concept", {"src": src})
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_concept_detail(
+    concept_id: str = "",
+    ts_code: str = "",
+) -> str:
+    """查询概念股成分列表，或查某只股票属于哪些概念。
+
+    Args:
+        concept_id: 概念ID (从 get_concept 获取)。与 ts_code 二选一
+        ts_code: 股票代码。与 concept_id 二选一
+    """
+    params: dict[str, Any] = {}
+    if concept_id:
+        params["id"] = concept_id
+    if ts_code:
+        params["ts_code"] = ts_code
+    result = await _call_tushare("concept_detail", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：基金 ───────────────────────────────────────────────────
+@mcp.tool()
+async def get_fund_basic(
+    market: str = "E",
+    status: str = "L",
+) -> str:
+    """获取公募基金列表。
+
+    Args:
+        market: E-场内(ETF等) O-场外
+        status: D-摘牌 I-发行中 L-已上市
+    """
+    result = await _call_tushare("fund_basic", {"market": market, "status": status})
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+async def get_fund_nav(
+    ts_code: str,
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取基金净值数据。
+
+    Args:
+        ts_code: 基金代码(如 510050.SH)
+        start_date: 开始日期
+        end_date: 结束日期
+    """
+    params: dict[str, Any] = {"ts_code": ts_code}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("fund_nav", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── 便捷工具：宏观经济 ───────────────────────────────────────────────
+@mcp.tool()
+async def get_shibor(
+    start_date: str = "",
+    end_date: str = "",
+) -> str:
+    """获取 Shibor 拆借利率数据。
+
+    Args:
+        start_date: 开始日期 YYYYMMDD
+        end_date: 结束日期 YYYYMMDD
+    """
+    params: dict[str, Any] = {}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    result = await _call_tushare("shibor", params)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+# ── API 文档工具 ──────────────────────────────────────────────────────
+@mcp.tool()
+async def get_api_doc(api_name: str) -> str:
+    """按接口名获取 Tushare API 的完整文档（参数、字段、示例、限量说明等）。
+
+    这是查询某个已知接口详细用法的最佳方式。
+    如果不确定接口名，请先用 search_api_docs 搜索。
+
+    Args:
+        api_name: Tushare 接口名，如 'daily', 'stock_basic', 'income',
+                  'fund_nav', 'index_daily', 'cb_daily', 'margin' 等
+    """
+    index = _load_api_index()
+    docs = _load_docs()
+
+    # 检查是否有别名（同名冲突的接口）
+    aliases = [n for n in index if "__" in n and n.split("__")[0] == api_name]
+
+    # 精确匹配
+    if api_name in index:
+        file_stem = index[api_name]["file"].replace(".md", "")
+        if file_stem in docs:
+            result = docs[file_stem]
+            # 如果有别名，追加提示
+            for alias in aliases:
+                alias_info = index[alias]
+                result += f"\n\n---\n> 注意：还有一个同名接口 `{alias}`（{alias_info['title']}），可用 get_api_doc('{alias}') 查看。"
+            return result
+
+    # 别名精确匹配（如 trade_cal__期货交易日历）
+    if api_name in index:
+        pass  # already handled above
+    for name, info in index.items():
+        if name == api_name:
+            file_stem = info["file"].replace(".md", "")
+            if file_stem in docs:
+                return docs[file_stem]
+
+    # 模糊匹配：接口名包含关键词 (要求至少4字符，避免短词误匹配)
+    candidates = []
+    if len(api_name) >= 4:
+        for name, info in index.items():
+            if name.startswith("_"):
+                continue
+            # 双向包含，但要求被包含方至少4字符，防止 "st" in "not_exist" 类误匹配
+            if (api_name in name) or (name in api_name and len(name) >= 4):
+                candidates.append((name, info))
+
+    if len(candidates) == 1:
+        file_stem = candidates[0][1]["file"].replace(".md", "")
+        if file_stem in docs:
+            return docs[file_stem]
+
+    if candidates:
+        result = f"未找到精确匹配 '{api_name}'，以下接口可能相关：\n\n"
+        for name, info in candidates:
+            result += f"- **{name}**: {info['title']} — {info['description']}\n"
+        result += "\n请使用精确的接口名重新查询。"
+        return result
+
+    return (
+        f"未找到接口 '{api_name}'。\n"
+        f"请使用 search_api_docs 按关键词搜索，或查看 tushare://api-reference 获取完整接口列表。"
+    )
+
+
+@mcp.tool()
+async def search_api_docs(keyword: str) -> str:
+    """按关键词搜索 Tushare API 文档，适用于不确定接口名时的模糊查找。
+
+    搜索范围包括接口名、中文标题、参数名、字段描述等。
+    找到接口后，请用 get_api_doc(api_name) 获取完整文档。
+
+    Args:
+        keyword: 搜索关键词，如 "融资融券" "利润" "PE" "ETF" "港股" 等
+    """
+    index = _load_api_index()
+    docs = _load_docs()
+    if not docs:
+        return "文档目录为空，请先运行 crawl_docs.py 爬取文档。"
+
+    # 短关键词用单词边界匹配减少噪音
+    if len(keyword) <= 3 and keyword.isascii():
+        pattern = re.compile(r"(?<![a-zA-Z])" + re.escape(keyword) + r"(?![a-zA-Z])", re.IGNORECASE)
+    else:
+        pattern = re.compile(re.escape(keyword), re.IGNORECASE)
+
+    scored_matches: list[tuple[int, str]] = []  # (score, result_text)
+
+    for name, content in docs.items():
+        hit_count = len(pattern.findall(content)) + len(pattern.findall(name))
+        if hit_count == 0:
+            continue
+
+        lines = content.split("\n")
+        title_line = lines[0] if lines else name
+
+        # 从索引中找到 api_name
+        api_name_str = ""
+        for api_n, info in index.items():
+            if info["file"].replace(".md", "") == name:
+                api_name_str = api_n
+                break
+
+        # 计算相关性分数
+        score = hit_count
+        # 标题匹配加权
+        if pattern.search(title_line):
+            score += 50
+        # 接口名匹配加权
+        if api_name_str and pattern.search(api_name_str):
+            score += 30
+
+        # 提取不重叠的上下文片段
+        relevant = []
+        covered = set()
+        for i, line in enumerate(lines):
+            if pattern.search(line) and i not in covered:
+                start = max(0, i - 1)
+                end = min(len(lines), i + 4)
+                snippet = "\n".join(lines[start:end])
+                relevant.append(snippet)
+                covered.update(range(start, end))
+
+        if relevant:
+            header = f"### {title_line}"
+            if api_name_str and not api_name_str.startswith("_"):
+                header += f"  (接口: `{api_name_str}`)"
+            result = header + "\n\n"
+            result += "\n...\n".join(relevant[:2])  # 最多2个片段
+            scored_matches.append((score, result))
+
+    if not scored_matches:
+        return f"未找到与 '{keyword}' 相关的文档。请尝试其他关键词。"
+
+    # 按相关性排序，取前8
+    scored_matches.sort(key=lambda x: -x[0])
+    top = scored_matches[:8]
+
+    header = f"找到 {len(scored_matches)} 个相关文档（按相关度排序，显示前 {len(top)} 个）：\n\n"
+    return header + "\n\n---\n\n".join(r for _, r in top)
+
+
+@mcp.resource("tushare://api-reference")
+def get_api_reference() -> str:
+    """Tushare Pro API 完整接口索引（按类别分组），列出所有可用接口及简要说明。
+    使用 get_api_doc(api_name) 获取具体接口的完整文档。"""
+    index = _load_api_index()
+    if not index:
+        return "API 索引为空，请先运行 build_index.py。"
+
+    # 按 category 分组
+    cats: dict[str, list[tuple[str, dict]]] = {}
+    for api_name, info in sorted(index.items()):
+        if api_name.startswith("_"):
+            continue
+        cat = info.get("category", "其他")
+        cats.setdefault(cat, []).append((api_name, info))
+
+    # 固定分类顺序
+    CAT_ORDER = [
+        "沪深股票", "财务数据", "资金流向", "市场参考", "指数数据", "概念板块",
+        "基金数据", "期货数据", "期权数据", "债券/可转债", "港股数据", "美股数据",
+        "外汇数据", "黄金现货", "宏观经济", "交易日历", "新闻公告", "其他",
+    ]
+
+    total = sum(len(v) for v in cats.values())
+    lines = [
+        "# Tushare Pro API 接口索引",
+        "",
+        f"共 {total} 个接口，分 {len(cats)} 个类别。使用 `get_api_doc(api_name)` 获取完整文档。",
+        "",
+    ]
+
+    for cat in CAT_ORDER:
+        if cat not in cats:
+            continue
+        items = cats[cat]
+        lines.append(f"## {cat} ({len(items)})")
+        lines.append("")
+        lines.append("| 接口名 | 名称 | 说明 |")
+        lines.append("|---|---|---|")
+        for api_name, info in items:
+            desc = info["description"][:50] if info["description"] else ""
+            lines.append(f"| {api_name} | {info['title']} | {desc} |")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+# ── 启动 ──────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    mcp.run()