# MCP (Model Context Protocol) 集成 TODO 与设计笔记

本文档概述了在 Paper Burner Chatbot 中集成 MCP 功能的计划，重点关注客户端能力以及未来对本地后端助手的考量。

## 1. 阶段一：纯前端 MCP 客户端 (基于浏览器)

**目标：** 使聊天机器人能够充当 MCP 客户端，发现并调用那些通过 Web 友好协议暴露的 MCP 服务器工具。

**主要功能点与 TODO：**

-   **[ ] `mcp-client.js` (新文件，位于 `js/chatbot/mcp/`):
    -   **[ ] 连接管理:**
        -   实现 `McpClient.connect(serverUrl)`：建立和管理与 MCP 服务器的连接。初期主要针对暴露 HTTP/SSE 端点的服务器。
        -   允许用户在设置中配置 MCP 服务器 URL。
    -   **[ ] 工具发现 (`listTools`):
        -   实现 `McpClient.listTools()`：根据 MCP 规范向连接的 MCP 服务器发送 `listTools` 请求。
        -   解析响应，获取可用工具列表、描述和输入模式 (input schema)。
        -   存储/缓存当前服务器的可用工具。
    -   **[ ] 工具调用 (`callTool`):
        -   实现 `McpClient.callTool(toolName, toolArgs)`：构造并向 MCP 服务器发送 `callTool` 请求。
        -   处理同步的（HTTP 请求/响应模式）工具调用。
        -   解析工具的响应并返回结果 (例如 `result.content`)。
    -   **[ ] 针对流式工具的 SSE 支持 (如果适用):
        -   调研并实现对通过服务器发送事件 (SSE) 提供流式输出的工具的支持。
        -   使用 `EventSource` API 连接到 MCP 工具提供的 SSE 端点。
        -   处理传入事件并逐步流式传输工具输出，类似于当前处理 LLM 流式响应的方式。
    -   **[ ] 错误处理与健壮性:**
        -   实现针对连接失败、无效服务器响应、工具调用错误等的健壮错误处理机制。
-   **[ ] 与 Agents 集成 (`js/chatbot/agents/`):
    -   **[ ] `LongTextAgent` 和 `RetrievalAgent` 利用 `McpClient`:
        -   Agents 可以发现并调用相关的 MCP 工具（例如，专门的文档分块工具、通过 MCP 暴露的向量搜索工具）来增强其处理能力。
-   **[ ] UI 注意事项 (更新 `js/chatbot/ui/` 模块):
    -   **[ ] 允许用户在设置中添加/管理 MCP 服务器端点。
    -   **[ ] 考虑在界面上展示可用的 MCP 工具，或允许用户根据上下文触发它们。

**认证机制:**

-   **[ ] 初期重点关注无需认证或基于 API 密钥的 MCP 服务器（前提是密钥可以被安全管理或由用户为特定服务器提供）。
-   **[ ] TODO (未来):**调研并实现对 OAuth 2.0 授权码模式（如果合适，也可以是客户端凭证模式）的支持，以应对需要此类认证的 MCP 服务器。这可能涉及到将用户重定向到认证服务器并处理回调。

## 2. 阶段二：本地后端助手/服务器 (未来增强)

**目标：** 引入一个轻量级的本地后端应用程序，以克服浏览器限制并解锁高级功能。这将保持核心聊天机器人在浏览器中的纯粹可用性，本地服务器作为一个可选的增强功能。

**主要功能点与 TODO (由本地后端服务器处理)：**

-   **[ ] 高级数据持久化与恢复:
    -   **[ ] 提供 API 端点，供前端将关键数据（聊天记录、思维导图、设置）保存到本地文件系统（例如 JSON 文件、SQLite）。
    -   **[ ] 提供 API 端点，供前端在 `localStorage` 被清除或不可用时请求数据恢复。
    -   **[ ] (可选) 与用户选择的云存储同步（需要仔细的安全和认证设计）。
-   **[ ] 本地 OCR 与后端转发的 OCR:
    -   **[ ] 提供 API 端点以接收前端的图像数据。
    -   **[ ] 集成本地 OCR 引擎（例如，如果后端是 Python，则通过 Python 环境集成 PP-OCR）。
    -   **[ ] 安全存储在线 OCR 服务（例如 Doc2X）的 API 密钥，并充当前端对这些服务请求的代理。
-   **[ ] 增强的 MCP 功能:
    -   **[ ] MCP 服务器的 Stdio 桥接:
        -   充当桥梁，运行使用 stdio 传输的本地 MCP 服务器（例如 Python 脚本）并与之通信。
        -   通过本地后端，将这些基于 stdio 的 MCP 服务器通过 HTTP/SSE 暴露给前端。
    -   **[ ] 前端作为 MCP 服务器 (通过本地后端代理):
        -   本地后端在特定端口监听来自外部客户端（包括其他浏览器扩展）的 MCP 请求。
        -   将这些 MCP 请求转发给 Paper Burner 前端（例如，通过前端和本地后端之间建立的 WebSockets 或其他持久连接）。
        -   前端（例如，一个新的 `js/chatbot/mcp/frontend-mcp-server-logic.js`）通过调用其内部模块 (`LongTextAgent`, `ChatbotCore`, `toc_logic.js`) 来处理请求。
        -   通过本地后端将响应返回给外部 MCP 客户端。
        -   这使得浏览器扩展可以通过本地后端进行通信，利用其 MCP 代理能力。

**本地后端技术栈 (考量)：**

-   Python (Flask/FastAPI) - 适合 AI/ML 任务，生态成熟。
-   Node.js (Express) - JavaScript 生态系统一致性。
-   Go / Rust - 高性能，单二进制文件部署。

**关于阶段划分的说明：**
阶段一允许聊天机器人立即消费任何可通过 Web 访问的 MCP 服务器提供的工具。阶段二通过利用本地处理能力并充当更通用的 MCP 中心，显著扩展了功能，但这需要用户运行一个独立的本地应用程序。