FastAPI MCP LangGraph 模板

一款用于智能体编排的现代化模板——专为快速迭代和可扩展部署而设计，采用高度可定制、社区支持的工具，如 MCP、LangGraph 等。

访问 GitHub：

[!注意] 请在此处查看带有演示视频的文档：这里。此仓库不包含演示视频。

• FastAPI MCP LangGraph 模板
  • 核心功能
    • 技术栈与特性
    • 计划中的功能
  • 架构
    • 检查器
    • 模板设置
    • 反向代理
    • 计划中的功能图示
      • 监控与可观测性
      • 认证与授权
  • 快速入门
  • 开发
    • VSCode 开发容器
    • 无需 VSCode 开发容器
  • 调试
  • 重构后的 Markdown 文件
    • MCP
    • LangGraph
    • Supabase
    • Langfuse
    • Grafana 堆栈

核心功能

是一种开放协议，用于标准化应用程序向大语言模型提供上下文的方式。

• 可无缝集成大语言模型，并拥有不断增长的社区集成列表，详情请见此处
• 无 LLM 提供商锁定

用于可定制的智能体编排

• 原生流式传输，适用于复杂的智能体工作流用户体验
• 原生持久化聊天历史和状态管理

技术栈与特性

• 用于 Python 后端 API
• 用于 Python SQL 数据库交互（ORM + 验证）。
  • 包装了
• 用于 LLM 可观测性和 LLM 指标
• 用于数据验证和设置管理
• 用于 DB RBAC
  • 关系型数据库
  • 向量存储
• 反向代理
• 用于开发和生产环境

计划中的功能

• 用于抓取指标
• 用于可视化指标
• SaaS 提供商，通过 OAuth 2.0 实现 OIDC 和 JWT 的认证与授权
• 使用 Github Actions 进行 CI/CD
  • :dollar: 将实时演示部署到
  • 使用 IaC 进行资源 provision
  • 将构建好的镜像推送到 ECR 和 Dockerhub

架构

本节概述了服务的架构、它们之间的交互以及计划中的功能。

检查器

检查器通过 SSE 协议与每个 MCP 服务器通信，而每个服务器则遵循 MCP 规范。

graph LR

  subgraph localhost
    A[检查器]
    B[DBHub 服务器]
    C[Youtube 服务器]
    D[自定义服务器]
  end

  subgraph Supabase 云
    E[Supabase 数据库]
  end

  subgraph Google 云
    F[Youtube API]
  end

  A<-->|协议|B
  A<-->|协议|C
  A<-->|协议|D
  B<-->E
  C<-->F

模板设置

当前模板并未连接所有 MCP 服务器。此外，API 服务器使用 SQL ORM 与数据库进行通信。

graph LR

  subgraph localhost
    A[API 服务器]
    B[DBHub 服务器]
    C[Youtube 服务器]
    D[自定义服务器]
  end

  subgraph Supabase 云
    E[Supabase 数据库]
  end

  A<-->|协议|D
  A<-->E

反向代理

可以扩展以支持其他服务，例如前端和/或某些后端服务，这些服务可以选择在本地托管而非云端运行（例如 Langfuse）。

graph LR
  A[Web 浏览器]

  subgraph localhost
    B[Nginx 反向代理]
    C[API 服务器]
  end

  A-->B
  B-->C

计划中的功能图

监控与可观测性

graph LR

  subgraph 本地主机
    A[API服务器]
  end

  subgraph Grafana Cloud
    B[Grafana]
  end

  subgraph Langfuse Cloud
    C[Langfuse]
  end

  A -->|指标与日志| B
  A -->|追踪与事件| C

身份验证与授权

Auth0 来源

快速入门

设置以在生产环境和开发环境中运行该仓库。

使用以下命令构建社区 YouTube MCP 镜像：

./community/youtube/build.sh

:::tip

与其在本地克隆或子模块化仓库后再构建镜像，不如使用此脚本在一个临时的 Docker-in-Docker 容器中构建 Docker 镜像。这种方法避免了将一次性文件污染到你的本地环境，因为容器退出后会清理所有内容。

:::

然后使用以下命令构建其他镜像：

docker compose -f compose-dev.yaml build

复制环境文件：

cp .env.sample .env

将你的 API 密钥和值添加到相应的文件中：./envs/backend.env、./envs/youtube.env 和 .env。

OPENAI_API_KEY=sk-proj-...
POSTGRES_DSN=postgresql://postgres...

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com

ENVIRONMENT=production

YOUTUBE_API_KEY=...

在 shell 中设置环境变量：（兼容 bash 和 zsh）

set -a; for env_file in ./envs/*; do source $env_file; done; set +a

启动生产容器：

docker compose up -d

  api:
    image: api:prod
    build:
      dockerfile: ./backend/api/Dockerfile
    # highlight-next-line
    entrypoint: bash -c "sleep infinity"
    env_file:
      - ./envs/backend.env

code --no-sandbox .

docker compose -f compose-dev.yaml up -d

docker compose -f compose-dev.yaml exec nginx sh -c "nginx -s reload"

FastAPI MCP LangGraph Template 快速上手指南

本指南帮助中国开发者快速搭建基于 FastAPI、MCP (Model Context Protocol) 和 LangGraph 的智能体编排模板。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (需安装 WSL2)
• Docker & Docker Compose: 必须安装并正在运行。
  • 国内用户建议: 配置 Docker 镜像加速器（如阿里云、腾讯云或 DaoCloud 加速），以加快镜像拉取速度。
• Git: 用于克隆代码仓库。
• API Keys: 准备好以下服务的密钥：
  • OpenAI API Key (或其他兼容 LLM)
  • Supabase 项目 URL 和 Key (用于数据库)
  • Langfuse Keys (用于可观测性，可选)
  • YouTube Data API Key (如需使用示例中的 YouTube 功能)

安装步骤

1. 克隆项目

git clone https://github.com/NicholasGoh/fastapi-mcp-langgraph-template.git
cd fastapi-mcp-langgraph-template

2. 构建社区 MCP 镜像

首先构建示例中使用的 YouTube MCP 服务器镜像。该脚本会在临时容器中构建，避免污染本地环境。

./community/youtube/build.sh

3. 构建主服务镜像

使用 Docker Compose 构建后端 API 及其他核心服务。

docker compose -f compose-dev.yaml build

4. 配置环境变量

复制示例配置文件到实际使用文件：

cp .env.sample .env

编辑以下文件，填入您的 API Keys 和数据库连接信息：

• ./envs/backend.env
• ./envs/youtube.env
• .env

关键配置项示例：

OPENAI_API_KEY=sk-proj-...
POSTGRES_DSN=postgresql://postgres...

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com

ENVIRONMENT=production

YOUTUBE_API_KEY=...

5. 加载环境变量

在终端中加载所有环境变量（兼容 bash 和 zsh）：

set -a; for env_file in ./envs/*; do source $env_file; done; set +a

6. 启动服务

启动生产环境容器（开发环境请使用 compose-dev.yaml）：

docker compose up -d

基本使用

服务启动后，您可以通过以下方式验证和使用：

1. 访问 API 服务

默认情况下，Nginx 反向代理会处理请求。您可以直接通过浏览器或工具访问本地 API 端点（通常映射到 http://localhost 或配置中指定的端口）。

2. 开发模式调试 (推荐 VSCode 用户)

如果您使用 VSCode 进行开发，可以利用 Devcontainer 获得完整的 IntelliSense 和调试支持：

1. 修改 ./compose-dev.yaml 中的 api 服务入口点，允许调试器附加：

   # 在 ./compose-dev.yaml 中找到 api 部分
   api:
     image: api:prod
     build:
       dockerfile: ./backend/api/Dockerfile
     entrypoint: bash -c "sleep infinity"  # 修改此行
     env_file:
       - ./envs/backend.env
   

2. 在 VSCode 中打开项目文件夹，按下 F1，输入并选择： Dev Containers: Rebuild and Reopen in Container
3. 容器重启后，即可在 VSCode 中设置断点并启动 FastAPI 调试。

3. 非 VSCode 开发模式

如果不使用 Devcontainer，可直接启动开发环境：

docker compose -f compose-dev.yaml up -d

4. 重新加载 Nginx 配置

如果在开发过程中修改了路由或服务配置，可能需要手动重载 Nginx：

docker compose -f compose-dev.yaml exec nginx sh -c "nginx -s reload"

5. 查看文档与进阶功能

本项目将部分详细文档拆分到了 docs 目录，建议查阅以下文件以了解具体模块的配置：

• MCP 集成: ./docs/mcp.md
• LangGraph 工作流: ./docs/langgraph.md
• Supabase 数据库: ./docs/supabase.md
• Langfuse 监控: ./docs/langfuse.md