# zwldarren/akshare-one-mcp architecture

> Architecture diagram of the GitHub repository zwldarren/akshare-one-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zwldarren/akshare-one-mcp
- Repository: https://github.com/zwldarren/akshare-one-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context
  %% =========================
  subgraph "System Context"
    direction TB

    Client["MCP Client<br/>(Claude Desktop / MCP-capable agent)"]:::client

    subgraph "AKShare One MCP Server (this repo)"
      direction TB

      ServerSvc["AKShare One MCP Server<br/>(Python process / package)"]:::server

      subgraph "Transport Adapters"
        direction TB
        Stdio["Stdio Transport<br/>(stdin/stdout MCP messages)"]:::transport
        Http["Streamable-HTTP Transport<br/>(bind host:port, route /mcp)"]:::transport
      end

      subgraph "Server Internals (Components)"
        direction TB
        Entry["Entrypoint / CLI Launcher<br/>(parse args: --streamable-http, --host, --port)"]:::component
        Core["Server Core<br/>(MCP init, tool registration, schema, routing)"]:::component
        Registry["Tool Registry & Schemas"]:::component

        subgraph "Tool Handlers (logical grouping)"
          direction TB
          Market["Market Data Tools<br/>get_hist_data<br/>get_realtime_data"]:::tools
          News["News Tools<br/>get_news_data"]:::tools
          Statements["Financial Statements<br/>get_balance_sheet<br/>get_income_statement<br/>get_cash_flow"]:::tools
          Metrics["Analytics / Metrics<br/>get_inner_trade_data<br/>get_financial_metrics"]:::tools
          Util["Utility<br/>get_time_info"]:::tools
        end

        Akshare["akshare-one (library)<br/>Source selection (eastmoney / sina / xueqiu)"]:::library
      end

      subgraph "Config / Metadata"
        direction TB
        FastMCP["fastmcp.json<br/>(tool schema / descriptor)"]:::meta
        ServerJson["server.json<br/>(server descriptor / metadata)"]:::meta
        Smithery["smithery.yaml<br/>(Smithery publish/install metadata)"]:::meta
        Pyproject["pyproject.toml<br/>(packaging & deps)"]:::meta
        UVLock["uv.lock<br/>(dependency lockfile)"]:::meta
        ReadmeEn["README.md<br/>(public tool surface & modes)"]:::meta
        ReadmeZh["README_zh.md<br/>(public tool surface & modes)"]:::meta
      end

      subgraph "Deployment / Delivery (optional)"
        direction TB
        Docker["Docker Container Boundary<br/>(Dockerfile)"]:::delivery
        CI["CI/CD Publish Pipeline<br/>(GitHub Actions)"]:::delivery
      end
    end

    subgraph "Internet / External Market Data Providers"
      direction TB
      Providers["External Providers (multiple)"]:::external
      Eastmoney["Eastmoney<br/>(incl. eastmoney_direct)"]:::external
      Sina["Sina"]:::external
      Xueqiu["Xueqiu"]:::external
    end
  end

  %% =========================
  %% Relationships (vertical)
  %% =========================
  Client -->|"MCP tool calls (stdio)"| Stdio
  Client -->|"MCP tool calls (streamable-http)"| Http

  Stdio -->|"invokes"| ServerSvc
  Http -->|"routes /mcp"| ServerSvc

  ServerSvc -->|"starts / configures"| Entry
  Entry -->|"initializes"| Core
  Core -->|"registers"| Registry

  Registry -->|"dispatches"| Market
  Registry -->|"dispatches"| News
  Registry -->|"dispatches"| Statements
  Registry -->|"dispatches"| Metrics
  Registry -->|"dispatches"| Util

  Market -->|"fetch via"| Akshare
  News -->|"fetch via"| Akshare
  Statements -->|"fetch via"| Akshare
  Metrics -->|"fetch via"| Akshare
  Util -->|"time info"| Core

  Akshare -->|"HTTP(S) requests"| Providers
  Providers -->|"responses (JSON/HTML), parsed & normalized"| Akshare

  Providers --> Eastmoney
  Providers --> Sina
  Providers --> Xueqiu

  Core -.->|"uses descriptors"| FastMCP
  Core -.->|"uses metadata"| ServerJson
  ServerSvc -.->|"documented by"| ReadmeEn
  ServerSvc -.->|"documented by"| ReadmeZh

  Docker -.->|"containerizes"| ServerSvc
  CI -.->|"publishes"| Smithery
  CI -.->|"builds/releases"| Pyproject
  Pyproject -.->|"locked by"| UVLock

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click ServerSvc "https://github.com/zwldarren/akshare-one-mcp/tree/main/src/akshare_one_mcp/"
  click Entry "https://github.com/zwldarren/akshare-one-mcp/blob/main/src/akshare_one_mcp/__main__.py"
  click Core "https://github.com/zwldarren/akshare-one-mcp/blob/main/src/akshare_one_mcp/server.py"
  click Registry "https://github.com/zwldarren/akshare-one-mcp/blob/main/src/akshare_one_mcp/server.py"
  click FastMCP "https://github.com/zwldarren/akshare-one-mcp/blob/main/fastmcp.json"
  click ServerJson "https://github.com/zwldarren/akshare-one-mcp/blob/main/server.json"
  click Smithery "https://github.com/zwldarren/akshare-one-mcp/blob/main/smithery.yaml"
  click Docker "https://github.com/zwldarren/akshare-one-mcp/tree/main/Dockerfile"
  click CI "https://github.com/zwldarren/akshare-one-mcp/blob/main/.github/workflows/publish-mcp.yml"
  click Pyproject "https://github.com/zwldarren/akshare-one-mcp/blob/main/pyproject.toml"
  click UVLock "https://github.com/zwldarren/akshare-one-mcp/blob/main/uv.lock"
  click ReadmeEn "https://github.com/zwldarren/akshare-one-mcp/blob/main/README.md"
  click ReadmeZh "https://github.com/zwldarren/akshare-one-mcp/blob/main/README_zh.md"

  %% =========================
  %% Styles (with color)
  %% =========================
  classDef client fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1
  classDef server fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
  classDef transport fill:#FFF8E1,stroke:#FF8F00,stroke-width:2px,color:#5D4037
  classDef component fill:#F1F8E9,stroke:#558B2F,stroke-width:1.5px,color:#1B5E20
  classDef tools fill:#E8F5E9,stroke:#43A047,stroke-width:1.5px,color:#1B5E20
  classDef library fill:#E0F7FA,stroke:#00838F,stroke-width:2px,color:#004D40
  classDef external fill:#FCE4EC,stroke:#AD1457,stroke-width:2px,color:#880E4F
  classDef meta fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
  classDef delivery fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238
```
