Ash MCP

🚀 ash - mcp

基於 baostock + akshare 的 MCP 服務，面向 A 股長期持有與低頻交易分析，為投資者提供全面、精準的 A 股市場數據和分析工具，助力長期投資決策。

🚀 快速開始

克隆倉庫（含子模塊）

git clone --recurse-submodules https://github.com/zlotus/ash-mcp.git

若已克隆主倉再補拉子模塊：

git submodule update --init --recursive

安裝依賴

pip install -r requirements.txt

查看工具列表

python a_share_value_mcp.py -h

Gemini JSON 配置（MCP）

將服務按 JSON 方式配置到 Gemini（示例）：

{
  "mcpServers": {
    "ash-mcp": {
      "command": "python",
      "args": ["a_share_value_mcp.py"],
      "cwd": "/home/wsl/quant/ash-mcp"
    }
  }
}

若你使用固定環境，也可把 command 改為絕對路徑（例如 /home/wsl/miniconda3/envs/quant/bin/python）。

夜間預取（推薦）

python prefetch_strategy.py

說明：

• 預取內容：industry_map、metrics、financial_cache、cap_map。
• financial_cache.total_share 優先來自 baostock query_profit_data，缺失時夜間再用 akshare 兜底。
• 運行中會按固定進度 checkpoint，持續寫入 prefetch-file-server/data/strategy_cache.json。

緩存發佈服務（可選）

• 本倉只負責生成緩存文件：prefetch-file-server/data/strategy_cache.json。
• 生產環境可使用獨立服務（例如 Rust 實現的 prefetch-file-server）對該文件提供下載接口。
• 該發佈服務不屬於本倉核心運行依賴，可以獨立倉庫維護並單獨部署。

預取調試日誌（臨時）

PREFETCH_DEBUG=1 python prefetch_strategy.py

說明：僅該次進程啟用 DEBUG 級別，默認運行不受影響。

預取進度日誌速查

預取腳本會輸出類似： [HS300] Progress: 120/300 | added=95 | cache_hit=20 | fetched=95 | skipped=5 | share_unavailable=3 | failed=0 字段含義：

• count/total：已處理股票數 / 總股票數。
• added：本次運行新增寫入 metrics 的股票數量。
• cache_hit：命中既有 metrics 緩存的股票數量。
• fetched：本次實際完成計算並寫入的股票數量（通常與 added 接近）。
• skipped：因關鍵數據缺失（如估值序列為空）跳過的數量。
• share_unavailable：無法得到有效總股本（total_share）的數量，會寫 unavailable: true。
• failed：請求或計算異常數量（可配合 DEBUG 日誌排查具體 symbol）。

✨ 主要特性

設計原則

1. 單一工具入口：每個功能只保留一個 tool。
2. 數據源優先級：在線查詢以 baostock 為主；夜間預取允許使用 akshare 補齊缺失字段（如總股本）。
3. 低頻優先：圍繞周/月級決策，不追求高頻撮合。
4. LLM 友好：輸出儘量為精簡表格和摘要，控制 token。

功能地圖

A. 基礎數據層（baostock）

• get_current_time：服務器時間
• get_stock_basic：證券基礎信息
• get_stock_kdata：股票歷史 K 線（d/w/m/分鐘）
• get_industry_info：行業分類映射
• get_dividend_info：分紅派息數據
• get_profit_info：季度盈利能力
• get_operation_info：季度營運能力
• get_growth_info：季度成長能力
• get_index_data：指數歷史 K 線
• get_valuation_info：PE/PB/PS/PCF 時序

B. 市場與個股分析層

• get_market_indices：三大指數市場概覽（baostock -> akshare）
• get_sector_fund_flow：行業資金流（akshare）
• get_north_fund_flow：北向資金彙總（akshare）
• get_stock_spot：個股最新行情快照（baostock -> akshare）
• get_financial_analysis：財務指標摘要（baostock -> akshare）
• get_valuation_status：5 年 PE 分位估值結論（baostock -> akshare）
• get_stock_news：個股新聞（akshare）
• get_dragon_tiger_list：龍虎榜（akshare）

C. 長期持有量化層

• get_grid_strategy：網格交易計劃（baostock -> akshare）
• get_long_term_factor_score：長期多因子評分（估值/質量/成長/分紅）
• get_low_freq_backtest：低頻回測（月度定投 + 手續費）
• get_portfolio_rebalance_plan：組合再平衡（等權/逆波動）
• get_value_candidates_and_grid：圍繞錨點股票篩選同類低估標的並輸出各自網格計劃（支持硬約束：估值分位/ROE/負債率/分紅年限/市值相似度/波動率；優先使用預取緩存）
  • 返回包含：約束配置、候選評分表、入選原因、每隻股票的網格計劃

💻 使用示例

典型工作流

工作流 1：長期選股初篩

1. get_long_term_factor_score
2. get_financial_analysis
3. get_valuation_status

工作流 2：單票長期持有驗證

1. get_stock_kdata
2. get_low_freq_backtest
3. get_stock_news（解釋近期異常波動）

工作流 3：組合月度調倉

1. get_portfolio_rebalance_plan
2. get_market_indices
3. get_sector_fund_flow

📚 詳細文檔

項目結構

ash-mcp/
├─ a_share_value_mcp.py      # MCP 入口與工具註冊（輕量 wrapper）
├─ prefetch_strategy.py       # 夜間緩存預取腳本（低頻任務）
├─ models/
│  └─ inputs.py              # 枚舉與全部輸入模型
├─ core/
│  └─ utils.py               # 通用工具函數（格式化、打分、權重處理等）
├─ data/
│  ├─ baostock_client.py     # baostock 訪問封裝
│  └─ market_data.py         # 價格序列獲取（baostock 優先 + akshare fallback）
├─ tools/
│  ├─ stock.py               # 基礎證券與行情類工具實現
│  ├─ market.py              # 市場概覽與新聞類工具實現
│  ├─ fundamental.py         # 基本面與估值類工具實現
│  └─ strategy.py            # 策略/回測/再平衡類工具實現
└─ readme.md

參數規範

• 股票代碼建議使用 6 位數字（如 600519），內部自動規範化。
• 日期支持 YYYYMMDD 或 YYYY - MM - DD。
• 長期分析默認使用較長回看窗口；如需更快響應可縮小範圍。

錯誤處理

• 工具統一通過 handle_error 返回可讀錯誤信息。
• 當主數據源失敗時，優先嚐試 fallback；若仍失敗，返回明確錯誤原因。
• 對 financial_cache 中不可用總股本會寫 unavailable: true，避免重複無效請求。

後續重構建議

建議下一階段將單文件拆分為多模塊（models/, services/, tools/），降低耦合並提升可維護性。

定時任務示例

0 1 * * * cd /home/wsl/quant/ash-mcp && /home/wsl/miniconda3/envs/quant/bin/python3 prefetch_strategy.py >> prefetch.log 2>&1