You: "拉一下贵州茅台过去20天的量价数据"

Claude: runs wind_historical with codes=600519.SH, fields=close,volume
        → Returns structured price/volume time series

You: "Find me A-share stocks with PE < 15 and ROE > 20%"

Claude: runs wind_dynamic_screen with universe=A-shares, filters, rank
        → Returns filtered and ranked stock list

graph TB
    subgraph Clients
        CC[Claude Code]
        WC[Web Client]
        CA[Custom App]
    end

    subgraph "Wind MCP Server"
        direction TB
        MCP["FastMCP Server<br/><i>23 tools + 1 resource</i>"]

        subgraph Handlers["Handler Layer"]
            direction LR
            SNAP[Snapshot & Historical]
            INTRA[Minute Bars & Ticks]
            MACRO[Macro & Sector]
            SCREEN[Screening]
            EST[Estimates & Holders]
            CAL[Calendar & Dates]
        end

        subgraph Core["Core Layer"]
            direction LR
            SESSION["WindSession<br/><i>Singleton + atexit</i>"]
            CACHE["WindCache<br/><i>TTL-based</i>"]
            PARSER["Parser<br/><i>12 parsers</i>"]
            CONV["Converter<br/><i>BBG → Wind</i>"]
        end
    end

    WIND["Wind Terminal<br/><i>WindPy (w.start)</i>"]

    CC -- stdio --> MCP
    WC -- HTTP/SSE --> MCP
    CA -- HTTP/SSE --> MCP
    MCP --> Handlers
    Handlers --> Core
    SESSION <--> WIND

    style MCP fill:#1a73e8,stroke:#1557b0,color:#fff
    style WIND fill:#e65100,stroke:#bf360c,color:#fff
    style SESSION fill:#2e7d32,stroke:#1b5e20,color:#fff
    style CACHE fill:#2e7d32,stroke:#1b5e20,color:#fff

graph LR
    subgraph "Market Data (5)"
        T1["wind_snapshot<br/><i>WSS current data</i>"]
        T2["wind_historical<br/><i>WSD time series</i>"]
        T3["wind_minute_bars<br/><i>WSI candles</i>"]
        T4["wind_ticks<br/><i>WST raw ticks</i>"]
        T5["wind_realtime<br/><i>WSQ live quotes</i>"]
    end

    subgraph "Fundamentals & Screening (5)"
        T6["wind_dataset<br/><i>WSET tables</i>"]
        T7["wind_screen<br/><i>WEQS screens</i>"]
        T8["wind_dynamic_screen<br/><i>Custom filter + rank</i>"]
        T9["wind_estimates<br/><i>Consensus</i>"]
        T10["wind_holders<br/><i>Shareholding</i>"]
    end

    subgraph "Macro & Sector (3)"
        T11["wind_macro<br/><i>EDB series</i>"]
        T12["wind_sector_series<br/><i>WSES time series</i>"]
        T13["wind_sector_snapshot<br/><i>WSEE snapshot</i>"]
    end

    subgraph "Connect & Calendar (2)"
        T14["wind_stock_connect<br/><i>Northbound flows</i>"]
        T15["wind_event_calendar<br/><i>IPO, earnings...</i>"]
    end

    subgraph "Composite & Portfolio (4)"
        T16["wind_company_profile<br/><i>One-stop overview</i>"]
        T17["wind_portfolio_report<br/><i>WPF reports</i>"]
        T18["wind_portfolio_snapshot<br/><i>WPS holdings</i>"]
        T19["wind_portfolio_series<br/><i>WPD time series</i>"]
    end

    subgraph "Date Utilities (3)"
        T20["wind_trading_days<br/><i>TDAYS</i>"]
        T21["wind_date_offset<br/><i>TDAYSOFFSET</i>"]
        T22["wind_days_count<br/><i>TDAYSCOUNT</i>"]
    end

    subgraph "Observability (1 tool + 1 resource)"
        T23["wind_metrics<br/><i>Server stats</i>"]
        R1["wind://health<br/><i>Health check</i>"]
    end

    style T6 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T7 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T8 fill:#1a73e8,stroke:#1557b0,color:#fff
    style T11 fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style T12 fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style T13 fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style T16 fill:#00695c,stroke:#004d40,color:#fff
    style T17 fill:#00695c,stroke:#004d40,color:#fff
    style T18 fill:#00695c,stroke:#004d40,color:#fff
    style T19 fill:#00695c,stroke:#004d40,color:#fff
    style R1 fill:#546e7a,stroke:#37474f,color:#fff

sequenceDiagram
    participant Client as AI Assistant
    participant MCP as MCP Server
    participant Conv as Ticker Converter
    participant Expand as Field Expander
    participant Cache as Cache Layer
    participant Session as WindSession
    participant Wind as Wind Terminal

    Client->>MCP: Tool call (JSON)
    MCP->>Conv: Convert BBG → Wind codes
    Conv-->>MCP: Wind codes

    alt FieldSet shortcuts used
        MCP->>Expand: Expand FieldSet shortcuts
        Expand-->>MCP: Resolved field list
    end

    MCP->>Cache: Check cache
    alt Cache hit
        Cache-->>MCP: Cached result
    else Cache miss
        MCP->>Session: Call WindPy API
        Session->>Wind: w.wsd() / w.wss() / ...
        Wind-->>Session: WindData response
        Session-->>MCP: Parsed dicts
        MCP->>Cache: Store with TTL
    end

    alt Markdown format
        MCP-->>Client: Formatted table
    else JSON format
        MCP-->>Client: Structured JSON
    end

flowchart LR
    A["Universe<br/><i>index, sector,<br/>or ticker list</i>"] --> B["Field Expansion<br/><i>FieldSet shortcuts<br/>→ Wind fields</i>"]
    B --> C["Wind API<br/><i>WSS request</i>"]
    C --> D["Filter<br/><i>gt, lt, between,<br/>in, eq, ...</i>"]
    D --> E["Rank & Slice<br/><i>rank_by + top_n</i>"]
    E --> F["Response<br/><i>Markdown table<br/>or JSON</i>"]

    style A fill:#e8f5e9,stroke:#2e7d32
    style C fill:#fff3e0,stroke:#ff6f00
    style F fill:#e3f2fd,stroke:#1a73e8

{
  "universe": "sector:全部A股",
  "fields": ["PRICE", "VALUATION", "PROFITABILITY"],
  "filters": [
    {"field": "pe_ttm", "op": "lt", "value": 15},
    {"field": "roe_ttm", "op": "gt", "value": 20}
  ],
  "rank_by": "roe_ttm",
  "rank_descending": true,
  "top_n": 20
}

[session]
connect_timeout = 30        # Seconds to wait for Wind connection
reconnect_retries = 3       # Auto-reconnect attempts
reconnect_backoff = 1.0     # Backoff multiplier between retries

[cache]
maxsize = 2000              # Max cached entries (LRU eviction)
ttl_realtime = 30           # WSQ — near real-time
ttl_snapshot = 300          # WSS — 5 min
ttl_historical = 43200     # WSD — 12 hours
ttl_dataset = 86400        # WSET — 24 hours
ttl_macro = 86400          # EDB — 24 hours
ttl_portfolio = 300        # WPF/WPS/WPD — 5 min

[api]
timeout = 30.0              # Per-call timeout (seconds)
retries = 2                 # Retry count on transient errors
backoff = 1.0               # Backoff multiplier

[log]
format = "text"             # "json" or "text"
level = "INFO"

wind-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── wind_mcp.toml                  # Server configuration (cache TTL, timeouts, retries)
├── run_server.bat / run_server.ps1
├── src/wind_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py                  # FastMCP entry point, 23 tools + 1 resource
│   ├── formatters.py              # Markdown table & JSON output
│   ├── core/
│   │   ├── session.py             # WindSession singleton + reconnect
│   │   ├── cache.py               # TTL cache with LRU eviction
│   │   ├── parser.py              # 12 WindData parsers
│   │   ├── converter.py           # Bloomberg → Wind ticker converter
│   │   ├── executor.py            # Single-thread executor for Wind API calls
│   │   ├── validators.py          # Input validation (codes, dates, fields)
│   │   ├── resilience.py          # Timeout, retry, stale-cache fallback
│   │   ├── config.py              # Centralized config (env > toml > defaults)
│   │   ├── metrics.py             # Counters + histograms for observability
│   │   ├── universe.py            # Universe resolution (index/sector → security list)
│   │   └── filters.py             # In-memory data filtering (gt/lt/between/in/...)
│   ├── models/
│   │   ├── enums.py               # ResponseFormat, Periodicity, etc.
│   │   └── inputs.py              # Pydantic input models
│   ├── tools/
│   │   ├── fieldsets.py           # 16 FieldSet definitions
│   │   └── field_expander.py      # FieldSet → field list resolver
│   ├── handlers/                  # 16 handler modules
│   │   ├── snapshot.py            # WSS
│   │   ├── historical.py          # WSD
│   │   ├── minute_bars.py         # WSI
│   │   ├── ticks.py               # WST
│   │   ├── realtime.py            # WSQ
│   │   ├── dataset.py             # WSET
│   │   ├── macro.py               # EDB
│   │   ├── sector.py              # WSES / WSEE
│   │   ├── screening.py           # WEQS + dynamic screen
│   │   ├── estimates.py           # Consensus estimates
│   │   ├── holders.py             # Holder analysis
│   │   ├── stock_connect.py       # Northbound/Southbound
│   │   ├── calendar.py            # Event calendar
│   │   ├── dates.py               # TDAYS / TDAYSOFFSET / TDAYSCOUNT
│   │   ├── composite.py           # Company profile (multi-source)
│   │   └── portfolio.py           # WPF / WPS / WPD portfolio tools
│   └── data/                      # Static mapping files
│       ├── us_exchange_map.json   # ~200 US tickers → exchange
│       ├── index_map.json         # BBG → Wind index mapping
│       ├── commodity_map.json     # BBG → Wind commodity mapping
│       └── currency_map.json      # BBG → Wind currency mapping
├── tests/                         # 101 unit tests (no Wind needed)
│   ├── test_parser.py
│   ├── test_fieldsets.py
│   ├── test_cache.py
│   ├── test_config.py
│   ├── test_converter.py
│   ├── test_filters.py
│   ├── test_formatters.py
│   ├── test_inputs.py
│   ├── test_metrics.py
│   ├── test_resilience.py
│   └── test_validators.py
└── examples/
    ├── basic_usage.py
    └── screening_example.py

python -c "from WindPy import w; w.start(); print(w.isconnected())"
# Should print: True

# From source
git clone https://github.com/QmQsun/Wind-MCP.git
cd Wind-MCP
pip install .            # standard install
# or: pip install -e .   # editable mode (for development)

# Or from PyPI
pip install wind-mcp

{
  "mcpServers": {
    "wind-mcp": {
      "command": "wind-mcp",
      "args": []
    }
  }
}

# stdio (default — for Claude Code)
python -m wind_mcp.server

# HTTP transport (for web clients)
python -m wind_mcp.server --http --port=8080

# SSE transport (for streaming clients)
python -m wind_mcp.server --sse --port=8080

# Command Prompt
run_server.bat

# PowerShell
.\run_server.ps1

graph LR
    subgraph "Wind Terminal (WindPy)"
        WSS["WSS<br/><i>Snapshot</i>"]
        WSD["WSD<br/><i>Historical</i>"]
        WSI["WSI<br/><i>Minute bars</i>"]
        WST["WST<br/><i>Tick data</i>"]
        WSQ["WSQ<br/><i>Realtime</i>"]
        WSET["WSET<br/><i>Datasets</i>"]
        EDB["EDB<br/><i>Macro</i>"]
        WSES["WSES<br/><i>Sector series</i>"]
        WSEE["WSEE<br/><i>Sector snapshot</i>"]
        WEQS["WEQS<br/><i>Stock screener</i>"]
        TDAYS["TDAYS<br/><i>Trading days</i>"]
    end

    WSS --- T1[Snapshot + Estimates + Holders + Screen]
    WSD --- T2[Historical Time Series]
    WSI --- T3[Intraday Bars]
    WST --- T4[Tick Data]
    WSQ --- T5[Realtime Quotes]
    WSET --- T6[Datasets + Connect + Calendar]
    EDB --- T7[Macro Indicators]
    WSES --- T8[Sector Time Series]
    WSEE --- T9[Sector Snapshot]
    WEQS --- T10[Saved Screens]
    TDAYS --- T11[Date Utilities]

    style WSS fill:#1a73e8,stroke:#1557b0,color:#fff
    style WSD fill:#1a73e8,stroke:#1557b0,color:#fff
    style EDB fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style WEQS fill:#e65100,stroke:#bf360c,color:#fff

pip install -e ".[dev]"
pytest                    # Unit tests (no Wind Terminal needed)
black src/ tests/
ruff check src/ tests/