You: "What are the top holders and supply chain for CEG US Equity?"

Claude: runs bloomberg_get_bulk_data with TOP_20_HOLDERS_PUBLIC_FILINGS
        runs bloomberg_get_supply_chain with suppliers + customers
        → Returns structured holder list + supplier/customer network

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

    subgraph "Bloomberg MCP Server"
        direction TB
        MCP["FastMCP Server<br/><i>18 tools exposed</i>"]

        subgraph Handlers["Handler Layer"]
            direction LR
            REF[Reference & Historical]
            BULK[Bulk Data & Estimates]
            TA[Technical Analysis]
            SCREEN[Screening & BQL]
            OWN[Ownership & Supply Chain]
            CAL[Calendars]
        end

        subgraph Core["Core Layer"]
            direction LR
            SESSION["BloombergSession<br/><i>Singleton + Cache</i>"]
            REQ[Request Builder]
            RESP[Response Parser]
        end
    end

    BBG["Bloomberg Terminal<br/><i>blpapi on port 8194</i>"]

    CC -- stdio --> MCP
    WC -- HTTP/SSE --> MCP
    CA -- HTTP/SSE --> MCP
    MCP --> Handlers
    Handlers --> Core
    SESSION <--> BBG
    REQ --> SESSION
    SESSION --> RESP

    style MCP fill:#1a73e8,stroke:#1557b0,color:#fff
    style BBG fill:#ff6f00,stroke:#e65100,color:#fff
    style SESSION fill:#2e7d32,stroke:#1b5e20,color:#fff

graph LR
    subgraph "Market Data (4)"
        T1["bloomberg_get_reference_data<br/><i>BDP snapshots</i>"]
        T2["bloomberg_get_historical_data<br/><i>BDH time series</i>"]
        T3["bloomberg_get_intraday_bars<br/><i>OHLCV candles</i>"]
        T4["bloomberg_get_intraday_ticks<br/><i>Raw ticks</i>"]
    end

    subgraph "Bulk Data & Analysis (4)"
        T5["bloomberg_get_bulk_data<br/><i>BDS tables</i>"]
        T6["bloomberg_get_estimates_detail<br/><i>Multi-period consensus</i>"]
        T7["bloomberg_get_ownership<br/><i>Holder analysis</i>"]
        T8["bloomberg_get_supply_chain<br/><i>SPLC network</i>"]
    end

    subgraph "Technical & BQL (2)"
        T9["bloomberg_get_technical_analysis<br/><i>RSI, MACD, Bollinger...</i>"]
        T10["bloomberg_run_bql<br/><i>Query language</i>"]
    end

    subgraph "Discovery (3)"
        T11["bloomberg_search_securities<br/><i>Find by name/ticker</i>"]
        T12["bloomberg_search_fields<br/><i>Field mnemonics</i>"]
        T13["bloomberg_get_field_info<br/><i>Field metadata</i>"]
    end

    subgraph "Screening (3)"
        T14["bloomberg_run_screen<br/><i>Saved EQS screens</i>"]
        T15["bloomberg_get_universe<br/><i>Index constituents</i>"]
        T16["bloomberg_dynamic_screen<br/><i>Custom filter + rank</i>"]
    end

    subgraph "Calendars (2)"
        T17["bloomberg_get_economic_calendar<br/><i>Fed, BoJ, ECB...</i>"]
        T18["bloomberg_get_earnings_calendar<br/><i>Earnings dates</i>"]
    end

    style T5 fill:#1a73e8,stroke:#1557b0,color:#fff
    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 T9 fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style T10 fill:#7b1fa2,stroke:#6a1b9a,color:#fff

sequenceDiagram
    participant Client as AI Assistant
    participant MCP as MCP Server
    participant Cache as Cache Layer
    participant Val as Pydantic Validation
    participant Expand as Field Expander
    participant Session as BloombergSession
    participant BBG as Bloomberg Terminal

    Client->>MCP: Tool call (JSON)
    MCP->>Val: Validate input model
    Val-->>MCP: Validated params

    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: Build & send request
        Session->>BBG: blpapi Request
        BBG-->>Session: blpapi Response
        Session-->>MCP: Parsed dataclasses
        MCP->>Cache: Store with TTL
    end

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

graph LR
    subgraph "Bloomberg Terminal (localhost:8194)"
        R["//blp/refdata<br/><i>BDP, BDH, BDS, BEQS</i>"]
        I["//blp/instruments<br/><i>Security lookup</i>"]
        F["//blp/apiflds<br/><i>Field discovery</i>"]
        T["//blp/tasvc<br/><i>Technical analysis</i>"]
        B["//blp/bqlsvc<br/><i>Query language</i>"]
    end

    R --- T1[Reference Data]
    R --- T2[Historical Data]
    R --- T3[Intraday Bars/Ticks]
    R --- T4[Bulk Data]
    R --- T5[Estimates]
    R --- T6[Screening]
    I --- T7[Security Search]
    F --- T8[Field Search]
    T --- T9[RSI / MACD / Bollinger]
    B --- T10[Dynamic Queries]

    style R fill:#ff6f00,stroke:#e65100,color:#fff
    style T fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    style B fill:#1a73e8,stroke:#1557b0,color:#fff

flowchart LR
    A["Universe<br/><i>index, screen,<br/>or ticker list</i>"] --> B["Field Expansion<br/><i>FieldSet shortcuts<br/>→ Bloomberg fields</i>"]
    B --> C["Bloomberg API<br/><i>ReferenceDataRequest</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": "index:SPX Index",
  "fields": ["PRICE", "RVOL", "TECHNICAL", "SECTOR"],
  "filters": [
    {"field": "RSI_14D", "op": "lt", "value": 30},
    {"field": "rvol", "op": "gt", "value": 2.0}
  ],
  "rank_by": "rvol",
  "rank_descending": true,
  "top_n": 20
}

graph TB
    subgraph "src/bloomberg_mcp/"
        SERVER["server.py<br/><i>~89 lines, thin entry point</i>"]

        subgraph models["models/"]
            INPUTS["inputs.py<br/><i>22 Pydantic models</i>"]
            ENUMS["enums.py<br/><i>ResponseFormat, modes</i>"]
        end

        subgraph handlers["handlers/"]
            direction TB
            H_REF["reference.py"]
            H_HIST["historical.py"]
            H_INTRA["intraday.py"]
            H_SEARCH["search.py"]
            H_SCREEN["screening.py"]
            H_CAL["calendars.py"]
            H_BULK["bulk.py ★"]
            H_EST["estimates.py ★"]
            H_TECH["technical.py ★"]
            H_OWN["ownership.py ★"]
            H_SC["supply_chain.py ★"]
            H_BQL["bql.py ★"]
        end

        FMTR["formatters.py"]
        UTILS["utils.py"]

        subgraph core["core/"]
            SESSION["session.py<br/><i>Singleton</i>"]
            CACHE["cache.py ★<br/><i>TTL cache</i>"]
            REQ["requests.py"]
            RESP["responses.py"]
        end

        subgraph tools["tools/"]
            direction TB
            T_REF["reference.py"]
            T_HIST["historical.py"]
            T_SEARCH["search.py"]

            subgraph ds["dynamic_screening/"]
                MODELS_DS["models.py<br/><i>19+ FieldSets</i>"]
                SCREEN_DS["screen.py"]
                FILTERS["filters.py"]
            end

            subgraph mn["morning_note/"]
                MN_CFG["config.py"]
                MN_US["us_session.py"]
                MN_STORE["storage.py"]
            end
        end
    end

    SERVER --> handlers
    SERVER --> models
    handlers --> core
    handlers --> FMTR
    handlers --> UTILS

    style SERVER fill:#1a73e8,stroke:#1557b0,color:#fff
    style SESSION fill:#2e7d32,stroke:#1b5e20,color:#fff
    style CACHE fill:#2e7d32,stroke:#1b5e20,color:#fff
    style H_BULK fill:#e65100,stroke:#bf360c,color:#fff
    style H_EST fill:#e65100,stroke:#bf360c,color:#fff
    style H_TECH fill:#e65100,stroke:#bf360c,color:#fff
    style H_OWN fill:#e65100,stroke:#bf360c,color:#fff
    style H_SC fill:#e65100,stroke:#bf360c,color:#fff
    style H_BQL fill:#e65100,stroke:#bf360c,color:#fff

# 1. Install Bloomberg Python SDK
pip install blpapi

# 2. Install bloomberg-mcp
git clone https://github.com/QmQsun/Bloomberg-MCP.git
cd Bloomberg-MCP
pip install .            # standard install
# or: pip install -e .   # editable mode (for development)

{
  "mcpServers": {
    "bloomberg-mcp": {
      "command": "python",
      "args": ["-m", "bloomberg_mcp.server"],
      "cwd": "/path/to/bloomberg-mcp",
      "env": {
        "BLOOMBERG_HOST": "localhost",
        "BLOOMBERG_PORT": "8194"
      }
    }
  }
}

[mcp_servers.bloomberg-mcp]
command = "python"
args = ["-m", "bloomberg_mcp.server"]
cwd = "/path/to/bloomberg-mcp"

[mcp_servers.bloomberg-mcp.env]
BLOOMBERG_HOST = "localhost"
BLOOMBERG_PORT = "8194"

from bloomberg_mcp.tools import get_reference_data, get_historical_data

# Current prices and fundamentals
data = get_reference_data(
    securities=["AAPL US Equity", "700 HK Equity", "2899 HK Equity"],
    fields=["PX_LAST", "PE_RATIO", "DIVIDEND_YIELD"]
)
for sec in data:
    print(f"{sec.security}: {sec.fields.get('PX_LAST')}")

# Multi-period estimates with overrides
data = get_reference_data(
    securities=["CEG US Equity"],
    fields=["BEST_EPS", "BEST_EPS_4WK_CHG", "BEST_TARGET_PRICE"],
    overrides={"BEST_FPERIOD_OVERRIDE": "1FY"}
)

# Historical time series
hist = get_historical_data(
    securities=["SPY US Equity"],
    fields=["PX_LAST", "VOLUME"],
    start_date="20240101",
    end_date="20241231",
    periodicity="DAILY"
)

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

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

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

graph LR
    subgraph Docker
        MCP["bloomberg-mcp<br/><i>:8080</i>"]
    end

    subgraph Host
        BBG["Bloomberg Terminal<br/><i>:8194</i>"]
    end

    Client["AI Client"] -- "HTTP/SSE" --> MCP
    MCP -- "host.docker.internal:8194" --> BBG

    style MCP fill:#1a73e8,stroke:#1557b0,color:#fff
    style BBG fill:#ff6f00,stroke:#e65100,color:#fff

docker-compose up -d
docker-compose logs -f bloomberg-mcp

AAPL US Equity       # US stock
VOD LN Equity        # UK stock (London)
7203 JP Equity       # Japan stock (numeric)
700 HK Equity        # Hong Kong stock
1133 HK Equity       # Hong Kong stock (numeric)
601012 CH Equity     # A-share (Shanghai)
002594 CH Equity     # A-share (Shenzhen)
300750 CH Equity     # A-share (ChiNext)
SPX Index            # Index
HSI Index            # Hang Seng Index
VIX Index            # Volatility index
EUR Curncy           # Currency
CL1 Comdty           # Commodity future
SPY US Equity        # ETF

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