使用说明（Markdown 格式）

项目简介
- AgentSphere‑AI 是一个基于 MCP 的后端系统集合，旨在向大语言模型（LLM）客户端提供统一的上下文资源、工具执行能力以及可渲染的 Prompt 模板，支持多服务器动态接入、流式响应、HITL 审批以及多租户数据持久化。
主要功能点
- Planner/Agent 两级架构：Planner 负责分析意图并将任务路由到所需的 MCP 服务器；Agent 作为主动执行器，执行选定工具并具备自我修复与循环保护能力。
- 全局 MCP 管理（mcp‑use 驱动）：动态连接 MCP 服务器、发现工具、编排任务。
- 数据持久化：使用 PostgreSQL 进行会话、对话历史、以及 MCP 服务器配置的持久化存储，支持多租户。
- 实时流式响应：对大模型的输出进行逐 token streaming，页面 UI 和命令行都可看到过程。
- HITL（人为在环）审批：对敏感工具调用进行中间拦截与审批，支持按租户配置的模式（denylist/allowlist）。
- 多服务器配置与扩展：提供如 filesystem、Google Drive、GitHub、YouTube 等多种 MCP 服务器的示例实现，便于扩展。
安装步骤
- 1. 安装依赖
  - 通过 Python 依赖管理安装所需包（requirements.txt 等）。
- 1. 数据库准备
  - 启动 PostgreSQL 实例，并配置 DATABASE_URL、租户、以及初始配置信息。
- 1. 启动核心服务
  - 启动基础 MCP 服务与 Planner/Agent 运行环境，例如运行入口脚本（示例中存在 main.py、以及前端 UI 的 streamlit_app.py）。
- 1. 配置 MCP 服务器
  - 将要接入的 MCP 服务器添加到多服务器配置中，用 JSON 配置描述每个服务器的启动命令和参数。
- 1. 运行后端和 UI
  - 启动后端服务后，可使用 Streamlit 提供的前端 UI 进行交互，或通过控制台进行测试。
服务器配置（MCP 客户端不需要理解，仅供参考，便于理解如何向 MCP 客户端注册服务器）
- 配置示例（JSON，说明每个服务器的名称、启动命令与参数）：
- 注：以下为文本描述形式的示例 JSON，请按需在实际使用中填充具体数值与凭据。MCP 客户端需要的是一个包含 server_name、command 与 args 的配置项，用于建立与 MCP 服务端的连接。
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"], "env": {} }, "arxiv": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-arxiv"], "env": {} }, "google-drive": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-google-drive"], "env": { "GOOGLE_DRIVE_TOKEN": "<token若需>", "GOOGLE_DRIVE_OAUTH_CREDENTIALS": "<路径或内容>" } } } }

说明
- server_name：服务器的唯一标识名称，如 filesystem、arxiv、google-drive 等。
- command/args：启动服务器的命令及参数，通常为 npx 和要执行的 MCP 服务端包名。
- env：可选的环境变量，具体凭据请按服务器实现要求填写（示例中包括 Google Drive 等）。
- 该配置通常由 MCP 客户端读取，用以动态连接并在需要时启动相应的 MCP 服务器。
基本使用方法
- 启动与连接：将上述 MCP 服务器配置放入配置文件后，启动后端核心服务；Planner 将根据用户输入决定是否需要调用工具。
- 任务路由与执行：对需要工具的任务，Planner 将规划并调用相应 MCP 服务器的工具，Agent 将执行并 streaming 输出结果。
- HITL 与安全：若触发 HITL，系统会提示审批；审批通过后可以继续该任务。
- 数据持久化：会话和消息通过 PostgreSQL 持久化，支持多租户隔离。
- UI 使用：如果使用 Streamlit UI，可通过前端查看服务器状态、连接的服务器、工具执行过程以及 HITL 审批等。
注意事项
- MCP 服务器的实际启动、路由及工具执行依赖具体实现的包与环境，需确保相关服务可访问并且环境变量正确配置。
- 由于项目包含多个 MCP 服务器实现（如 filesystem、Discord、YouTube、Google Drive 等），请在实际生产前对接入的服务器进行单独测试与安全性验证。
额外信息
- 该仓库包含了 MCP 的核心管理、服务器实现、数据库模型、 migrations、以及若干 MCP 服务器示例，适合作为基于 MCP 的后端服务框架进行二次开发和扩展。

关键词

信息