paper-burner/js/chatbot/mcp

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 中心，显著扩展了功能，但这需要用户运行一个独立的本地应用程序。