# jwangkun/stock_mcp architecture

> Architecture diagram of the GitHub repository jwangkun/stock_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jwangkun/stock_mcp
- Repository: https://github.com/jwangkun/stock_mcp

## Overview

##### Project Type and Purpose
- This is a backend “stock analysis” MCP (Message Control Protocol) server with optional SSE (Server-Sent Events) support for integration with CherryStudio.
- It ingests live and historical stock data via the AKShare API, computes technical indicators, sentiment, performs searches and exposes these capabilities over MCP and SSE protocols.

##### High-Level Architecture
- The system is essentially a single Python service (or two closely related services) organized around a layered, asynchronous, event-driven architecture:
- Entry-Point Layer: `stock_mcp_server.py` (MCP) and `mcp_sse_server.py` (SSE)
- Controller/Router Layer: request dispatchers in `server.py` / `mcp_server.py`
- Service Layer: `StockAnalyzer` (indicators), `MarketSentimentAnalyzer`, `StockSearcher`, `NewsFetcher`
- Data Access Layer: AKShare API adapter, optional caching module
- Cross-Cutting Concerns: Configuration loader (`config.py` + JSON), logging, error handling

##### Main Components & Their Relationships
a. Clients
- CherryStudio IDE (via SSE) / any MCP client library
b. Protocol Handlers
- MCP Server (`stock_mcp_server.py`): handles MCP requests
- SSE Server (`mcp_sse_server.py`): wraps MCP handlers in SSE streams
c. Controllers / Routers
- Entry-point functions route to specific features: realtime, history, indicators, sentiment, search, news
d. Core Services
- StockAnalyzer: calculates MA, MACD, RSI, etc.
- MarketSentimentAnalyzer: aggregates market/bulk sentiment
- StockSearcher: name/code lookup
- NewsFetcher: retrieves news via AKShare or another news source
e. Data Layer
- AKShare API: external HTTP calls for market data
- In-memory cache (5-minute TTL) to reduce API calls
f. Infrastructure
- Config module: reads `cherry_studio_config.json`, `cherry_studio_sse_config.json`, etc.
- Logging: writes to `stock_mcp.log`
- Async framework (asyncio or equivalent) for concurrency

##### Data Flow & Interactions
1. Client (MCP or SSE) → Protocol Handler
2. Protocol Handler → Controller / Router
3. Controller → Core Service (e.g., StockAnalyzer)
4. Core Service → Data Layer
– Check cache → if miss, call AKShare API → store in cache
5. Core Service processes raw data → returns domain object (e.g., DataFrame → JSON)
6. Controller formats response → Protocol Handler → Client

##### Architectural Patterns & Design Principles
- Layered Architecture (separation of concerns)
- Adapter Pattern for AKShare API integration
- Cache-aside Strategy for data caching
- Asynchronous, event-driven I/O for high concurrency
- Single-responsibility components (Analyzer, Searcher, Fetcher)

##### Technologies & Frameworks
- Python 3.x
- fastmcp framework for MCP protocol
- CherryStudio SSE protocol adapter
- AKShare for market data
- asyncio or equivalent for async processing
- In-memory caching library (e.g., functools.lru_cache or custom)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["CherryStudio IDE (SSE) / MCP Client"]:::external

    %% Bootstrapper
    Bootstrap["start_server.py\n(Bootstrap)"]:::infra

    %% Protocol Handlers
    MCPHandler["stock_mcp_server.py\n(MCP Protocol Handler)"]:::protocol
    SSEHandler["mcp_sse_server.py\n(SSE Protocol Handler)"]:::protocol

    %% Controllers / Routers
    MCPRouter["mcp_server.py\n(MCP Router)"]:::controller
    GenericRouter["server.py\n(Generic Router)"]:::controller

    %% Services
    subgraph "Stock Analysis Services"
        StockAnalyzer["StockAnalyzer\n(Indicators)"]:::service
        SentimentAnalyzer["MarketSentimentAnalyzer\n(Sentiment)"]:::service
        StockSearcher["StockSearcher\n(Search)"]:::service
        NewsFetcher["NewsFetcher\n(News)"]:::service
    end

    %% Data Layer
    Cache["In-Memory Cache\n(5-min TTL)"]:::data
    AKShare["AKShare API\n(External)"]:::external

    %% Cross-Cutting Concerns
    ConfigLoader["config.py\n(Configuration Loader)"]:::infra
    Logging["stock_mcp.log\n(Logging)"]:::infra

    %% Dependencies and Tests (grouped)
    subgraph "Utilities & Tests"
        ReqMCP["requirements.txt"]:::infra
        ReqSSE["requirements_sse.txt"]:::infra
        Examples["examples.py"]:::infra
        TestSSEAPI["test_sse_api.py"]:::infra
        TestSSEFixed["test_sse_fixed.py"]:::infra
        TestCherrySSE["test_cherry_sse.py"]:::infra
        TestTools["test_tools.py"]:::infra
    end

    %% Flows
    Client -->|connect| SSEHandler
    Client -->|connect| MCPHandler
    Bootstrap -->|loads config| ConfigLoader
    Bootstrap -->|starts| MCPHandler
    Bootstrap -->|starts| SSEHandler
    ConfigLoader -->|provides settings| MCPHandler
    ConfigLoader -->|provides settings| SSEHandler

    MCPHandler -->|MCP request| MCPRouter
    SSEHandler -->|wraps & streams| MCPRouter
    MCPRouter -->|route request| GenericRouter
    GenericRouter -->|invoke| StockAnalyzer
    GenericRouter -->|invoke| SentimentAnalyzer
    GenericRouter -->|invoke| StockSearcher
    GenericRouter -->|invoke| NewsFetcher

    StockAnalyzer -->|check cache| Cache
    SentimentAnalyzer -->|check cache| Cache
    StockSearcher -->|check cache| Cache
    NewsFetcher -->|check cache| Cache

    Cache -->|on miss| AKShare
    AKShare -->|market data| Cache

    StockAnalyzer -->|result| GenericRouter
    SentimentAnalyzer -->|result| GenericRouter
    StockSearcher -->|result| GenericRouter
    NewsFetcher -->|result| GenericRouter

    GenericRouter -->|response| MCPHandler
    GenericRouter -->|response| SSEHandler
    MCPHandler -->|send| Client
    SSEHandler -->|send| Client

    %% Logging
    MCPHandler -->|log| Logging
    SSEHandler -->|log| Logging
    GenericRouter -->|log| Logging
    StockAnalyzer -->|log| Logging
    SentimentAnalyzer -->|log| Logging
    StockSearcher -->|log| Logging
    NewsFetcher -->|log| Logging
    Cache -->|log| Logging

    %% Click Events
    click MCPHandler "https://github.com/jwangkun/stock_mcp/blob/main/stock_mcp_server.py"
    click SSEHandler "https://github.com/jwangkun/stock_mcp/blob/main/mcp_sse_server.py"
    click MCPRouter "https://github.com/jwangkun/stock_mcp/blob/main/mcp_server.py"
    click GenericRouter "https://github.com/jwangkun/stock_mcp/blob/main/server.py"
    click Bootstrap "https://github.com/jwangkun/stock_mcp/blob/main/start_server.py"
    click ConfigLoader "https://github.com/jwangkun/stock_mcp/blob/main/config.py"
    click Logging "https://github.com/jwangkun/stock_mcp/blob/main/stock_mcp.log"
    click ReqMCP "https://github.com/jwangkun/stock_mcp/blob/main/requirements.txt"
    click ReqSSE "https://github.com/jwangkun/stock_mcp/blob/main/requirements_sse.txt"
    click Examples "https://github.com/jwangkun/stock_mcp/blob/main/examples.py"
    click TestSSEAPI "https://github.com/jwangkun/stock_mcp/blob/main/test_sse_api.py"
    click TestSSEFixed "https://github.com/jwangkun/stock_mcp/blob/main/test_sse_fixed.py"
    click TestCherrySSE "https://github.com/jwangkun/stock_mcp/blob/main/test_cherry_sse.py"
    click TestTools "https://github.com/jwangkun/stock_mcp/blob/main/test_tools.py"

    %% Styles
    classDef external fill:#E8F1FA,stroke:#2B7BB9,color:#2B7BB9;
    classDef protocol fill:#F5E6CC,stroke:#BF8C00,color:#BF8C00;
    classDef controller fill:#DDEEEA,stroke:#2AA198,color:#2AA198;
    classDef service fill:#F1E6F6,stroke:#93328E,color:#93328E;
    classDef data fill:#E9F5EB,stroke:#3E8635,color:#3E8635;
    classDef infra fill:#F2F2F2,stroke:#7A7A7A,color:#7A7A7A;
```
