apex-freen/apex-mcp-bridge

[Screenshot: Admin Dashboard — to be added]

**Apex MCP Bridge** 是一个 AI 原生的边缘 hub，作为 AI agent 访问物理世界的**核心控制层**。它将所有兼容 MCP 的 agent 客户端（TRAE、WorkBuddy、Codex、Claude Code、Cursor 等）连接在一端，将所有物理设备和网络服务（灯光、音箱、机器狗、NAS、打印机、数据库、ERP 等）连接在另一端——充当**统一的 MCP 智能控制器**。 通过 Docker 部署，它可以在任何支持 Docker 的设备（NAS、服务器、树莓派、PC）上运行，实现零硬件依赖。 ## 💎 核心亮点 | 🔐 五层安全 | 🎯 1 个统一 MCP 入口 | 🚀 0 硬件依赖 | |:---:|:---:|:---:| | Token + 权限 + TTL + 防绕过 + 限流 | 所有设备与服务汇聚，agent 只能看到 **1 个工具** | 任何设备上的 Docker — NAS、树莓派、服务器、PC | | AI 看不到的东西，它永远无法触碰 | 恒定的 token 消耗，零幻觉膨胀 | 3 分钟部署，无需硬件 | ## 🧠 核心理念：大脑与手，零信任架构 **一句话概括：Agent 思考，Bridge 执行，人类授权。** | 角色 | 职责 | 拥有 | 不拥有 | |:---:|---|---|---| | 🤖 Agent | 生成意图 | 大脑（推理） | 任何密钥或权限 | | ✋ Bridge | 验证 + 执行 + 审计 | 设备与服务控制权 | 大脑（绝不自行决定） | | 👤 人类 | 定义授权边界 | 最终决策权 | — | ## ✨ 为什么选择 Apex MCP Bridge 2026 年初的“龙虾事件”导致 27 万个 AI agent 实例同时在线——删除电子邮件、泄露隐私，并在公共互联网上被扫描。如果这发生在企业场景中：任何 AI 都能开门、机械臂被未经授权的命令控制、营销 agent 访问研发数据——后果将不堪设想。 Apex MCP Bridge 提供： | 问题 | 解决方案 | |---------|----------| | AI agent 缺乏访问控制 | **五层安全** — token + 权限 + TTL + 防绕过 + 限流 | | N 台设备 + M 个服务 = N+M 个 MCP 工具淹没上下文 | **工具汇聚** — 所有服务汇聚到 **1 个 MCP 入口**，基于 token 的权限过滤 | | 连接设备与服务的门槛高 | **双开源框架** — 硬件 (ESP32-S3/C3) + 插件引擎，通过 AI agent 生成代码 | | 数据隐私与合规担忧 | **纯本地架构** — 数据从不离开局域网，满足 GDPR 要求 | ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ AI Agent Clients │ │ (TRAE · WorkBuddy · Claude Code · Cursor · Codex · ...) │ └─────────────────────────────┬───────────────────────────────────┘ │ MCP Protocol ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Apex MCP Bridge (Rust) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ 5-Layer │ │ Tool │ │ MCP ↔ MQTT / Plugin │ │ │ │ Security │ │ Convergence│ │ Protocol Translation │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Token │ │ Audit │ │ Plugin Engine │ │ │ │ Management │ │ Center │ │ (auto-discovery) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └───────────┬───────────────────────────────┬─────────────────────┘ │ MQTT │ Plugin (stdin/stdout) ▼ ▼ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ IoT Devices │ │ Network Services │ │ (ESP32-S3/C3 · │ │ (NAS · DB · Printer · ERP · │ │ Lights · Speakers · │ │ CRM · WebDAV · FTP · ...) │ │ Robot Dogs · ...) │ │ │ └──────────────────────┘ └──────────────────────────────────┘ ``` ## 🚀 快速开始 本项目基于纯 Docker 部署——所有环境和依赖均打包在镜像中。 ### 端口 | 端口 | 用途 | |---|---| | `8018` | Web 管理面板 + MCP Server endpoint | | `1883` | MQTT 设备接入端口 | ### 前置条件 - 任何支持 Docker 的设备（NAS、服务器、树莓派、PC） - 已安装 Docker & Docker Compose - 确保上述端口可用 - 防火墙允许 `8018/tcp` 和 `1883/tcp` 通信 ### 部署步骤 **第 1 步：准备 docker-compose.yml** 创建一个项目目录，并从仓库根目录复制 `docker-compose.yml`： ``` mkdir -p apex-mcp-bridge && cd apex-mcp-bridge # 复制 docker-compose.yml 到当前目录 ``` **第 2 步：配置 HOST_HOSTNAME（必填）** 编辑 `docker-compose.yml`，找到 `HOST_HOSTNAME` 环境变量，并将其设置为您设备的**局域网 IP** 或**主机名**： ``` environment: - HOST_HOSTNAME=192.168.1.100 # Change to your device LAN IP or hostname ``` **第 3 步：启动** ``` docker compose up -d ``` 等待 1-3 分钟以拉取镜像并启动容器。 ### 访问 打开浏览器并访问：`http://:8018` **默认凭证：** - 用户名：`admin` - 密码：`admin123` 🖼️ **截图占位符**：登录页面及成功登录后的管理面板。 ### 系统设置流程 ``` 1. Create Users → User Management 2. Add Devices/Plugins → Plugin Management + Device Management 3. Issue Tokens → MCP Token Management + MCP Permission Management 4. Connect Agents → MCP Endpoint (http://:8018/mcp) 5. Audit Everything → Audit Center ``` ## 🔌 插件安装 插件可将任何网络服务转换为 MCP 工具。示例：SMB 文件插件。 1. 从插件仓库下载一个插件文件夹： 2. 将插件文件夹复制到 `./data/service-plugins/` 中 3. Bridge 会自动检测并动态加载它——**无需重启** ## 🔧 核心功能 ### 五层安全系统 | 层级 | 机制 | 防御对象 | |-------|-----------|-----------------| | ① Token 认证 | 每个请求都必须携带有效的 token | 未经授权的 agent 甚至无法看到设备列表 | | ② 权限检查 | 与 Token 绑定的细粒度权限（设备/功能级别） | 仅允许控制已授权的设备/功能 | | ③ TTL 过期 | Token 级别的 TTL，秒级撤销 | 被盗用的 token 可以立即失效 | | ④ 防绕过 | 对所有 MCP 请求进行统一的验证通道 | 阻止直接使用设备 ID 构造调用 | | ⑤ 限流 | Token/设备/功能三维节流 | 防止 AI 幻觉循环和暴力探测 | ### 工具汇聚（独特创新） | 维度 | 传统直接 MCP | Apex MCP Bridge | |-----------|------------------------|-----------------| | Agent 可见的工具 | N + M（全部暴露） | **1**（统一入口） | | 每次对话的 token 消耗 | 随设备数量线性增长 | **恒定**（与设备无关） | | 无权限的设备 | 暴露在工具列表中，依赖模型“自律” | **完全不可见** | | 幻觉风险 | 工具越多风险越高 | **大幅降低** | ### 系统模块 | 模块 | 功能 | |--------|-----------| | **审计中心** | 审计统计面板、操作审计日志、授权审计、token 审计 | | **用户管理** | 创建/禁用/删除系统用户 | | **设备管理** | 已注册的 IoT 设备、在线状态、能力列表 | | **插件管理** | 安装/卸载/启用/禁用插件，每个插件 = 一组 MCP 工具 | | **MCP 权限管理** | 将工具/设备绑定到 token，实现细粒度的“谁能做什么”控制 | | **MCP Token 管理** | 创建/续期/撤销具有 TTL 的 agent 访问 token | | **系统设置** | 端口、日志级别、HOST_HOSTNAME 等 | ## 🧩 相关项目 | 项目 | 描述 | 链接 | |---------|-------------|------| | **apex-mcp-bridge** | 核心项目（本仓库） | [GitHub](https://github.com/apex-freen/apex-mcp-bridge) | | **apex-mcp-service-plugins** | 插件生态 — 通过服务能力扩展 Bridge | [GitHub](https://github.com/apex-freen/apex-mcp-service-plugins) | | **apex-mcp-esp32-s3-v6** | 硬件框架 (ESP32-S3) — 开源芯片模板 | [GitHub](https://github.com/apex-freen/apex-mcp-esp32-s3-v6) | | **apex-mcp-esp32-c3-v6** | 硬件框架 (ESP32-C3) — 开源芯片模板 | [GitHub](https://github.com/apex-freen/apex-mcp-esp32-c3-v6) | ## ⚠️ 安全提示 - **初始密码安全**：数据库密码和管理员密码均设为简单的默认值，仅供快速评估使用。**请在首次部署后立即更改以下密码以提高密码复杂度**： - 数据库密码：修改 `docker-compose.yml` 中的 `MARIADB_ROOT_PASSWORD` 和 `MARIADB_PASSWORD`（修改后需重启容器） - 管理员密码：登录管理面板后，在用户管理中更改 `admin` 用户的密码（当前默认为：`admin123`） - **插件安全**：插件会在您的主机上执行任意 Python 代码。请仅安装来自官方仓库或您完全信任的来源的插件。如果您从非官方渠道获取了插件且不理解其代码，**请勿使用**——它可能包含恶意逻辑。 - **网络暴露**：Bridge 专为局域网部署而设计。如需远程访问，请使用 VPN 或安全隧道，而不是将端口直接暴露在互联网上。 ## ❓ 常见问题

问：支持哪些 MCP 客户端？

所有兼容 MCP 的客户端：TRAE、WorkBuddy、Codex、Claude Code、Cursor，以及任何实现了 Model Context Protocol 的客户端。

问：可以在没有 Docker 的情况下运行吗？

Docker 是官方支持并推荐的部署方式。高级用户可以直接进行二进制部署，但这不在官方文档范围内。

问：如何将新服务添加为 MCP 工具？

有两种方式： 1. **插件**：如果已有现成的插件，只需将其复制到 `service_plugins/` 目录中 2. **自定义插件**：使用标准的插件框架，向 AI agent 描述您的服务，它会为您生成插件代码

问：支持哪些硬件设备？

官方支持：带有开源硬件框架模板的 ESP32-S3 和 ESP32-C3。任何支持 MQTT 的设备都可以通过自定义固件进行集成。

问：我的数据会离开局域网吗？

不会。Apex MCP Bridge 采用纯本地架构——所有数据都保留在您的网络中。Bridge 绝不会进行外部通信或上传任何数据。

问：开发插件我需要什么技能？

**极低门槛：基础的 Python + 描述您需求的能力。** 插件框架处理了所有的样板代码——输入 schema、通信协议、错误处理和响应格式。您可以： - **零代码方式**：向 AI agent 描述服务（“我需要一个 WebDAV 插件”），它会为您生成代码 - **基础 Python**：如果 AI 生成的结果需要调整，可以微调现有插件或编写简单的处理程序 - **高级开发**：针对复杂服务进行全面的自定义插件开发 核心技能是知道您想暴露*什么*服务——而框架会处理*如何*去做。

问：插件需要什么版本的 Python？

插件处理器要求 **Python ≥ 3.10**。Docker 镜像自带兼容的 Python runtime，因此如果您通过 Docker 部署，则无需担心此问题。如果在本地开发，请确保您的 Python 版本满足此要求。

问：如何升级到新版本？

``` # 1. 拉取最新镜像 docker-compose pull # 2. 重启容器（保留 volumes 中的所有数据） docker-compose up -d ``` 您的配置、插件、设备、token 和审计日志都存储在 Docker volumes (`./data/`) 中，并且**在升级后会保留**。小版本更新无需迁移步骤。对于大版本升级，请查看发布说明以获取任何特定指示。

问：它能处理多少台设备？性能如何？

单个 Apex MCP Bridge 实例可以轻松处理： - 通过 MQTT 连接的 **100 多台 IoT 设备** - **50 多个活跃插件**（网络服务） - 多个 AI agent 同时发出的**并发 MCP 请求** 其 Rust 核心经过高度优化且轻量化——在正常负载下仅占用约 30-50 MB 的内存。在树莓派 4B 上，它每秒可以处理数百次 MCP 工具调用。对于更大规模的部署（数千台设备），您可以运行多个 Bridge 实例并共享配置。

_{由 Apex MCP Bridge 团队用 ❤️ 构建}

标签：AI智能体, Docker, MCP协议, Rust, 可视化界面, 安全防御评估, 本地部署, 物联网控制, 网络流量审计, 请求拦截, 边缘计算, 逆向工具