target_docs/solution_design.md

# 解决方案设计

## 1. 架构概述

本解决方案将采用基于 FastAPI 的微服务架构，实现一个统一的 MCP 服务入口。该服务将作为 ASGI 应用程序运行，并通过 `app.mount` 机制将多个独立的 MCP 应用程序挂载到不同的 URL 路径下。

```mermaid
graph TD
    A[客户端] --> B(HTTP 请求)
    B --> C[FastAPI 主服务 (端口 7860)]
    C -- /app01/sse --> D[App01 MCP 应用]
    C -- /app02/sse --> E[App02 MCP 应用]
    C -- /tasks/sse --> F[Tasks MCP 应用]
    D --> G[App01 工具/资源]
    E --> H[App02 工具/资源]
    F --> I[Tasks 工具/资源 (例如: add_task)]
    I --> J[Supabase 数据库]
```

## 2. 核心组件

### 2.1. FastAPI 主服务 (`app.py`)

*   **职责:** 作为所有 MCP 应用程序的统一入口点，处理传入的 HTTP 请求，并将请求路由到相应的 MCP 应用程序。
*   **实现细节:**
    *   使用 `FastAPI` 实例作为主应用。
    *   通过 `from apps.app_name import AppName` 导入各个 MCP 应用程序类。
    *   实例化每个 MCP 应用程序：`app_instance = AppName()`。
    *   使用 `app.mount("/app_name", app=app_instance.mcp.sse_app())` 将每个 MCP 应用程序的 SSE 端点挂载到指定的 URL 路径。
    *   通过 `uvicorn app:app --host 0.0.0.0 --port 7860` 命令启动服务。

### 2.2. MCP 应用程序 (`apps/app_name.py`)

*   **职责:** 每个文件代表一个独立的 MCP 应用程序，负责定义和管理其自身的工具和资源。
*   **实现细节:**
    *   每个应用程序类（例如 `App01`, `App02`, `Tasks`）将包含一个 `FastMCP` 实例。
    *   工具和资源通过 `FastMCP` 实例的装饰器（例如 `@mcp.tool()`, `@mcp.resource()`) 进行注册。
    *   通过 `mcp.sse_app()` 方法暴露 SSE 端点，供 FastAPI 主服务挂载。

## 3. 数据流

1.  客户端向 `http://localhost:7860/app_name/sse` 发送 HTTP 请求。
2.  FastAPI 主服务接收请求，并根据 URL 路径将其路由到相应的 MCP 应用程序。
3.  MCP 应用程序处理请求，执行相应的工具或访问资源。
4.  如果涉及数据库操作（例如 `airs_tasks` 服务），则与 Supabase 数据库进行交互。
5.  MCP 应用程序通过 SSE 将结果流式传输回客户端。

## 4. 部署方案

*   **本地开发:**
    *   安装 `requirements.txt` 中列出的所有依赖。
    *   激活 `learning` conda 环境。
    *   运行 `uvicorn app:app --host 0.0.0.0 --port 7860` 启动服务。
*   **Docker 部署:**
    *   提供 `Dockerfile`，包含 Python 环境设置和依赖安装。
    *   将 `app.py` 和 `apps/` 目录复制到容器中。
    *   容器启动命令设置为运行 `uvicorn`。

## 5. 风险与挑战

*   **性能瓶颈:** 随着 MCP 应用程序数量和并发请求的增加，可能会出现性能瓶颈。需要进行性能测试和优化。
*   **错误处理:** 需要健壮的错误处理机制，以确保服务在单个 MCP 应用程序出现问题时仍能保持稳定。
*   **安全性:** 生产环境中需要更严格的安全措施，例如身份验证和授权。