How jwangkun/stock_mcp works
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)