# datawhalechina/mcp-lite-dev architecture

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

- Interactive diagram: https://gitdiagram.com/datawhalechina/mcp-lite-dev
- Repository: https://github.com/datawhalechina/mcp-lite-dev

## Overview

1. **Repository purpose**
   - This is primarily a **learning repository** for the book/course “MCP极简开发”.
   - It combines **chapter notes** and **small runnable Python examples** rather than one single production application.

2. **Top-level structure**
   - The repo splits cleanly into two major areas:
     - `docs/`: the written course notes, organized by chapter.
     - `src/`: the Python code used in the hands-on chapters.
   - This makes the architecture a mix of **static documentation site** + **example code package**.

3. **Documentation subsystem**
   - `docs/` contains one markdown file per chapter (`ch01` through `ch11`) plus images and a sidebar index.
   - `docs/index.html`, `docs/_sidebar.md`, and `.nojekyll` indicate a **static docs site** setup, likely Docsify-style.
   - Architecturally, this is a separate read-only knowledge layer; it does not drive runtime behavior.

4. **Python package entrypoint**
   - `src/__main__.py` suggests the project can be run as a module from the command line.
   - `src/__init__.py` and the chapter subpackages make `src` a package boundary for the runnable examples.

5. **Shared weather domain code**
   - `src/weather.py` is the most likely shared utility layer for weather-related examples.
   - It probably contains reusable logic for talking to the weather service and normalizing weather data before it is consumed by chapter-specific code.

6. **Chapter 6 implementation**
   - `src/ch06/` contains the chapter 6 code, including:
     - `mcp_client.py`: a client-side MCP integration example.
     - `weather.py`: chapter-specific weather tool/server logic.
   - This chapter appears to focus on the **minimal end-to-end MCP flow**: a client connects to an MCP-capable service/tool and uses weather data as the sample domain.

7. **Chapter 7 implementation**
   - `src/ch07/weather.py` is a separate weather example for the next chapter.
   - The separate package boundary suggests chapter 7 introduces a **different or more advanced implementation** of the same domain, rather than reusing chapter 6 code directly.
   - This is useful for diagramming as a “versioned evolution” of the same capability.

8. **External service dependencies**
   - The repository relies on **OpenWeather** for weather data, configured via `OPENWEATHER_API_KEY`.
   - It also expects an **LLM API endpoint** compatible with SiliconFlow/OpenAI-style configuration via `BASE_URL`, `MODEL`, and `API_KEY`.
   - These are the key external boundaries in the system: weather data provider and model provider.

9. **Runtime/data flow**
   - Typical flow appears to be:
     - user runs the Python example,
     - the code loads environment configuration,
     - the MCP client and/or weather module calls the weather API,
     - model-facing logic uses the configured LLM endpoint when needed,
     - results are returned back to the local client.
   - The architecture is therefore **local Python orchestration around remote APIs**, not a server-heavy deployment.

10. **Configuration boundary**
   - Secrets and environment-specific values are kept outside the code in a `.env` file.
   - This cleanly separates **code**, **credentials**, and **runtime endpoints**.

11. **Packaging and dependency management**
   - `pyproject.toml`, `uv.lock`, and the README’s `uv sync` workflow show the project uses **uv** for dependency resolution and environment setup.
   - The project targets **Python 3.10+**.
   - This matters architecturally because the examples are intended to be reproducible and packageable, not just notebook-style snippets.

12. **Publishing workflow**
   - The README includes a PyPI publish flow for one chapter section, implying the repo also demonstrates **packaging an MCP server for distribution**.
   - That introduces a deployment boundary: local source code can be built into an installable artifact and uploaded externally.

13. **Likely architecture diagram focus**
   - A clear diagram should show:
     - documentation as a separate static subsystem,
     - the Python package split by chapter,
     - shared weather logic reused by examples,
     - external OpenWeather API,
     - external LLM API endpoint,
     - environment variables as configuration inputs.
   - The main design theme is **progressive MCP examples centered on a weather domain**.

Main entry points: [`src/__init__.py`](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/__init__.py) (Src package), [`src/ch07/weather.py`](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch07/weather.py) (Ch7 weather), [`src/ch06/weather.py`](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch06/weather.py) (Ch6 weather), [`src/weather.py`](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/weather.py) (Weather core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_docs_root["Docs site<br/>static site<br/>[index.html]"]
  node_docs_nav["Sidebar<br/>docs nav<br/>[_sidebar.md]"]
  node_docs_readme["Course guide<br/>docs home<br/>[README.md]"]
  node_docs_chapter["Chapter notes<br/>[ch01.md]"]
end

subgraph group_src["Python"]
  node_src_pkg["Src package<br/>python package<br/>[__init__.py]"]
  node_src_entry["Module entry<br/>cli entry<br/>[__main__.py]"]
  node_shared_weather["Weather core<br/>shared module<br/>[weather.py]"]
  node_ch06_client["MCP client<br/>chapter 6 client<br/>[mcp_client.py]"]
  node_ch06_weather["Ch6 weather<br/>chapter 6 tool<br/>[weather.py]"]
  node_ch07_weather["Ch7 weather<br/>chapter 7 example<br/>[weather.py]"]
end

subgraph group_ext["External"]
  node_env_cfg["Env config<br/>runtime config"]
  node_openweather_api[("OpenWeather<br/>weather API")]
  node_llm_api[("LLM API<br/>model API")]
  node_uv_tooling["UV tooling<br/>deps tool<br/>[pyproject.toml]"]
  node_pypi_release(("PyPI release<br/>distribution"))
end

node_docs_root -->|"navigates"| node_docs_nav
node_docs_root -->|"starts at"| node_docs_readme
node_docs_root -->|"contains"| node_docs_chapter
node_src_pkg -->|"exposes"| node_src_entry
node_src_pkg -->|"contains"| node_shared_weather
node_src_pkg -->|"contains"| node_ch06_client
node_src_pkg -->|"contains"| node_ch06_weather
node_src_pkg -->|"contains"| node_ch07_weather
node_src_entry -->|"launches"| node_ch06_client
node_ch06_client -->|"uses"| node_ch06_weather
node_ch06_client -.->|"calls"| node_llm_api
node_ch06_weather -->|"reuses"| node_shared_weather
node_ch07_weather -->|"reuses"| node_shared_weather
node_shared_weather -->|"fetches from"| node_openweather_api
node_ch06_weather -->|"fetches from"| node_openweather_api
node_ch07_weather -->|"fetches from"| node_openweather_api
node_shared_weather -->|"reads"| node_env_cfg
node_ch06_weather -->|"reads"| node_env_cfg
node_ch07_weather -->|"reads"| node_env_cfg
node_ch07_weather -->|"calls"| node_llm_api
node_uv_tooling -.->|"installs"| node_src_pkg
node_uv_tooling -.->|"packages"| node_pypi_release

click node_docs_root "https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/index.html"
click node_docs_nav "https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/_sidebar.md"
click node_docs_readme "https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/README.md"
click node_docs_chapter "https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/ch01/ch01.md"
click node_src_pkg "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/__init__.py"
click node_src_entry "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/__main__.py"
click node_shared_weather "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/weather.py"
click node_ch06_client "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch06/mcp_client.py"
click node_ch06_weather "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch06/weather.py"
click node_ch07_weather "https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch07/weather.py"
click node_uv_tooling "https://github.com/datawhalechina/mcp-lite-dev/blob/master/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_docs_root,node_docs_nav,node_docs_readme,node_docs_chapter toneBlue
class node_src_pkg,node_src_entry,node_shared_weather,node_ch06_client,node_ch06_weather,node_ch07_weather toneAmber
class node_env_cfg,node_openweather_api,node_llm_api,node_uv_tooling,node_pypi_release toneMint
```

## Components

### Docs

Static chapter notes and site shell

- [Docs site](https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/index.html): static site · Docsify-style documentation shell · `docs/index.html`
- [Sidebar](https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/_sidebar.md): docs nav · Chapter navigation for the docs site · `docs/_sidebar.md`
- [Course guide](https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/README.md): docs home · Repository-level reading and course entry · `docs/README.md`
- [Chapter notes](https://github.com/datawhalechina/mcp-lite-dev/blob/master/docs/ch01/ch01.md): chapter notes · Representative chapter note page · `docs/ch01/ch01.md`

### Python

Runnable MCP examples and shared code

- [Src package](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/__init__.py): python package · Package boundary for runnable examples · `src/__init__.py`
- [Module entry](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/__main__.py): cli entry · Runs the examples as a Python module · `src/__main__.py`
- [Weather core](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/weather.py): shared module · Common weather-domain helpers · `src/weather.py`
- [MCP client](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch06/mcp_client.py): chapter 6 client · Client-side MCP integration example · `src/ch06/mcp_client.py`
- [Ch6 weather](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch06/weather.py): chapter 6 tool · Chapter 6 weather tool/server logic · `src/ch06/weather.py`
- [Ch7 weather](https://github.com/datawhalechina/mcp-lite-dev/blob/master/src/ch07/weather.py): chapter 7 example · Chapter 7 evolution of the weather example · `src/ch07/weather.py`

### External

Remote APIs and runtime configuration

- **Env config**: runtime config · Secrets and endpoint settings from environment
- **OpenWeather**: weather API · External weather data provider
- **LLM API**: model API · OpenAI-compatible model endpoint
- [UV tooling](https://github.com/datawhalechina/mcp-lite-dev/blob/master/pyproject.toml): deps tool · Dependency resolution and environment setup · `pyproject.toml`
- **PyPI release**: distribution · Installable package publishing target

## Connections

- Docs site → Sidebar: navigates · Docs shell is organized by the sidebar
- Docs site → Course guide: starts at · Repository guide explains the course structure
- Docs site → Chapter notes: contains · Chapters are published as static markdown pages
- Src package → Module entry: exposes · Package can be run as a module
- Src package → Weather core: contains · Shared weather helpers live at package root
- Src package → MCP client: contains · Chapter 6 client example
- Src package → Ch6 weather: contains · Chapter 6 weather implementation
- Src package → Ch7 weather: contains · Chapter 7 weather implementation
- Module entry → MCP client: launches · Module entrypoint runs the example flow
- MCP client → Ch6 weather: uses · Client talks to the chapter 6 weather service/tool
- MCP client → LLM API: calls · Client can reach an LLM endpoint when needed
- Ch6 weather → Weather core: reuses · Chapter 6 implementation may share normalization and API helpers
- Ch7 weather → Weather core: reuses · Chapter 7 builds on the common weather layer
- Weather core → OpenWeather: fetches from · Weather data ultimately comes from OpenWeather
- Ch6 weather → OpenWeather: fetches from · Chapter 6 weather logic calls the weather provider
- Ch7 weather → OpenWeather: fetches from · Chapter 7 weather logic calls the weather provider
- Weather core → Env config: reads · API keys and runtime endpoints are configured externally
- Ch6 weather → Env config: reads · Chapter 6 uses environment-based configuration
- Ch7 weather → Env config: reads · Chapter 7 uses environment-based configuration
- Ch7 weather → LLM API: calls · Later chapter uses the configured model endpoint
- UV tooling → Src package: installs · Package metadata drives editable installs and sync
- UV tooling → PyPI release: packages · README publish flow implies distribution to PyPI
