nacos-fastapi-mcp-example

这是一个参考的FastAPI服务，演示了如何集成Nacos进行配置和服务发现，并结合MCP（模型上下文协议）生态系统。该项目使用PDM管理，并针对Python 3.13。

特性

• 具有自定义生命周期的FastAPI应用程序，挂载MCP工具并将其注册到Nacos。
• 运行时从Nacos同步配置，支持YAML/JSON解析和内存缓存快照。
• 使用Loguru进行结构化日志记录，并提供跟踪ID传播工具（位于src/utils中）。
• PDM脚本用于常见工作流（dev、start、lint、fmt、typecheck、test）。

项目布局

app/                FastAPI入口点，Nacos集成，设置辅助
src/utils/          应用程序共享的日志和跟踪辅助
logs/               本地日志输出（在Docker镜像中忽略）
.nacos-data/        本地Nacos快照存储（在Docker镜像中忽略）

预备条件

• Python 3.13
• PDM
• Nacos服务器3.x（已测试3.0.3），并且可以访问凭证/命名空间（NACOS_SERVER_ADDR，NACOS_USERNAME，NACOS_NAMESPACE等）
• 可选：Docker 24+用于容器化部署

准备Nacos

1. 将样本配置nacos-fastapi-mcp-example.yaml上传到Nacos配置服务。
   • 数据ID：nacos-fastapi-mcp-example.yaml
   • 组：DEFAULT_GROUP
   • 命名空间：与环境中的NACOS_NAMESPACE对齐
2. 根据运行时需要调整YAML内容（数据库DSN，特性标志等）。
3. 确保Nacos HTTP/GRPC端点可以从该FastAPI服务运行的位置访问。

本地设置

1. 复制环境示例并根据您的设置调整值：

   cp .env.example .env
   

2. 使用PDM安装依赖项（如果配置了，会自动创建虚拟环境）：

   pdm install
   

运行服务

• 开发模式带热重载：

  pdm run dev
  

• 类生产单进程模式（依赖于.env配置）：

  pdm run start
  

应用程序暴露：

• GET /health — 轻量级健康检查。
• GET /config/nacos — 当前从Nacos获取的运行时配置快照。

Docker使用

仓库附带一个Dockerfile。因为.env被.dockerignore排除，所以在运行时传递它。

构建镜像：

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

运行容器（映射端口并提供.env文件）：

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

如果暴露不同的APP_PORT，请调整端口映射。

注意事项

• 默认的.env.example启用Nacos注册；确保Nacos地址和凭证可达，或者切换MCP_REGISTER_ENABLED/APP_WORKERS以进行本地调试。
• 日志输出位于本地的logs/中；如果您想在Docker内部持久化日志，请挂载卷或覆盖APP_LOG_PATH。

文档

更多中文背景信息，请参见README.zh.md。