nacos-fastapi-mcp-example

A reference FastAPI service that demonstrates how to integrate Nacos for configuration and service discovery together with the MCP (Model Context Protocol) ecosystem. The project is managed with PDM and targets Python 3.13.

Features

• FastAPI application with custom lifespan that mounts MCP tooling and registers the service to Nacos.
• Runtime configuration syncing from Nacos with YAML/JSON parsing and in-memory cache snapshots.
• Structured logging via Loguru with trace ID propagation utilities (src/utils).
• PDM scripts for common workflows (dev, start, lint, fmt, typecheck, test).

Project Layout

app/                FastAPI entrypoints, Nacos integration, settings helper
src/utils/          Logging and trace helpers shared across the app
logs/               Local log output (ignored in Docker image)
.nacos-data/        Local Nacos snapshot storage (ignored in Docker image)

Prerequisites

• Python 3.13
• PDM
• Nacos server 3.x (tested with 3.0.3) and reachable credentials/namespace (NACOS_SERVER_ADDR, NACOS_USERNAME, NACOS_NAMESPACE, ...)
• Optional: Docker 24+ for containerized deployments

Preparing Nacos

• Upload the sample configuration nacos-fastapi-mcp-example.yaml to the Nacos Config Service.

• Data ID: nacos-fastapi-mcp-example.yaml

• Group: DEFAULT_GROUP

• Namespace: align with NACOS_NAMESPACE in your environment
• Adjust the YAML contents as needed for your runtime (database DSN, feature flags, etc.).
• Ensure the Nacos HTTP/GRPC endpoints are accessible from where this FastAPI service runs.

Local Setup

• Copy the environment example and adjust values for your setup:

cp .env.example .env

• Install dependencies with PDM (a virtualenv will be created automatically if configured):

pdm install

Running the Service

• Development mode with hot reload:

pdm run dev

• Production-style single process (relies on the .env configuration):

pdm run start

The application exposes:

• GET /health — lightweight health probe.
• GET /config/nacos — current runtime configuration snapshot from Nacos.

Docker Usage

The repository ships with a Dockerfile. Because .env is excluded by .dockerignore, pass it at runtime.

Build the image:

docker build -t nacos-fastapi-mcp-example:v0.1.0 .

Run the container (map ports and supply the .env file):

docker run -d \
  --name nacos-fastapi-mcp-example \
  --env-file .env \
  -p 8000:8000 \
  nacos-fastapi-mcp-example:v0.1.0

Adjust the port mapping if you expose a different APP_PORT.

Notes

• The default .env.example enables Nacos registration; ensure the Nacos address and credentials are reachable, or toggle MCP_REGISTER_ENABLED/APP_WORKERS for local debugging.
• Logging output lives in logs/ locally; mount a volume or override APP_LOG_PATH if you want to persist logs inside Docker.

Documentation

For additional context in Chinese, see README.zh.md.