How datawhalechina/mcp-lite-dev works
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: __init__.py Src package · ch07/weather.py Ch7 weather · ch06/weather.py Ch6 weather · src/weather.py Weather core
Components 15
Docs
Static chapter notes and site shell
- Docs site · Docsify-style documentation shell
docs/index.html - Sidebar · Chapter navigation for the docs site
docs/_sidebar.md - Course guide · Repository-level reading and course entry
docs/README.md - Chapter notes · Representative chapter note page
docs/ch01/ch01.md
Python
Runnable MCP examples and shared code
- Src package · Package boundary for runnable examples
src/__init__.py - Module entry · Runs the examples as a Python module
src/__main__.py - Weather core · Common weather-domain helpers
src/weather.py - MCP client · Client-side MCP integration example
src/ch06/mcp_client.py - Ch6 weather · Chapter 6 weather tool/server logic
src/ch06/weather.py - Ch7 weather · Chapter 7 evolution of the weather example
src/ch07/weather.py
External
Remote APIs and runtime configuration
- Env config · Secrets and endpoint settings from environment
- OpenWeather · External weather data provider
- LLM API · OpenAI-compatible model endpoint
- UV tooling · Dependency resolution and environment setup
pyproject.toml - PyPI release · Installable package publishing target
Connections 22
- 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