ori88c-python-templates/fastmcp-polyrepo-template

Production-grade FastMCP template built around **dependency injection** and **zero global state**.
A composition root wires clients, services, and loggers so tests inject dependencies instead of monkeypatching; Cursor rules keep AI edits copying this architecture. Layered import DAG, Testcontainers, Prometheus, and Kubernetes probes included.
Table of Contents
- Highlights
- Why this template
- Architecture
- Layout
- Configuration
- Logging
- Demonstrative Feature - User Notes
- Running locally
- Container image
- Production deploy
- Testing
- Linting and type checking
- Pre-commit hooks
- CI
- Authentication
Highlights
- **Dependency injection, zero global state** 🧩: Every component takes dependencies in __init__; LifecycleManager (the composition root) constructs the clients, services, and loggers and wires them — main.py only builds AppConfig and that manager. No module-level config, logger, or client, so tests inject dependencies instead of monkeypatching or process-wide setup.
- **Three-layer import DAG, enforced** 🧭: The protocol surface (http_routes / mcp_primitives / middlewares / prometheus), services, and clients stay loosely coupled so you can test a service without FastMCP and a client without a registrator. Packages import downward only; lint-imports fails cycles and FastMCP leaking into services or clients.
- **Sample vertical slice** 🚩: UserNotesService plus its tool, resource, and prompt, Prometheus series, and matching integration and e2e tests. Copy that pattern for the next feature.
- **Nested Pydantic config** ⚙️: AppConfig composes resource-specific models (redis, logger, prometheus, …). Invalid config fails at startup, not on the first request.
- **Structured JSON logging** 📡: Every line carries prod-grade fields (app, instance, env, app.version, correlation_id). Each component gets a named child logger with its own context, so you can filter easily — with grep, or with observability tools such as Groundcover, Grafana, and Datadog.
- **Unit, integration, and e2e from day 1** 🧪: pytest is wired for all three: in-process units, Testcontainers against real Redis, and the real app through LifecycleManager. The notes slice is covered at each layer.
- **Cursor rules that keep the conventions** 🤖: Checked-in .cursor/rules encode layers, logging, tests, and metrics so AI-assisted edits copy this architecture instead of inventing a new one.
- **Production-shaped ops** 🚢: Non-root multi-stage image, Kubernetes liveness and readiness probes (GET /livez, GET /readyz), Prometheus scrape (GET /metrics), and GitHub Actions CI. HTTP-aware Prometheus series live in prometheus/; the notes counters live in metrics/.
- **Supply-chain hygiene** 🔒: SHA-pinned Actions, weekly Dependabot for the uv lockfile and GitHub Actions, and a separate uv audit workflow on push/PR plus a weekly schedule so a CVE published while main is idle still fails the Audit badge.
Why this template
Unlike opinionated application frameworks such as NestJS, Spring, and .NET, FastMCP does not
prescribe a strict architecture. Without widely shared project conventions, **tightly coupled
components, module-level globals, and related anti-patterns are common in Python codebases**, in
part because package docs favor short examples that use global state for brevity. The risk is
sharper in AI-assisted development: each existing pattern becomes the baseline the next
change copies. This template is a starting architecture that follows best practices from the
first commit, so you can spend the remaining effort on the product.
The guiding constraint: nothing important is reachable through a module-level global. No global
config object, no global logger, no import-time singletons. Every component declares what it needs
in its __init__, and a **single composition root** (LifecycleManager) wires those
dependencies together. That is what makes the code testable without monkeypatching and without
import-order surprises.
This template does not ship a database. For an MCP server, a database is not the usual
resource: a tool is more likely to call a service client than to query a database