omnibot (Coldxiangyu163)

🤖 OmniBot

MCP-native AI Agent Framework — plug any MCP server, ship an agent in minutes.

Quick Start • Architecture • Features • Configuration • Comparison • Contributing

______________________________________________________________________

什么是OmniBot？

OmniBot是一个 轻量级AI代理框架 围绕 模型上下文协议（MCP）。您可以在JSON配置中声明MCP服务器，而不是硬编码工具集成——OmniBot会自动发现它们的工具，并让您的代理在零代码更改的情况下使用它们。

将MCP视为 用于AI工具的USB-COmniBot是一款支持任何USB-C设备的笔记本电脑。

______________________________________________________________________

建筑

                          ┌──────────────────────────────────────────────┐
                          │                  OmniBot                     │
                          │                                              │
┌──────────┐   REST/WS    │  ┌────────────┐    ┌──────────────────────┐  │
│  Web UI  │─────────────▶│  │  FastAPI    │───▶│   Agent Engine       │  │
│  (Chat   │◀─────────────│  │  Gateway    │◀───│                      │  │
│  Widget) │              │  └────────────┘    │  ┌────────────────┐  │  │
└──────────┘              │                    │  │  ReAct Loop    │  │  │
                          │                    │  │  ┌──────────┐  │  │  │
┌──────────┐              │                    │  │  │ Reason   │  │  │  │
│  cURL /  │──────────────│                    │  │  │    ↓     │  │  │  │
│  API     │              │                    │  │  │ Act      │  │  │  │
│  Client  │              │                    │  │  │    ↓     │  │  │  │
└──────────┘              │                    │  │  │ Observe  │  │  │  │
                          │                    │  │  └──────────┘  │  │  │
                          │                    │  └────────────────┘  │  │
                          │                    └──────────┬───────────┘  │
                          │                               │              │
                          │              ┌────────────────┼──────────┐  │
                          │              │   Unified Tool Registry    │  │
                          │              └──┬─────────┬──────────┬───┘  │
                          │                 │         │          │      │
                          └─────────────────┼─────────┼──────────┼──────┘
                                            │         │          │
                          ┌─────────────────┼─────────┼──────────┼──────┐
                          │   MCP Servers   │         │          │      │
                          │                 ▼         ▼          ▼      │
                          │  ┌───────────┐ ┌────────┐ ┌──────────────┐ │
                          │  │filesystem │ │ fetch  │ │   github     │ │
                          │  └───────────┘ └────────┘ └──────────────┘ │
                          │  ┌───────────┐ ┌────────┐ ┌──────────────┐ │
                          │  │ postgres  │ │sqlite  │ │  playwright  │ │
                          │  └───────────┘ └────────┘ └──────────────┘ │
                          └─────────────────────────────────────────────┘

                          ┌─────────────────────────────────────────────┐
                          │   LLM Providers                             │
                          │   ┌──────────┐  ┌───────────┐  ┌────────┐  │
                          │   │  OpenAI  │  │ Anthropic │  │ More.. │  │
                          │   │ GPT-4o   │  │  Claude   │  │        │  │
                          │   └──────────┘  └───────────┘  └────────┘  │
                          └─────────────────────────────────────────────┘

______________________________________________________________________

核心功能

🔌 MCP客户端（一级）

OmniBot以MCP为母语。在中声明任何与MCP兼容的服务器 omnibot.json 它可以立即作为代理工具使用——无需代码，无需适配器，无需胶水。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

🧠 重新激活代理循环

A内置 理由→ Act → 观察 循环驱动代理。LLM决定调用哪些工具，解释结果，并不断迭代，直到得到完整的答案——最多 MAX_AGENT_ITERATIONS 回合。

🗂️ 统一工具注册表

MCP工具和原生Python工具并排存在一个注册表中。代理不在乎工具来自哪里，它只是选择了正确的工具。

from app.core.engine import engine

async def get_weather(city: str) -> str:
    return f"Weather in {city}: 22°C, sunny"

engine.registry.register_builtin(
    name="get_weather",
    description="Get current weather for a city",
    input_schema={
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
    handler=get_weather,
)

🤖 多LLM支持

使用单个env变量在LLM提供程序之间切换。目前支持：

📚 RAG（内置代理工具）

RAG不是一个单独的管道——它是代理在需要搜索您的知识库时可以调用的工具。上传文档，代理决定何时查询。

# Upload a document
curl -X POST http://localhost:8000/api/v1/knowledge \
  -F "file=@company-faq.pdf"

# Agent auto-searches when relevant
curl -X POST http://localhost:8000/api/v1/chat \
  -d '{"text": "What is our refund policy?"}'

______________________________________________________________________

快速开始

通过3个步骤让OmniBot运行：

步骤1：克隆并安装

git clone https://github.com/coldxiangyu163/omnibot.git
cd omnibot
cp .env.example .env          # Add your API keys
pip install -r requirements.txt

步骤2：配置MCP工具

创建 omnibot.json 在项目根目录中（或从模板复制）：

cp omnibot.example.json omnibot.json

编辑它以声明您想要的MCP服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

第三步：跑步

# Development
make dev                       # → http://localhost:8000

# Or with Docker
docker compose up -d           # → http://localhost:8000

就是这样。您的代理已经上线，所有已声明的MCP工具都已自动发现并准备就绪。

试试看

# Simple chat
curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"text": "List all files in the data directory"}'

# Full agent mode with step-by-step details
curl -X POST http://localhost:8000/api/v1/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Fetch https://news.ycombinator.com and summarize the top 3 stories"}'

# List all available tools (MCP + built-in)
curl http://localhost:8000/api/v1/tools

______________________________________________________________________

运作原理

OmniBot使用 ReAct（Reason+Act）代理循环:

User: "What's in my docs folder?"
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Agent Step 1                                        │
│   Think:  "I should list the directory"             │
│   Act:    filesystem.list_directory(path="./docs")  │
│   Result: ["report.pdf", "notes.md", "data.csv"]   │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ Agent Step 2                                        │
│   Think:  "I have the file list, I can respond"     │
│   Response: "Your docs folder contains 3 files:     │
│              report.pdf, notes.md, and data.csv"    │
└─────────────────────────────────────────────────────┘

代理不断循环（最多 MAX_AGENT_ITERATIONS)直到它有足够的信息给出最终答案。

______________________________________________________________________

配置

环境变量

MCP服务器配置(omnibot.json)

每个条目下 mcpServers 定义工具提供者：

{
  "mcpServers": {
    "": {
      "command": "",
      "args": ["", ""],
      "env": {
        "": ""
      }
    }
  }
}

OmniBot通过stdio连接到每台服务器，发现其工具，并在启动时将其注册到统一的工具注册表中。

______________________________________________________________________

比较

OmniBot的最佳选择：你想要一个生产就绪的代理，它可以使用任何MCP工具，只需最少的设置，而无需引入庞大的框架。

______________________________________________________________________

项目结构

omnibot/
├── app/
│   ├── main.py                # FastAPI entry point + lifespan
│   ├── config.py              # Settings & env loading
│   ├── core/
│   │   ├── engine.py          # AgentEngine — the orchestrator
│   │   ├── agent/
│   │   │   └── loop.py        # ReAct agent loop implementation
│   │   ├── mcp/
│   │   │   ├── client.py      # MCP stdio client
│   │   │   └── registry.py    # Unified tool registry (MCP + built-in)
│   │   ├── llm/               # LLM providers (OpenAI, Anthropic)
│   │   └── rag/               # RAG pipeline (vector search tool)
│   ├── api/v1/                # REST API routes
│   ├── channels/              # WebSocket, future: Slack / Telegram
│   └── schemas/               # Pydantic request/response models
├── examples/                  # Quickstart & usage examples
├── static/widget/             # Embeddable web chat widget
├── omnibot.example.json       # MCP config template
├── docker-compose.yml         # One-click Docker deployment
├── Makefile                   # Dev commands
├── requirements.txt           # Python dependencies
└── tests/                     # Test suite

______________________________________________________________________

兼容的MCP服务器

任何兼容MCP的服务器都可以开箱即用。热门选择：

浏览完整目录 MCP服务器.

______________________________________________________________________

路线图

• \[x\] MCP客户端（stdio传输）
• \[x\] 使用工具调用重新激活代理循环
• \[x\] OpenAI+人工智能函数调用
• \[x\] 统一工具注册表（MCP+内置）
• \[x\] RAG作为内置代理工具
• \[x\] REST API+WebSocket
• \[x\] 可嵌入的网络聊天小部件
• \[\]MCP SSE/流式HTTP传输
• \[\]流式响应（SSE）
• \[\]对话记忆（多回合上下文）
• \[\]渠道整合（Slack/Telegram/Lark）
• \[\]代理人之间的委托
• \[\]MCP服务器模式（将OmniBot本身暴露为MCP服务器）

______________________________________________________________________

贡献

欢迎投稿！以下是如何开始：

开发设置

git clone https://github.com/coldxiangyu163/omnibot.git
cd omnibot
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
make dev

如何做出贡献

1. 分叉 存储库
2. 创建 特征分支： git checkout -b feat/my-feature
3. 提交 您的更改： git commit -m "feat: add my feature"
4. 推 到你的叉子： git push origin feat/my-feature
5. 打开 拉取请求反对 main

指南

• 遵循现有的代码风格和项目结构
• 尽可能添加新功能的测试
• 使用 约定式提交 用于提交消息
• 让PR保持专注——每个PR都有一个功能或修复
• 如果您的更改影响公共API，请更新文档

报告问题

发现错误或有功能请求？ 打开一个问题 与：

• 对问题或建议的清晰描述
• 复制步骤（针对bug）
• 预期行为与实际行为

______________________________________________________________________

许可证

麻省理工学院 --使用它，修改它，运送它，用它赚钱。

______________________________________________________________________

Built with ❤️ by coldxiangyu