MCP Server Fastapp

Todo 应用 - 基于 FastAPI 的 MCP 服务器与 Gemini CLI 集成

一个使用FastAPI和MongoDB构建的综合待办事项应用程序，作为MCP（模型上下文协议）服务器暴露出来，以便与Gemini CLI集成。

🎯 项目概述

这个项目展示了：

• ✅（正确/对） FastAPI 应用程序 具备完整的CRUD操作功能
• ✅ MongoDB 集成 配备异步电机驱动器
• ✅ MCP 服务器 使用FastMCP框架
• ✅ 表示“正确”或“已确认”。 Gemini CLI 集成 用于自然语言待办事项管理
• ✅ 翻译为中文是：✅（这个符号本身在中文中没有特定的含义，通常用作表示正确、确认或完成的标记，直接保留原样即可。） 完整的工具套件 配备10个MCP工具和2个提示

特点/特性

FastAPI 应用程序

• ✅ 表示“正确”或“完成”的意思。 创建待办事项添加新待办事项，包括标题、描述、优先级、截止日期和标签
• ✅ 阅读所有（任务/项目）获取带分页、过滤和搜索功能的待办事项
• ✅ 更新所有待办事项修改现有的待办事项
• ✅ 删除所有待办事项删除全部
• ✅ 切换完成状态快速标记待办事项为已完成/未完成
• 🔍（放大镜图标，通常表示搜索、查看细节或调查） 搜索按标题和描述搜索所有待办事项
• 🏷️ 标签用自定义标签整理所有事项
• ⚡（闪电符号，无具体含义，可表示快速、能量、电力等概念） 优先级级别设置优先级（低、中、高）
• 📅 日历 截止日期设定并跟踪截止日期
• 📊 表格/数据图表 统计获取完成率和优先级细分
• 🔄（循环/重复） 分页带分页功能的高效数据加载
• 🎯（瞄准靶心） 过滤按完成状态、优先级和标签进行筛选

MCP服务器功能

• 10个MCP工具完成所有任务管理功能
• 2个MCP提示常见操作的有用模板
• 自然语言接口与Gemini CLI一起使用
• 实时数据库同步所有操作持久化到MongoDB

技术栈

• 后端FastAPI
• 数据库使用Motor（异步驱动程序）的MongoDB
• 验证Pydantic
• 文档自动OpenAPI/Swagger文档

安装

1. 克隆仓库

   git clone 
   cd todo-app

1. 安装依赖项

   pip install -r requirements.txt

1. 设置MongoDB

- 在本地安装MongoDB或使用MongoDB Atlas - 更新连接字符串中的 config.py 如需 - 默认值： mongodb://localhost:27017

1. 运行 FastAPI 应用程序

   python run.py

或者直接使用 uvicorn：

   uvicorn main:app --reload --host 0.0.0.0 --port 8000

1. 在Gemini CLI中安装MCP服务器

   gemini mcp add "Todo App MCP Server" "python mcp_server.py" \
     --env MONGODB_URL="" \
     --env DATABASE_NAME="todo"

API 文档

服务器运行后，请访问：

• Swagger UIhttp://localhost:8000/docs 翻译为中文是：“本地主机8000端口的文档页面”
• ReDoc（注：ReDoc是一个用于生成API文档的工具或框架的名称，在中文中通常直接使用其英文原名，不进行翻译）http://localhost:8000/redoc（该网址可直接在浏览器中输入访问，无需翻译，但为说明其含义，可表述为：“本地主机8000端口上的Redoc文档界面”）

API 端点

健康检查

• GET / - 健康检查端点

全面管理

• POST /todos - 创建一个新的待办事项
• GET /todos - 获取待办事项，并进行过滤和分页
• GET /todos/{todo_id} - 获取特定的待办事项
• PUT /todos/{todo_id} - 更新一个待办事项
• DELETE /todos/{todo_id} - 删除一个待办事项
• PATCH /todos/{todo_id}/toggle - 切换待办事项完成状态

特殊查询

• GET /todos/completed - 获取所有已完成的待办事项
• GET /todos/pending - 获取所有待办事项
• GET /todos/tag/{tag} - 按标签获取所有待办事项
• GET /stats - 获取所有待办事项的统计数据

使用示例

创建一个待办事项

curl -X POST "http://localhost:8000/todos" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Learn FastAPI",
    "description": "Complete the FastAPI tutorial",
    "priority": "high",
    "tags": ["learning", "backend"]
  }'

获取带有过滤条件的所有待办事项

curl "http://localhost:8000/todos?page=1&limit=10&completed=false&priority=high&search=learn"

切换待办事项完成状态

curl -X PATCH "http://localhost:8000/todos/{todo_id}/toggle"

获取统计数据

curl "http://localhost:8000/stats"

📹 视频演示

完整的视频演示可在以下获取 video/ 文件夹显示：

• FastAPI应用程序正在运行，API文档
• MCP服务器启动与功能
• Gemini CLI 集成与 MCP 工具使用
• 数据库操作和数据持久化
• 自然语言待办事项管理

视频位置： video/demo.webm

🚀 MCP服务器使用情况

使用Gemini CLI

安装完成后，您可以通过Gemini CLI使用自然语言：

gemini chat

然后问一些诸如：

• *“创建一个待办事项，以高优先级审查项目提案”*
• *“显示我所有未完成的待办事项”*
• *“将提案审核标记为已完成”*
• *“给我关于我待办事项进度的统计数据”*
• *“查找所有标记为‘工作’的待办事项”*

可用的MCP工具

• create_todo - 创建带有所有选项的新待办事项
• get_todos - 列出所有待办事项，并支持过滤和分页
• get_todo - 通过ID获取特定待办事项
• update_todo - 更新现有的待办事项
• delete_todo - 删除所有待办事项
• toggle_todo - 切换完成状态
• get_completed_todos - 获取所有已完成的待办事项
• get_pending_todos - 获取所有待办事项
• get_todos_by_tag - 按标签过滤所有待办事项
• get_todo_stats - 获取全面统计数据

数据模型

全部模式

{
  "id": "string",
  "title": "string (1-200 chars)",
  "description": "string (optional, max 1000 chars)",
  "completed": "boolean",
  "priority": "low|medium|high",
  "due_date": "datetime (optional)",
  "tags": ["string array"],
  "created_at": "datetime",
  "updated_at": "datetime"
}

配置

该应用程序使用环境变量进行配置：

• MONGODB_URLMongoDB 连接字符串（默认：mongodb://localhost:27017）
• DATABASE_NAME数据库名称（默认：todo_app）

错误处理

该API包含全面的错误处理功能：

• 400：错误请求（验证错误）
• 404: 未找到（任务未找到）
• 500：内部服务器错误（服务器问题）

发展

项目结构

todo-app/
├── main.py          # FastAPI application
├── models.py        # Pydantic models
├── crud.py          # Database operations
├── database.py      # Database connection
├── config.py        # Configuration
├── requirements.txt # Dependencies
└── README.md        # Documentation

添加新功能

1. 新领域添加到 TodoBase 模型输入 models.py
2. 新的终点（或目标）添加路由到 main.py
3. 新业务/新运营添加方法到 TodoCRUD （进入）课堂 crud.py

许可证

这个项目是开源的，并遵循MIT许可协议。