使用说明

Yata - 任务管理应用

一个使用Python FastAPI作为后端、React TypeScript作为前端，并集成Google OAuth认证的简单待办事项应用。

技术栈

后端使用 FastAPI 的 Python
前端使用TypeScript编写的React，由Bun管理
数据库用于数据持久化的PostgreSQL
缓存/会话用于会话管理的Redis
认证Google OAuth 2.0
开发环境Docker Compose
MCP 服务器用于AI集成的模型上下文协议服务器

建筑学

系统架构

Yata应用程序遵循现代微服务架构，实现了前端、后端和数据层之间的清晰分离。该系统支持通过MCP（模型上下文协议）服务器进行网页浏览器交互以及AI助手集成。

认证流程

认证过程使用Google OAuth 2.0来安全地验证用户身份。流程始于用户点击登录按钮，随后被重定向至Google进行认证，并在后端建立会话后完成。

开发环境

开发环境使用Docker Compose来协调所有服务。每个组件都在自己的容器中运行，并启用了热重载以实现快速开发。MCP服务器容器连接到后端API以集成AI助手。

生产架构

生产环境旨在实现高可用性和可扩展性。它包括负载均衡、SSL终止、使用Prometheus和Grafana进行监控，以及容器编排。该架构通过MCP服务器支持网页流量和AI助手交互。

OAuth 2.0 机器对机器流程（MCP）

MCP服务器使用OAuth 2.0客户端凭证流与Yata API进行机器到机器的认证。这使得AI助手能够在没有用户干预的情况下安全地与待办事项管理系统进行交互。

该流程包括三个阶段：

设置阶段一次性将MCP服务器注册为OAuth客户端
认证流程用客户端凭据交换访问令牌
全部操作使用访问令牌对任务列表执行创建、读取、更新和删除（CRUD）操作

如需查看更详细的架构图，请参阅 docs/architecture-diagrams.md（文件路径，可翻译为“文档/架构图说明.md”或保持原样，因为文件路径通常不直接翻译）。

先决条件

Docker 和 Docker Compose
Google OAuth 客户端ID和密钥

设置

克隆仓库
```
git clone <repository-url>
cd yata
```

设置环境变量

cp .env.example .env

在（相应位置）填写您的Google OAuth凭据 .env 文件：

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

启动开发环境

docker-compose -f docker-compose.dev.yml up --build

访问该应用程序
- 前端地址：http://localhost:3000
- 后端API：http://localhost:8000
- API文档：http://localhost:8000/docs

Google OAuth 设置

前往 Google 云控制台
创建一个新项目或选择一个现有项目
启用Google+ API
创建OAuth 2.0凭据
添加授权重定向URI： http://localhost:3000/auth/callback
复制客户端ID和客户端密钥到您的 .env 文件

项目结构

yata/
├── backend/
│   ├── app/
│   │   ├── api/          # API endpoints
│   │   ├── core/         # Core configuration
│   │   ├── models/       # Database models
│   │   ├── schemas/      # Pydantic schemas
│   │   ├── services/     # Business logic
│   │   └── main.py       # FastAPI application
│   ├── requirements.txt
│   └── Dockerfile.dev
├── frontend/
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── services/     # API client
│   │   ├── types/        # TypeScript types
│   │   ├── utils/        # Utility functions
│   │   └── App.tsx       # Main React component
│   ├── package.json
│   └── Dockerfile.dev
├── mcp-yata/             # MCP Server for AI integration
│   ├── mcp_yata/
│   │   ├── server.py     # Main MCP server
│   │   ├── auth.py       # OAuth client
│   │   ├── client.py     # API client
│   │   ├── tools.py      # MCP tools
│   │   └── config.py     # Configuration
│   ├── requirements.txt
│   └── Dockerfile
├── docs/                 # Documentation
│   ├── architecture-diagrams.md
│   └── mcp-*.md
├── docker-compose.dev.yml
├── docker-compose.prod.yml
└── README.md

API 端点

认证

GET /api/v1/auth/google/login - 重定向到Google OAuth
GET /api/v1/auth/google/callback - OAuth 回调处理程序
POST /api/v1/auth/logout - 登出用户
GET /api/v1/auth/me - 获取当前用户信息

所有人

GET /api/v1/todos - 获取已认证用户的全部待办事项
POST /api/v1/todos - 创建新的待办事项
GET /api/v1/todos/{id} - 获取特定待办事项
PUT /api/v1/todos/{id} - 更新待办事项
DELETE /api/v1/todos/{id} - 删除待办事项

OAuth 2.0（用于MCP）

POST /oauth/token - 获取用于机器到机器身份验证的OAuth令牌

MCP服务器集成

该项目包含一个模型上下文协议（MCP）服务器，使AI助手能够通过OAuth 2.0机器对机器身份验证与Yata API进行交互。

设置MCP服务器

为MCP服务器创建OAuth凭据：

# In the backend application
# Create an OAuth client with client_credentials grant type

配置MCP服务器环境变量：

# In mcp-yata/.env
OAUTH_CLIENT_ID=your_mcp_client_id
OAUTH_CLIENT_SECRET=your_mcp_client_secret
OAUTH_TOKEN_URL=http://backend:8000/oauth/token
API_BASE_URL=http://backend:8000/api/v1

启动MCP服务器：
```
python -m mcp_yata.server
```

可用的MCP工具

create_todo - 创建一个新的待办事项
list_todos - 获取已认证用户的全部待办事项
get_todo - 通过ID获取特定的待办事项
update_todo - 更新现有的待办事项
delete_todo - 删除一个待办事项

有关MCP实现的更多详细信息，请参阅 docs/mcp-server-architecture.md 翻译为中文是：“文档/mcp服务器架构.md”。

发展

后端开发

后端运行在8000端口，并启用了热重载功能
数据库迁移在启动时自动处理
API文档可在以下位置获取 /docs

前端开发

前端运行在3000端口，并启用了热重载功能
TypeScript 已配置为启用严格类型检查
Tailwind CSS 用于样式设计

数据库管理

PostgreSQL 数据持久化存储在 Docker 卷中
Redis用于会话管理
数据库模式在启动时自动创建

生产部署

对于生产环境部署，您需要：

使用生产环境的Dockerfile（而非 .dev 版本）
设置适当的环境变量
配置HTTPS
设置一个合适的数据库和Redis实例
配置适当的CORS设置

做出贡献

为仓库创建分支（或：克隆仓库）
创建一个特性分支
进行你的更改
彻底测试
提交拉取请求

许可证

此项目采用MIT许可证授权。