JinDaGe - fastapi-todo-listapp-mcpserver MCP Details

article

README

🚀 2025版FastAPI待办事项列表与MCP服务器

这是一个使用FastAPI构建的现代待办事项列表应用程序，它通过FastMCP集成了MCP（模型上下文协议）服务器，可与Gemini CLI进行交互，为用户提供便捷的待办事项管理体验。

🚀 快速开始

按照以下步骤快速启动项目：

# 安装依赖
pip install -r requirements.txt

# 在终端1启动FastAPI
python main.py

# 在终端2启动MCP服务器
python mcp_server.py

# 测试API
curl http://localhost:8000/todos/stats

✨ 主要特性

✅ 支持待办事项的完整CRUD操作。
📊 提供任务统计端点，方便跟踪任务状态。
🔌 使用FastMCP（2025）构建的MCP服务器。
📝 预加载5条虚拟数据，方便测试。
🤖 支持与Gemini CLI集成。
🎯 仅需2个文件，即可完成简单设置。

📦 安装指南

1. 安装依赖

pip install -r requirements.txt

2. 启动FastAPI服务器

python main.py

API的访问地址如下：

API基础地址：http://localhost:8000
文档地址：http://localhost:8000/docs
统计端点：http://localhost:8000/todos/stats

3. 启动MCP服务器（在另一个终端中执行）

python mcp_server.py

💻 使用示例

基础用法

以下是一些使用curl命令测试API的示例：

# 获取所有待办事项
curl http://localhost:8000/todos

# 获取统计信息
curl http://localhost:8000/todos/stats

# 创建新的待办事项
curl -X POST "http://localhost:8000/todos" \
     -H "Content-Type: application/json" \
     -d '{"title": "Test Todo", "description": "Created via curl"}'

高级用法

可以使用MCP服务器提供的工具与Gemini CLI进行交互，例如：

python mcp_server.py

这将测试连接并显示当前的待办事项。

📚 详细文档

📊 API端点

| 方法 | 端点 | 描述 | |--------|----------|-------------| | GET | / | 获取API信息和可用端点 | | GET | /todos | 获取所有待办事项 | | GET | /todos/stats | 获取待办事项统计信息 | | GET | /todos/{id} | 根据ID获取特定待办事项 | | POST | /todos | 创建新的待办事项 | | PUT | /todos/{id} | 更新现有待办事项 | | DELETE | /todos/{id} | 删除待办事项 |

🔌 MCP服务器工具

MCP服务器为Gemini CLI提供了以下工具：

get_todos - 获取所有待办事项
get_todo_stats - 获取统计信息（总数、已完成、待处理）
create_todo - 创建新的待办事项
update_todo - 更新现有待办事项
delete_todo - 删除待办事项
get_todo_by_id - 获取特定待办事项的详细信息

🤖 Gemini CLI集成

配置

.gemini/settings.json文件用于配置Gemini CLI以连接到MCP服务器：

{
  "mcpServers": {
    "todo-mcp-server": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/home/okki/Desktop/projects/fast-apimcp"
    }
  }
}

示例命令

当两个服务器都运行后，你可以向Gemini CLI提问：

"还剩多少任务？" → 获取待处理任务数量
"显示所有待办事项" → 列出所有任务
"创建一个名为审查代码的新任务" → 添加新任务
"将任务1标记为已完成" → 更新任务状态
"删除任务3" → 删除任务

🔧 技术细节

本项目使用的技术栈如下：

FastAPI - 现代Python Web框架
FastMCP - 现代MCP服务器库（2025）
Pydantic - 数据验证和序列化
Uvicorn - ASGI服务器
httpx - 异步HTTP客户端

📝 虚拟数据

应用程序预加载了5条虚拟待办事项：

学习FastAPI（待处理） - 完成FastAPI教程
构建MCP服务器（待处理） - 为Gemini CLI创建MCP服务器
测试集成（待处理） - 测试FastAPI与MCP服务器的集成
部署应用程序（已完成） - 部署到生产环境
编写文档（待处理） - 创建API文档

📈 统计示例

以下是一个统计信息的示例：

{
  "total_todos": 5,
  "completed_todos": 1,
  "pending_todos": 4,
  "completion_percentage": 20.0
}

🐛 故障排除

常见问题

"无法连接到FastAPI"
- 确保先启动FastAPI：python main.py
"找不到模块：fastmcp"
- 安装fastmcp：pip install fastmcp
"端口8000已被占用"
- 停止其他服务或在main.py中更改端口
MCP服务器无法连接
- 检查.gemini/settings.json配置
- 确保两个服务器都在运行

📹 演示视频

观看演示视频：2025版FastAPI待办事项列表与MCP服务器演示

一切就绪后，你将拥有：

✅ 提供待办事项API的FastAPI
✅ 连接到FastAPI的MCP服务器
✅ 能够管理待办事项的Gemini CLI
✅ 实时待办事项统计信息
✅ 自然语言待办事项管理功能

非常适合提高生产力和任务跟踪！ 🚀

fastapi-todo-listapp-mcpserver