Ash MCP

🚀 ash - mcp

baostock + akshare をベースにした MCP サービスで、A 株の長期保有と低頻度取引分析を対象としています。

🚀 クイックスタート

このサービスは、A 株の長期保有と低頻度取引分析に特化しており、baostock と akshare を利用してデータを取得します。以下に、主な使い方を説明します。

✨ 主な機能

設計原則

1. 単一ツールエントリー：各機能には 1 つのツールのみを残します。
2. データソースの優先順位：オンラインクエリーは baostock を主とし、夜間の事前取得では akshare を使って欠落したフィールド（例えば総株式数）を補完します。
3. 低頻度優先：週/月レベルの意思決定を中心に、高頻度のマッチングを追求しません。
4. LLM フレンドリー：出力はできるだけ簡潔な表と要約にし、トークンをコントロールします。

機能マップ

A. 基礎データ層（baostock）

• get_current_time：サーバー時間
• get_stock_basic：証券の基礎情報
• get_stock_kdata：株式の過去の K 線（日/週/月/分）
• 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

📦 インストール

リポジトリのクローン（サブモジュールを含む）

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 で補完します。
• 実行中は一定の進捗チェックポイントで 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 ログを使って具体的なシンボルを調査できます）。

📚 ドキュメント

プロジェクト構造

ash-mcp/
├─ a_share_value_mcp.py      # MCP エントリーとツール登録（軽量ラッパー）
├─ prefetch_strategy.py       # 夜間キャッシュ事前取得スクリプト（低頻度タスク）
├─ models/
│  └─ inputs.py              # 列挙型とすべての入力モデル
├─ core/
│  └─ utils.py               # 汎用ツール関数（フォーマット、スコアリング、重み処理など）
├─ data/
│  ├─ baostock_client.py     # baostock アクセスのラッパー
│  └─ market_data.py         # 価格シーケンスの取得（baostock 優先 + akshare フォールバック）
├─ tools/
│  ├─ stock.py               # 基礎証券と相場関連のツール実装
│  ├─ market.py              # 市場概観とニュース関連のツール実装
│  ├─ fundamental.py         # 基本分析と評価関連のツール実装
│  └─ strategy.py            # 戦略/バックテスト/再バランス関連のツール実装
└─ readme.md

パラメータ規範

• 株式コードは 6 桁の数字（例：600519）を使用することをおすすめし、内部で自動的に正規化されます。
• 日付は YYYYMMDD または YYYY-MM-DD 形式をサポートします。
• 長期分析ではデフォルトで長いバックデートウィンドウを使用します。より速い応答が必要な場合は範囲を狭めることができます。

エラー処理

• ツールは handle_error を通じて読みやすいエラーメッセージを返します。
• メインデータソースが失敗した場合、まずフォールバックを試み、それでも失敗した場合は明確なエラー原因を返します。
• 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