🚀 MCPOmni Connect - 万能MCP服务器网关

MCPOmni Connect 是一个强大、智能的AI代理系统，以及通用的命令行界面（CLI），它不仅仅是一个通往模型上下文协议（MCP）生态系统的网关。通过其 ReAct Agent 模式 和 Orchestrator 模式，它作为一个自主代理运行，能够独立进行推理、决策和复杂任务的执行。它无缝集成多个MCP服务器、AI模型和各种传输协议，形成一个统一的智能界面，可以自主运行或交互式运行。

🚀 新用户？ 从 ⚙️ 配置指南 开始，了解配置文件、传输类型和OAuth行为之间的区别。然后查看 🧪 测试 部分，快速上手。

✨ 主要功能

🤖 智能代理系统

• ReAct Agent 模式
  • 基于推理和行动周期的自主任务执行
  • 无需人工干预的独立决策
  • 通过迭代推理进行高级问题解决
  • 自主导向的工具选择和执行
  • 复杂任务的分解和处理
• Orchestrator Agent 模式
  • 战略性的多步骤任务规划和执行
  • 跨多个MCP服务器的智能协调
  • 动态代理委派和通信
  • 在可能的情况下并行任务执行
  • 具有实时进度监控的复杂工作流管理
• 交互式聊天模式
  • 带有审批工作流的人工参与任务执行
  • 步步指导和解说
  • 用于理解AI决策过程的教育模式

🔌 通用连接

• 多协议支持
  • 对stdio传输的原生支持
  • 用于实时通信的服务器发送事件（SSE）
  • 可高效数据流传输的流式HTTP
  • Docker容器集成
  • NPX包执行
  • 可扩展的传输层，用于未来协议
• 认证支持
  • OAuth 2.0认证流程
  • 带宽令牌认证
  • 自定义头支持
  • 安全凭证管理
• 代理操作模式
  • 在聊天、自主和orchestrator模式之间无缝切换
  • 基于任务复杂性的上下文感知模式选择
  • 跨模式转换的持久状态管理

🧠 AI驱动的智能

• 使用LiteLLM的统一LLM集成
  • 所有AI提供方的单一统一接口
  • 支持来自提供方的100多个模型，包括：
    • OpenAI（GPT-4、GPT-3.5等）
    • Anthropic（Claude 3.5 Sonnet、Claude 3 Haiku等）
    • Google（Gemini Pro、Gemini Flash等）
    • Groq（Llama、Mixtral、Gemma等）
    • DeepSeek（DeepSeek-V3、DeepSeek-Coder等）
    • Azure OpenAI
    • OpenRouter（访问200多个模型）
    • Ollama（本地模型）
  • 简化的配置和降低的复杂性
  • 基于可用能力的动态系统提示
  • 智能上下文管理
  • 自动工具选择和链接
  • 通过自定义ReAct Agent的通用模型支持
    • 处理没有原生函数调用的模型
    • 基于用户请求的动态函数执行
    • 智能工具编排

🔒 安全与隐私

• 明确用户控制
  • 在聊天模式下，所有工具执行都需要用户明确批准
  • 在执行之前清楚地解释工具操作
  • 透明地披露数据访问和使用
• 数据保护
  • 严格的数据访问控制
  • 服务器特定的数据隔离
  • 无未经授权的数据暴露
• 以隐私为先的方法
  • 最少数据收集
  • 用户数据保留在指定服务器上
  • 无需同意，不会跨服务器共享数据
• 安全通信
  • 加密的传输协议
  • 安全的API密钥管理
  • 环境变量保护

💾 内存管理

• Redis驱动的持久化
  • 长期对话内存存储
  • 会话持久化跨重启
  • 可配置的内存保留
  • 通过命令轻松切换内存
• 聊天历史文件存储
  • 将完整的聊天对话保存到文件
  • 从保存的文件加载以前的对话
  • 从你离开的地方继续对话
  • 跨会话的持久聊天历史
  • 基于文件的对话备份和恢复
• 智能上下文管理
  • 自动上下文修剪
  • 相关信息检索
  • 基于内存的响应
  • 跨会话上下文维护

💬 提示管理

• 高级提示处理
  • 跨服务器的动态提示发现
  • 灵活的参数解析（JSON和键值格式）
  • 跨服务器提示协调
  • 智能提示验证
  • 上下文感知提示执行
  • 实时提示响应
  • 支持复杂的嵌套参数
  • 自动类型转换和验证
• 客户端采样支持
  • 从客户端动态采样配置
  • 灵活的LLM响应生成
  • 可定制的采样参数
  • 实时采样调整

🛠️ 工具编排

• 动态工具发现与管理
  • 自动工具能力检测
  • 跨服务器工具协调
  • 基于上下文的智能工具选择
  • 实时工具可用性更新

📦 资源管理

• 通用资源访问
  • 跨服务器资源发现
  • 统一资源寻址
  • 自动资源类型检测
  • 智能内容摘要

🔄 服务器管理

• 高级服务器处理
  • 多个同时服务器连接
  • 自动服务器健康监控
  • 优雅的连接管理
  • 动态能力更新
  • 灵活的认证方法
  • 运行时服务器配置更新

🏗️ 架构

核心组件

MCPOmni Connect
├── 传输层
│   ├── Stdio 传输
│   ├── SSE 传输
│   └── Docker 集成
├── 会话管理
│   ├── 多服务器编排
│   └── 连接生命周期管理
├── 工具管理
│   ├── 动态工具发现
│   ├── 跨服务器工具路由
│   └── 工具执行引擎
└── AI 集成
    ├── LLM 处理
    ├── 上下文管理
    └── 响应生成

🚀 入门指南

前置条件

• Python 3.10+
• LLM API密钥
• UV包管理器（推荐）
• Redis服务器（可选，用于持久化内存）

使用包管理器安装

使用uv（推荐）

uv add mcpomni-connect

使用pip

pip install mcpomni-connect

配置

# 设置环境变量
echo "LLM_API_KEY=your_key_here" > .env
# 可选：配置Redis连接
echo "REDIS_HOST=localhost" >> .env
echo "REDIS_PORT=6379" >> .env
echo "REDIS_DB=0" >> .env
# 在servers_config.json中配置你的服务器

⚙️ 配置指南

配置文件概述

MCPOmni Connect使用两个独立的配置文件用于不同的目的：

1. .env文件 - 环境变量

包含敏感信息，如API密钥和可选设置：

# 必需：你的LLM提供方API密钥
LLM_API_KEY=your_api_key_here

# 可选：Redis配置（用于持久化内存）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

2. servers_config.json - 服务器和代理配置

包含应用程序设置、LLM配置和MCP服务器连接：

{
  "AgentConfig": {
    "tool_call_timeout": 30,
    "max_steps": 15,
    "request_limit": 1000,
    "total_tokens_limit": 100000
  },
  "LLM": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.5,
    "max_tokens": 5000,
    "top_p": 0.7
  },
  "mcpServers": {
    "your-server-name": {
      "transport_type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-package"]
    }
  }
}

🚦 传输类型与认证

MCPOmni Connect支持多种连接到MCP服务器的方式：

1. stdio - 直接进程通信

使用场景：连接作为独立进程运行的本地MCP服务器

{
  "server-name": {
    "transport_type": "stdio",
    "command": "uvx",
    "args": ["mcp-server-package"]
  }
}

• 无需认证
• 无需启动OAuth服务器
• 最常用于本地开发

2. sse - 服务器发送事件

使用场景：使用服务器发送事件连接基于HTTP的MCP服务器

{
  "server-name": {
    "transport_type": "sse",
    "url": "http://your-server.com:4010/sse",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "timeout": 60,
    "sse_read_timeout": 120
  }
}

• 使用带宽令牌或自定义头
• 无需启动OAuth服务器

3. streamable_http - 带可选OAuth的HTTP

使用场景：连接基于HTTP的MCP服务器，带或不带OAuth

不带OAuth（带宽令牌）：

{
  "server-name": {
    "transport_type": "streamable_http",
    "url": "http://your-server.com:4010/mcp",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "timeout": 60
  }
}

• 使用带宽令牌或自定义头
• 无需启动OAuth服务器

带OAuth：

{
  "server-name": {
    "transport_type": "streamable_http",
    "auth": {
      "method": "oauth"
    },
    "url": "http://your-server.com:4010/mcp"
  }
}

• OAuth回调服务器自动在http://localhost:3000启动
• 这是硬编码的，不能更改
• 正确工作所需的OAuth流程

🔐 OAuth服务器行为

重要：在使用OAuth认证时，MCPOmni Connect会自动启动一个OAuth回调服务器。

你会看到：

🖥️  在http://localhost:3000启动回调服务器

关键点：

• 这是正常行为**——不是错误**
• 地址http://localhost:3000是硬编码的，不能更改
• 仅当你在配置中具有"auth": {"method": "oauth"}时，服务器才会启动
• 当应用程序关闭时，服务器会停止
• 仅用于OAuth令牌处理——没有其他用途

当不使用OAuth时：

• 从服务器配置中删除整个"auth"部分
• 使用"headers"和"Authorization": "Bearer token"代替
• 不会启动OAuth服务器

🛠️ 常见问题排查

"连接到服务器失败：会话终止"

可能原因和解决方案：

1. 传输类型错误

   问题：你的服务器期望'stdio'，但你配置了'streamable_http'
   解决方案：检查你的服务器文档以获取正确的传输类型
   

2. OAuth配置不匹配

   问题：你的服务器不支持OAuth，但你具有`"auth": {"method": "oauth"`
   解决方案：完全删除"auth"部分，并使用头代替：
   
   "headers": {
       "Authorization": "Bearer your-token-here"
   }
   

3. 服务器未运行

   问题：在指定URL上的MCP服务器未运行
   解决方案：首先启动你的MCP服务器，然后使用MCPOmni Connect连接
   

4. 错误的URL或端口

   问题：配置中的URL与服务器实际运行的位置不匹配
   解决方案：验证服务器的实际地址和端口
   

"启动回调服务器在http://localhost:3000" - 这是正常的吗？

是的，当：

• 你在任何服务器配置中具有"auth": {"method": "oauth"
• OAuth服务器自动处理令牌
• 你不能也不应该尝试更改这个地址

如果你不想OAuth服务器：

• 从所有服务器配置中删除"auth": {"method": "oauth"
• 使用替代认证方法，如带宽令牌

📋 按用例配置示例

本地开发（stdio）

{
  "mcpServers": {
    "local-tools": {
      "transport_type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-tools"]
    }
  }
}

带令牌的远程服务器

{
  "mcpServers": {
    "remote-api": {
      "transport_type": "streamable_http",
      "url": "http://api.example.com:8080/mcp",
      "headers": {
        "Authorization": "Bearer abc123token"
      }
    }
  }
}

带OAuth的远程服务器

{
  "mcpServers": {
    "oauth-server": {
      "transport_type": "streamable_http",
      "auth": {
        "method": "oauth"
      },
      "url": "http://oauth-server.com:8080/mcp"
    }
  }
}

启动CLI

启动CLI - 确保你的API密钥已导出或创建.env文件：

mcpomni_connect

🧪 测试

运行测试

# 使用详细输出运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_specific_file.py -v

# 运行带覆盖率报告的测试
pytest tests/ --cov=src --cov-report=term-missing

测试结构

tests/
├── unit/           # 单元测试，针对单个组件

开发快速入门

1. 安装

   # 克隆存储库
   git clone https://github.com/Abiorh001/mcp_omni_connect.git
   cd mcp_omni_connect
   
   # 创建并激活虚拟环境
   uv venv
   source .venv/bin/activate
   
   # 安装依赖
   uv sync
   

2. 配置

   # 设置环境变量
   echo "LLM_API_KEY=your_key_here" > .env
   
   # 在servers_config.json中配置你的服务器
   

3. 启动客户端

   uv run run.py
   

   或：

   python run.py
   

⚙️ 配置指南

配置文件概述

MCPOmni Connect使用两个独立的配置文件用于不同的目的：

1. .env文件 - 环境变量

包含敏感信息，如API密钥和可选设置：

# 必需：你的LLM提供方API密钥
LLM_API_KEY=your_api_key_here

# 可选：Redis配置（用于持久化内存）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

2. servers_config.json - 服务器和代理配置

包含应用程序设置、LLM配置和MCP服务器连接：

{
  "AgentConfig": {
    "tool_call_timeout": 30,
    "max_steps": 15,
    "request_limit": 1000,
    "total_tokens_limit": 100000
  },
  "LLM": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.5,
    "max_tokens": 5000,
    "max_context_length": 30000,
    "top_p": 0
  },
  "mcpServers": {
    "your-server-name": {
      "transport_type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-package"]
    }
  }
}

🚦 传输类型与认证

MCPOmni Connect支持多种连接到MCP服务器的方式：

1. stdio - 直接进程通信

使用场景：连接作为独立进程运行的本地MCP服务器

{
  "server-name": {
    "transport_type": "stdio",
    "command": "uvx",
    "args": ["mcp-server-package"]
  }
}

• 无需认证
• 无需启动OAuth服务器
• 最常用于本地开发

2. sse - 服务器发送事件

使用场景：使用服务器发送事件连接基于HTTP的MCP服务器

{
  "server-name": {
    "transport_type": "sse",
    "url": "http://your-server.com:4010/sse",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "timeout": 60,
    "sse_read_timeout": 120
  }
}

• 使用带宽令牌或自定义头
• 无需启动OAuth服务器

3. streamable_http - 带可选OAuth的HTTP

使用场景：连接基于HTTP的MCP服务器，带或不带OAuth

不带OAuth（带宽令牌）：

{
  "server-name": {
    "transport_type": "streamable_http",
    "url": "http://your-server.com:4010/mcp",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "timeout": 60
  }
}

• 使用带宽令牌或自定义头
• 无需启动OAuth服务器

带OAuth：

{
  "server-name": {
    "transport_type": "streamable_http",
    "auth": {
      "method": "oauth"
    },
    "url": "http://your-server.com:4010/mcp"
  }
}

• OAuth回调服务器自动在http://localhost:3000启动
• 这是硬编码的，不能更改
• 正确工作所需的OAuth流程

🔐 OAuth服务器行为

重要：在使用OAuth认证时，MCPOmni Connect会自动启动一个OAuth回调服务器。

你会看到：

🖥️  在http://localhost:3000启动回调服务器

关键点：

• 这是正常行为**——不是错误**
• 地址http://localhost:3000是硬编码的，不能更改
• 仅当你在配置中具有"auth": {"method": "oauth"}时，服务器才会启动
• 当应用程序关闭时，服务器会停止
• 仅用于OAuth令牌处理——没有其他用途

当不使用OAuth时：

• 从服务器配置中删除整个"auth"部分
• 使用"headers"和"Authorization": "Bearer token"代替
• 不会启动OAuth服务器

🛠️ 常见问题排查

常见问题

Error: Could not connect to MCP server

• 检查服务器是否运行
• 验证servers_config.json中的服务器配置
• 确保网络连接
• 检查服务器日志中的错误
• 参见传输类型与认证以获取详细设置

2. API密钥问题

   Error: Invalid API key
   

• 验证.env中API密钥是否正确设置
• 检查API密钥是否具有所需权限
• 确保API密钥针对正确的环境（生产/开发）
• 参见配置文件概述以获取正确设置

3. Redis连接

   Error: Could not connect to Redis
   

• 验证Redis服务器是否运行
• 检查.env中的Redis连接设置
• 确保Redis密码正确（如果配置）

4. 工具执行失败

   Error: Tool execution failed
   

   • 检查连接服务器上的工具可用性
   • 验证工具权限
   • 审查工具参数的正确性

调试模式

启用调试模式以获取详细日志：

/debug

对于额外支持，请：

1. 检查问题页面
2. 查看已关闭的问题以查找类似问题
3. 如果需要，请提供详细信息，打开新问题

🤝 协作

我们欢迎协作！请参阅我们的协作指南了解详情。

📖 文档

完整文档可在以下位置找到：MCPOmni Connect Docs

要在本地构建文档：

./docs.sh serve    # 在http://127.0.0.1:8080启动开发服务器
./docs.sh build    # 构建静态文档

📄 许可证

本项目根据MIT许可证授权 - 请参阅许可证文件了解详情。

📬 联系与支持

• 作者：Abiola Adeshina
• 邮箱：abiolaadedayo1993@gmail.com
• GitHub问题：报告错误

由MCPOmni Connect团队用❤️构建