How zwldarren/akshare-one-mcp works
Project type & purpose (what you’re diagramming)
This repo is a Python MCP (Model Context Protocol) server that exposes a set of financial-market “tools” (functions like get_hist_data, get_realtime_data, etc.) to an MCP client (Claude Desktop / other MCP-capable agents). Internally it delegates data fetching to akshare-one (a wrapper over multiple China market data sources), and can run in:
• stdio mode (default): MCP client launches the process and communicates over stdin/stdout.
• streamable-http mode: server binds to http://{host}:{port}/mcp (default port 8081).
So the core architecture is: MCP Client ↔ MCP Server (this repo) ↔ akshare-one ↔ external market data providers.
File tree clues (map folders/files to architecture)
• src/akshare_one_mcp/
• __main__.py: package entrypoint when executed (uvx akshare-one-mcp / python -m akshare_one_mcp style).
• server.py: likely defines MCP server initialization, tool registration, transports (stdio vs HTTP), routing for /mcp.
• __init__.py: package metadata / exports.
• pyproject.toml + uv.lock: Python packaging + dependency lock (runtime dependencies likely include MCP SDK / FastMCP + akshare-one).
• fastmcp.json, server.json: MCP server descriptors/metadata used by clients/registries (often includes tool schema, name, command, env).
• smithery.yaml: Smithery publishing/install integration (distribution channel).
• Dockerfile: container runtime option (deployment container boundary).
This structure suggests a single-service architecture (one Python service) with two transport adapters (stdio and HTTP).
What the README adds (runtime contracts)
The README gives you the “public API surface”:
• Tools: get_hist_data, get_realtime_data, get_news_data, get_balance_sheet, get_income_statement, get_cash_flow, get_inner_trade_data, get_financial_metrics, get_time_info.
• Data sources explicitly referenced: eastmoney, eastmoney_direct, sina, xueqiu (and possibly more via akshare-one).
• HTTP mode endpoint: /mcp on host/port.
• Installation modes: Smithery, uvx, local dev. These can be shown as different deployment contexts.
External Market Data Providers
• Eastmoney (incl. “direct”)
• Sina
• Xueqiu
*(Optional but useful)* Internet / Network boundary (to highlight outbound calls)
• MCP Client → MCP Server
• Transport variants: “stdio” OR “HTTP streamable (/mcp)”
• MCP Server → External Providers
• External Providers → MCP Server
Key annotation: MCP Server is a *thin orchestration layer* that exposes tools and normalizes output; the heavy lifting is done by akshare-one + upstream providers.
Since this is essentially one service, your “containers” are mostly execution modes:
Container 1: MCP Server (Python runtime)
• Show:
• “Transport Adapter: stdio”
• “Transport Adapter: streamable-http (bind host/port, route /mcp)”
• “Tool Handlers / Tool Registry”
• “akshare-one client layer”
Container 2 (optional): Docker
• “Docker container: akshare-one-mcp”
• Port mapping for HTTP mode: 8081 (or configurable)
• It to MCP Client (if client calls HTTP) or note stdio mode is usually not used via Docker (unless wrapped).
External systems container(s):
Entrypoint (__main__.py)
• Parses CLI args: --streamable-http, --host, --port
• Starts server with correct transport
Server Core (server.py)
• MCP server instance (likely FastMCP-based given fastmcp.json)
• Registers tool schemas and handlers
• Serializes responses to MCP format
Tool Handlers (logical grouping)
• Market Data Tools: get_hist_data, get_realtime_data
• News Tools: get_news_data
• Financial Statements: get_balance_sheet, get_income_statement, get_cash_flow
• Analytics/Metrics: get_inner_trade_data, get_financial_metrics
• Utility: get_time_info
Data Source Adapter (akshare-one)
• As an internal dependency/library boundary:
• “akshare-one (library)”
• “Source selection logic” (eastmoney/sina/xueqiu)
Config/Metadata
• fastmcp.json, server.json as descriptors (tool definitions, server identity) used by clients/registries.
• smithery.yaml as packaging metadata for Smithery.
• Entrypoint → Server Core
• Server Core → Tool Registry → Tool Handler → akshare-one → External provider
Architectural patterns/design principles to highlight
• Adapter pattern (transport adapters): stdio vs HTTP are two ways to expose the same tool surface.
• Facade layer: this MCP server is a facade over akshare-one and multiple upstream data providers.
• Pluggable data sources: “source” parameters select which upstream provider is used; show this as a decision point in the flow.
• Stateless service (likely): no evidence of DB/cache in file tree; represent it as stateless unless you confirm otherwise.
Don’t overthink it: split into many components (but keep truthfulness)
• Transport
• Tool registry & schemas
• Tool handler groups
• akshare-one integration
• External providers
That separation will help reviewers reason about reliability (provider failures), extensibility (adding new tools/sources), and deployment choices (stdio vs HTTP).
Container: stdio mode vs HTTP mode, plus Docker boundary (optional)
3. Component: __main__.py → server.py (server core + tool registry) → tool handler groups → akshare-one → providers