Ash MCP

🚀 ash-mcp

An MCP service based on baostock + akshare, designed for long-term holding and low-frequency trading analysis of A-shares.

🚀 Quick Start

Clone the Repository (including submodules)

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

If you have already cloned the main repository and need to pull submodules later:

git submodule update --init --recursive

Install Dependencies

pip install -r requirements.txt

View the Tool List

python a_share_value_mcp.py -h

Gemini JSON Configuration (MCP)

Configure the service in JSON format for Gemini (example):

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

If you use a fixed environment, you can also change command to an absolute path (e.g., /home/wsl/miniconda3/envs/quant/bin/python).

Nightly Prefetching (Recommended)

python prefetch_strategy.py

Explanation:

• Prefetched content: industry_map, metrics, financial_cache, cap_map.
• financial_cache.total_share is preferably obtained from baostock query_profit_data. If it is missing, akshare will be used to fill in the gap at night.
• During the operation, checkpoints will be made at fixed intervals, and the data will be continuously written to prefetch-file-server/data/strategy_cache.json.

Cache Publishing Service (Optional)

• This repository is only responsible for generating the cache file: prefetch-file-server/data/strategy_cache.json.
• In a production environment, an independent service (e.g., prefetch-file-server implemented in Rust) can be used to provide a download interface for this file.
• This publishing service is not a core running dependency of this repository and can be maintained in an independent repository and deployed separately.

Prefetch Debug Log (Temporary)

PREFETCH_DEBUG=1 python prefetch_strategy.py

Explanation: DEBUG level is only enabled for this process, and the default operation is not affected.

Quick Check of Prefetch Progress Log

The prefetch script will output something like: [HS300] Progress: 120/300 | added=95 | cache_hit=20 | fetched=95 | skipped=5 | share_unavailable=3 | failed=0 Field meanings:

• count/total: Number of processed stocks / Total number of stocks.
• added: Number of stocks newly written to metrics during this run.
• cache_hit: Number of stocks that hit the existing metrics cache.
• fetched: Number of stocks actually calculated and written during this run (usually close to added).
• skipped: Number of stocks skipped due to missing key data (e.g., empty valuation sequence).
• share_unavailable: Number of stocks for which valid total shares (total_share) cannot be obtained, and unavailable: true will be written.
• failed: Number of abnormal requests or calculations (specific symbols can be checked with DEBUG logs).

✨ Features

Design Principles

1. Single tool entry: Only one tool is retained for each function.
2. Data source priority: Online queries are mainly based on baostock; akshare can be used to fill in missing fields (such as total shares) during nightly prefetching.
3. Low-frequency priority: Focus on weekly/monthly level decisions, not pursuing high-frequency matching.
4. LLM-friendly: Output is preferably in the form of concise tables and summaries to control tokens.

Feature Map

A. Basic Data Layer (baostock)

• get_current_time: Server time
• get_stock_basic: Basic stock information
• get_stock_kdata: Historical K-line data of stocks (daily/weekly/monthly/minute)
• get_industry_info: Industry classification mapping
• get_dividend_info: Dividend data
• get_profit_info: Quarterly profitability
• get_operation_info: Quarterly operational capacity
• get_growth_info: Quarterly growth ability
• get_index_data: Historical K-line data of indices
• get_valuation_info: Time series of PE/PB/PS/PCF

B. Market and Individual Stock Analysis Layer

• get_market_indices: Overview of the three major index markets (baostock -> akshare)
• get_sector_fund_flow: Sector fund flow (akshare)
• get_north_fund_flow: Aggregate of northbound funds (akshare)
• get_stock_spot: Latest snapshot of individual stock quotes (baostock -> akshare)
• get_financial_analysis: Summary of financial indicators (baostock -> akshare)
• get_valuation_status: Valuation conclusion of 5-year PE percentile (baostock -> akshare)
• get_stock_news: News of individual stocks (akshare)
• get_dragon_tiger_list: Dragon and Tiger List (akshare)

C. Long-term Holding Quantification Layer

• get_grid_strategy: Grid trading plan (baostock -> akshare)
• get_long_term_factor_score: Long-term multi-factor score (valuation/quality/growth/dividend)
• get_low_freq_backtest: Low-frequency backtesting (monthly fixed investment + handling fees)
• get_portfolio_rebalance_plan: Portfolio rebalancing (equal weight/inverse volatility)
• get_value_candidates_and_grid: Screen similar undervalued targets around an anchor stock and output their respective grid plans (supports hard constraints: valuation percentile/ROE/debt ratio/dividend years/market value similarity/volatility; preferably use prefetch cache).
  • Returns: Constraint configuration, candidate scoring table, reasons for selection, and grid plan for each stock.

💻 Usage Examples

Workflow 1: Initial Screening for Long-term Stock Selection

1. get_long_term_factor_score
2. get_financial_analysis
3. get_valuation_status

Workflow 2: Verification of Long-term Holding of a Single Stock

1. get_stock_kdata
2. get_low_freq_backtest
3. get_stock_news (explain recent abnormal fluctuations)

Workflow 3: Monthly Portfolio Rebalancing

1. get_portfolio_rebalance_plan
2. get_market_indices
3. get_sector_fund_flow

📚 Documentation

Project Structure

ash-mcp/
├─ a_share_value_mcp.py      # MCP entry and tool registration (lightweight wrapper)
├─ prefetch_strategy.py       # Nightly cache prefetch script (low-frequency task)
├─ models/
│  └─ inputs.py              # Enumerations and all input models
├─ core/
│  └─ utils.py               # General utility functions (formatting, scoring, weight processing, etc.)
├─ data/
│  ├─ baostock_client.py     # baostock access encapsulation
│  └─ market_data.py         # Price sequence acquisition (baostock first + akshare fallback)
├─ tools/
│  ├─ stock.py               # Implementation of basic securities and market tools
│  ├─ market.py              # Implementation of market overview and news tools
│  ├─ fundamental.py         # Implementation of fundamental and valuation tools
│  └─ strategy.py            # Implementation of strategy/backtesting/rebalancing tools
└─ readme.md

Parameter Specifications

• It is recommended to use 6-digit stock codes (e.g., 600519), which will be automatically normalized internally.
• Dates support YYYYMMDD or YYYY-MM-DD.
• Long-term analysis uses a longer look-back window by default; the range can be reduced for faster response.

Error Handling

• Tools uniformly return readable error information through handle_error.
• When the main data source fails, the fallback source will be tried first; if it still fails, a clear error reason will be returned.
• For unavailable total shares in financial_cache, unavailable: true will be written to avoid repeated invalid requests.

Suggestions for Future Refactoring

It is recommended to split the single file into multiple modules (models/, services/, tools/) in the next stage to reduce coupling and improve maintainability.

Example of Scheduled Task

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