使用说明

项目简介

ThirdBrAIn MCP OpenAI Agent 是一个代理服务，它作为 OpenAI 兼容的语言模型和 Model Context Protocol (MCP) 服务器之间的桥梁。该 Agent 允许 OpenAI 等模型利用 MCP 服务器提供的工具和资源，从而扩展其在数据访问、外部功能调用等方面的能力。通过集成 MCP 服务器，该 Agent 可以为 LLM 提供更丰富的上下文信息和更强大的功能执行能力。

主要功能点

MCP 服务器集成: 能够连接和管理多种 MCP 服务器，例如 Memory, Compute, Fetch 等，从而利用这些服务器提供的资源和工具。
OpenAI 工具桥接: 将 MCP 服务器提供的工具转化为 OpenAI 模型可以理解和调用的函数形式，使得模型能够通过函数调用来使用这些工具。
动态服务器配置: 支持通过聊天命令动态添加、删除、启用和禁用 MCP 服务器的配置，方便灵活地管理和调整工具集。
会话管理: 通过 Supabase 数据库存储和管理对话历史，为 Agent 提供上下文记忆能力。
API 鉴权: 提供 API 密钥 (Bearer Token) 鉴权机制，保障服务安全。
Slash 命令管理: 内置一系列 Slash 命令，用于在聊天交互中直接管理 MCP 服务器配置和查看可用功能。

安装步骤

克隆仓库:

git clone https://github.com/cbruyndoncx/thirdbrain-mcp-openai-agent
cd thirdbrain-mcp-openai-agent

安装 Python 3.12 及依赖: 确保您的系统已安装 Python 3.12 或更高版本，并使用 pip 安装项目依赖。
```
pip install -r requirements.txt
```

配置 Supabase: 在项目根目录下，复制 '.env.example' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入您的 Supabase 项目 URL 和 Service Key。

mv .env.example .env
# 编辑 .env 文件，填入 SUPABASE_URL 和 SUPABASE_SERVICE_KEY

配置 OpenAI 或 DeepSeek API Key (可选): 如果您计划使用 OpenAI 或 DeepSeek 模型，请在 '.env' 文件中配置相应的 API 密钥和模型信息。如果您使用 Ollama 等本地模型，则可能无需 API Key。根据 '.env' 文件中的 'SELECTED' 变量选择配置 OpenAI 或 DeepSeek 的相关参数。
```
# 编辑 .env 文件，根据 SELECTED 变量配置 OpenAI 或 DEEPSEEK 的 URL, API_KEY, MODEL
```
配置 API Bearer Token: 为了保护 API 接口，请在 '.env' 文件中设置 'API_BEARER_TOKEN' 环境变量，用于 API 请求的身份验证。
```
# 编辑 .env 文件，设置 API_BEARER_TOKEN
```
配置 MCP 服务器: 编辑 'mcp_config.json' 文件，配置您希望 Agent 连接的 MCP 服务器信息。您可以配置多个服务器，例如 Memory, Compute, Fetch 等。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令及其参数，以便建立连接。在 'mcp_config.json' 文件中，您可以配置多个 MCP 服务器。以下是一个示例配置，展示了如何配置名为 "memory" 和 "compute" 的 MCP 服务器：

{
  "mcpServers": {
    "memory": {  // 服务器名称：memory
      "command": "docker",  // 启动命令：docker
      "args": ["run", "-i", "--rm", "mcp/memory"],  // 命令参数：运行 mcp/memory docker 镜像
      "env": {},  // 环境变量（可选，此处为空）
      "enable": true // 是否启用该服务器，true 为启用，false 为禁用
    },
    "compute": {  // 服务器名称：compute
      "command": "docker",  // 启动命令：docker
      "args": ["run", "-i", "--rm", "mcp/compute"],  // 命令参数：运行 mcp/compute docker 镜像
      "env": {},  // 环境变量（可选，此处为空）
      "enable": false // 是否启用该服务器，false 为禁用
    }
  }
}

配置参数说明:

'server name': MCP 服务器的名称，用于在客户端中引用。
'command': 启动 MCP 服务器的可执行命令，例如 'docker', 'uvx', 'python3' 等。
'args': 命令的参数列表，用于配置如何启动 MCP 服务器，例如 Docker 镜像名、端口号、配置文件路径等。
'env': 环境变量，用于传递额外的配置信息给 MCP 服务器（可选）。
'enable': 布尔值，指示该 MCP 服务器是否启用。客户端只会连接和使用启用的服务器。

基本使用方法

启动 Agent 服务: 在项目根目录下，运行以下命令启动 Agent 服务。

uvicorn thirdbrain-mcp-openai-agent:app --host 0.0.0.0 --port 8001

验证服务运行: 您可以通过浏览器访问 'http://localhost:8001/api/thirdbrain-hello' 检查 Agent 服务是否成功启动。
集成到 LLM 客户端: 将 Agent 服务作为 MCP 客户端集成到 oTTomator 或其他支持 MCP 协议的 LLM 客户端中。客户端可以通过 API 向 Agent 服务发送用户查询。
使用 Slash 命令: 在聊天界面中，您可以使用 Slash 命令管理 MCP 服务器配置，例如：
- '/list': 列出所有已配置的 MCP 服务器及其启用状态。
- '/functions <server-name>': 列出指定 MCP 服务器提供的所有功能（工具）。
- '/addMcpServer <JSON 配置>': 添加新的 MCP 服务器配置。
- '/disable <server1, server2, ...>': 禁用指定的 MCP 服务器。
- '/enable <server1, server2, ...>': 启用指定的 MCP 服务器。
- '/dropMcpServer <server-name>': 删除指定的 MCP 服务器配置。

示例 Slash 命令

添加 Fetch MCP 服务器:

/addMcpServer { "fetch": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/fetch"] } }

添加 AIDD MCP 服务器:

/addMcpServer { "aidd-ai-software-development-utilities": { "command": "uvx", "args": ["mcp-server-aidd"] } }

关键词