MCP-Codex: Model Context Protocol Tool Orchestration

MCP-Codex：模型上下文协议工具编排

免责声明：Cloudflare 发布了一项类似服务，解决了许多相同的问题，因此本项目已停止维护。我分享此代码库，是为了将其作为 MCP 编排架构的学习资源和示例。虽然不再积极开发，但相关概念和实现对于对 AI 工具编排感兴趣的人来说仍可能有价值。请在此查看 Cloudflare 全新的 Remote MCP 服务及其博客公告：https://blog.cloudflare.com/remote-model-context-protocol-servers-mcp/

一项用于编排模型上下文协议（MCP）服务的服务，可让 AI 助手动态发现并使用工具，而无需重启。它由“The Librarian”驱动——一个能够理解用户需求并为其连接最合适工具的智能 Agent。

概述

MCP-Codex 解决了模型上下文协议生态系统中的一个核心问题：添加新工具时需要重启 AI 助手。它通过中央服务实现动态工具发现和执行，让 AI 助手能够按需使用任何兼容的 MCP 工具。

The Librarian：智能工具发现

MCP-Codex 的核心是“The Librarian”——一个旨在理解用户需求并为其连接合适工具的智能 Agent。The Librarian 作为一个 Agentic RAG（检索增强生成）系统，具备以下能力：

• 多向量知识库：为行业知识和内部文档分别设立向量数据库
• MCP 仓库感知能力：深入了解整个生态系统中可用的 MCP 工具
• 即时工具安装：能够在需要之前按需安装工具
• 上下文感知推荐：利用用户查询的完整上下文，识别最合适的工具
• 无缝集成：处理工具发现、安装和执行的所有细节

The Librarian 实际上充当了用户意图与技术能力之间的通用适配器，减轻用户和 AI 助手在选择工具时的认知负担。

问题

模型上下文协议（MCP）是一项强大的标准，可将 AI 助手连接到外部工具和数据源。然而，传统 MCP 实现存在一个明显局限：

• 静态配置：工具必须在启动时配置；每当需要新功能时，都必须重启
• 仅限本地运行：工具通常与助手运行在同一台机器上
• 发现能力有限：助手没有标准化的方式来发现可用工具
• 认知负担较重：用户必须确切知道某项任务需要哪个工具

解决方案

MCP-Codex 为 AI 助手与更广泛的 MCP 生态系统搭建桥梁，提供以下功能：

1. 智能工具发现：The Librarian 服务分析用户意图并推荐最合适的工具
2. 动态工具管理：可按需安装、配置和执行工具
3. 远程执行：工具可在任何位置运行，而不局限于本地机器
4. 集中管理：无需重启助手，即可添加、更新或移除工具
5. 标准化协议：提供与任意 MCP 工具交互的一致接口

架构

本项目由三个主要组件构成：

1. Codex 服务（codex-serv.py）：管理工具发现和调用的核心执行服务
2. Librarian 服务（计划中）：AI 驱动的工具推荐系统
3. MCP 客户端（mcp-codex.py）：供 AI 助手使用的兼容 MCP 接口

工作原理

1. AI 助手连接到 MCP-Codex 客户端
2. 客户端提供两个主要工具：search 和 call_tool
3. 助手可以使用自然语言搜索所需功能
4. 确定工具后，可以通过标准化调用来执行
5. Codex 服务负责实际执行工具并返回结果

组件

Codex 服务

中央编排服务，负责：

• 管理可用 MCP 工具的注册表
• 处理工具执行请求
• 将请求路由到相应的工具子进程
• 管理工具生命周期

MCP 客户端

符合 MCP 规范的接口，使任何兼容 MCP 的助手都可以：

• 连接到 Codex 生态系统
• 搜索可用工具
• 通过标准化接口执行工具

随附工具示例

此代码库包含多个 MCP 工具示例：

• StockFlow：金融数据和股票市场分析工具
• OptionsFlow：期权交易分析和策略评估
• CodeSavant：代码管理、编辑和执行工具
• StockScreen：股票筛选和过滤功能

安装

先决条件

• Python 3.10+
• 所需的 Python 软件包（参见 requirements.txt）

设置

1. 克隆代码库：

git clone https://github.com/your-username/mcp-codex.git
cd mcp-codex

2. 安装依赖项：

pip install -r requirements.txt

3. 创建所需目录：

mkdir -p config data logs tools

4. 配置环境：

cp .env.example .env
# Edit .env with your configuration

使用方法

启动 Codex 服务

python codex-serv.py

启动 MCP 客户端

python mcp-codex.py

与 Claude Desktop 搭配使用

1. 在 Claude Desktop 中安装 MCP 客户端：

mcp install mcp-codex.py

2. 客户端将注册两个工具：

   • search：查找与你的任务相关的工具
   • call_tool：执行已找到的工具

3. 在 Claude 中的用法示例：

I need to analyze stock data for Apple. Can you help me find the right tool?

路线图

该项目原计划包含多个完整实现的组件：

Librarian（深入介绍）

Librarian 的设想是一个复杂的 AI 驱动工具编排系统，能够：

• 充当 Agentic RAG 系统：结合检索能力与生成式智能
• 维护多个知识源：
  • 行业知识向量数据库（通用技术信息）
  • 内部文档向量数据库（特定工具的功能）
  • 实时 MCP 仓库索引（生态系统中的可用工具）
• 执行复杂的工具选择逻辑：
  • 分析用户查询，理解其深层意图
  • 将意图与所需功能相匹配
  • 在整个 MCP 生态系统中识别最合适的工具
  • 考虑工具兼容性、性能和可靠性
• 提供即时工具管理：
  • 检测所需工具是否尚未安装
  • 自动从仓库安装所需工具
  • 根据具体任务适当配置工具
  • 在执行前确认安装成功
• 管理完整的执行生命周期：
  • 为工具准备适当的上下文
  • 监控执行进度
  • 管理错误处理和恢复
  • 以最实用的格式提供结果
• 持续学习和改进：
  • 跟踪工具的性能和可靠性
  • 从用户反馈和纠正中学习
  • 根据历史成功情况改进推荐
  • 适应新的工具和功能

其他计划功能

• 用户身份验证和授权
• 工具沙箱隔离，保障安全
• 支持云部署
• 工具版本管理和兼容性检查
• 性能监控和分析

文档

工具注册表配置

工具在 config/codex.yaml 文件中定义，结构如下：

tools:
  - name: tool_name
    description: Tool description
    server: path/to/tool/server.py
    methods:
      - method_name
    schemas:
      method_name:
        type: object
        properties:
          # Parameter definitions

API 端点

Codex 服务提供以下 REST 端点：

• /health：健康检查端点
• /search：搜索与查询匹配的工具
• /call_tool：执行特定工具方法
• /reload：重新加载工具配置

本项目的缘由

创建本项目是为了解决当前 AI 工具生态系统中的若干局限：

1. 实现真正的 Agent 能力：让 AI 助手能够根据用户需求动态发现并使用工具
2. 降低运维复杂性：添加新能力时，无需重启 AI 服务
3. 集中管理工具：提供统一的工具部署和更新控制入口
4. 标准化工具交互：为工具发现和执行创建一致的接口
5. 支持远程执行：让工具可以在任何地方运行，而不仅限于本地机器

遗憾的是，Cloudflare 最近发布了类似功能，使本项目的部分内容变得多余。不过，该代码库仍能为 MCP 编排和动态工具发现提供有价值的参考。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Model Context Protocol 提供灵感并设计核心协议
• 感谢开源 MCP 社区作出的宝贵贡献