# apex-mcp-bridge

**Repository Path**: freen/apex-mcp-bridge

## Basic Information

- **Project Name**: apex-mcp-bridge
- **Description**: Apex MCP Bridge 是 AI 原生边缘 MCP 中控，将本地设备服务+网络服务打包成 1 个 MCP Server 供授权智能体调用。工具收敛降 Token、五重安全零信任、双开源框架（ESP32+插件引擎 MIT）支持 AI 约束式生成。纯本地 Rust 核心，Docker 一键部署。

关键词：MCP、AI Agent、IoT、零信任、工具收敛、ESP32、边缘计算
- **Primary Language**: Docker
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/freen/apex-mcp-bridge
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!--
  ┌──────────────────────────────────────────────────────┐
  │  apex-mcp-bridge — AI 原生边缘 MCP 中控               │
  │  正式文档 (2026-07-31).                               │
  └──────────────────────────────────────────────────────┘
-->

<p align="center">
  <img src="https://img.shields.io/badge/core-apex--mcp--bridge-6c5ce7?style=flat-square" alt="核心项目">
  <img src="https://img.shields.io/badge/version-latest-6c5ce7?style=flat-square" alt="版本">
  <img src="https://img.shields.io/badge/rust--核心-✓-DEA584?logo=rust&style=flat-square" alt="Rust">
  <img src="https://img.shields.io/badge/docker-✓-2496ED?logo=docker&style=flat-square" alt="Docker">
  <img src="https://img.shields.io/badge/MCP-2026.07-6c5ce7?style=flat-square" alt="MCP 协议">
</p>

<p align="center">
  <b>Rust</b> · MCP · MQTT · Docker · Plugin Engine · ESP32
</p>

<p align="center">
  <img src="docs/apex-demo-optimized.gif" alt="Apex MCP Bridge 演示" width="720">
</p>

# Apex MCP Bridge

> **AI 原生边缘 MCP 中控** —— 连接 AI 智能体与物理世界的核心控制层

<div align="center">
<table>
<tr>
<td align="center"><img src="docs/dashboard.png" width="300"><br>💎 数据通览</td>
<td align="center"><img src="docs/operation-audit.png" width="300"><br>📋 操作记录</td>
<td align="center"><img src="docs/authorization-audit.png" width="300"><br>🔐 授权记录</td>
</tr>
<tr>
<td align="center"><img src="docs/token-qrcode.png" width="300"><br>📱 令牌二维码</td>
<td align="center"><img src="docs/plugin-list.png" width="300"><br>🔌 插件管理</td>
<td align="center"><img src="docs/device-list.png" width="300"><br>🖧 设备管理</td>
</tr>
</table>
</div>

> 🌍 **English Documentation**: For English version, see [README.md](./README.md)

**Apex MCP Bridge** 是一个 AI 原生边缘中枢，定位为智能体通向物理世界的 **核心主控层**。它一头连接所有支持 MCP 协议的智能体客户端（TRAE、WorkBuddy、Codex、Claude Code、Cursor 等），一头连接灯光、音响、机械狗、NAS、打印机、数据库、ERP 等所有物理设备和任意网络服务，充当 **MCP 全域智能中控** 的角色。

项目基于 Docker 容器化部署，可运行在 NAS、服务器、树莓派、个人电脑等任意支持 Docker 的设备上，零硬件依赖。

<details>
<summary><b>📋 目录</b></summary>

- [核心亮点](#核心亮点) — 工具收敛、插件框架、五重安全
- [核心理念](#核心理念大脑与手分离零信任架构) — 大脑与手分离，零信任架构
- [为什么选择](#为什么选择-apex-mcp-bridge) — 给开发者的价值
- [系统架构](#系统架构) — 架构图与数据流
- [快速开始](#快速开始) — Docker 部署、配置、访问
- [插件安装与可视化](#插件安装与可视化) — 网络服务 MCP 化、插件 Web 可视化
- [核心功能](#核心功能) — 五重安全、工具收敛、系统模块
- [智能体模块](#智能体模块) — 解耦智能体、大模型对接、智能体对话
- [语音交互与智能硬件终端](#语音交互与智能硬件终端) — ASR/TTS、桌宠指令终端
- [关联项目](#关联项目) — 插件仓库、硬件框架
- [安全提示](#安全提示) — 密码、插件、网络
- [参与贡献](#参与贡献) — 如何贡献代码和插件
- [常见问题](#常见问题) — FAQ

</details>

***

## 💎 核心亮点

|        🎯 工具收敛（降 Token）       |     🔌 插件框架（免造轮子）     |       🔐 五重安全（零信任）      |
| :---------------------------: | :-------------------: | :---------------------: |
| N 设备 + M 服务 → 智能体仅见 **1 个工具** | 硬件 + 插件双开源框架，AI 约束式生成 | 令牌 + 权限 + 时效 + 防绕过 + 限流 |
|      Token 消耗恒定，幻觉风险大幅降低      |  描述需求即出固件/插件，不用从零搭鉴权  |     AI 看不见的东西，永远碰不到     |

> **一句话定位**：工具收敛降成本 + 插件框架提效率 + 零信任保安全 + 内置智能体与语音交互，让 AI 通过单一 MCP 入口安全地控制任意设备、任意服务。

***

## 🧠 核心理念：大脑与手分离，零信任架构

**一句话理解：智能体负责想，Bridge 负责做，人类负责授权。**

> **本质**：Bridge 把你本地的设备服务和网络服务打包成 1 个 MCP Server，用户只需扫二维码接入智能体，即可在授权范围内联动数据和设备。

**举个例子**：你说"想听音乐"——智能体先调用网络服务拿到音乐文件，再调用设备服务让音响播放。全程 MCP 化，安全可控。

|    角色    | 职责           | 有什么      | 没什么        |
| :------: | ------------ | -------- | ---------- |
|  🤖 智能体  | 产生意图         | 大脑（推理）   | 任何密钥与权限    |
| ✋ Bridge | 校验 + 执行 + 审计 | 设备与服务控制权 | 大脑（不会自主决策） |
|   👤 人类  | 定义授权边界       | 最终决策权    | —          |

> **零信任原则**：先校验，后执行，全程留痕。默认不信任任何智能体。

***

## ✨ 为什么选择 Apex MCP Bridge

### 给开发者的价值

| 痛点                                       | Bridge 的解法                                        |
| ---------------------------------------- | ------------------------------------------------- |
| N 设备 + M 服务 = N+M 个 MCP 工具塞满上下文，Token 爆炸 | **工具收敛**：所有服务汇聚到 1 个 MCP 入口，Token 消耗恒定            |
| 每个项目都要重写鉴权、权限、MQTT 协议栈                   | **双开源框架**：硬件（ESP32-S3/C3）+ 插件引擎（MIT），框架约束 + AI 生成 |
| 担心 AI 幻觉导致误操作                            | **五重安全校验**：无权限的设备/功能对智能体完全不可见                     |
| 数据合规顾虑（GDPR）                             | **纯本地架构**：数据不出内网，Rust 核心高性能低占用                    |

> AI 智能体学会了动手，但没人给它装 **安全闸门**。Apex MCP Bridge 就是这道闸门。

2026 年初的"龙虾事件"中，27 万只 AI 智能体同时在线——疯狂删除邮件、泄露隐私、被全网扫描器挨个摸了一遍。如果这发生在企业场景：门禁被任意 AI 一句话打开、机械臂被未授权指令控制、市场部智能体越权读取研发部核心数据——后果不堪设想。

Apex MCP Bridge 提供了：

| 问题                              | 解决方案                                             |
| ------------------------------- | ------------------------------------------------ |
| AI 智能体无访问控制                     | **五重安全校验** —— 令牌 + 权限 + TTL时效 + 防绕过 + 频率限制       |
| N 设备 + M 服务 = N+M 个 MCP 工具塞满上下文 | **工具收敛** —— 所有服务汇聚到 **1 个 MCP 入口**，基于令牌权限过滤      |
| 设备与服务接入门槛极高                     | **双开源框架** —— 硬件（ESP32-S3/C3）+ 插件引擎，通过 AI 智能体生成代码 |
| 数据隐私与合规顾虑                       | **纯本地架构** —— 数据不出内网，满足 GDPR 等隐私合规                |

***

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        AI 智能体客户端                             │
│   (TRAE · WorkBuddy · Claude Code · Cursor · Codex · ...)      │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP 协议
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Apex MCP Bridge (Rust)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ 五重安全     │  │  工具        │  │  MCP ↔ MQTT / 插件      │ │
│  │ 校验体系     │  │  收敛机制    │  │  协议翻译                │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ 令牌        │  │  审计        │  │  插件引擎                │ │
│  │ 管理        │  │  中心        │  │  (自动发现 + 可视化)     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ 智能体模块   │  │ ASR/TTS     │  │  使用中心                │ │
│  │ (DeepSeek   │  │ 语音交互     │  │  (智能体对话 + 插件Web)  │ │
│  │  大模型对接) │  │             │  │                         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└───────────┬───────────────────────────────┬─────────────────────┘
            │ MQTT                          │ 插件 (标准输入输出)
            ▼                               ▼
┌──────────────────────┐      ┌──────────────────────────────────┐
│  物联网设备           │      │  网络服务                        │
│  (ESP32-S3/C3 ·       │      │  (NAS · 数据库 · 打印机 · ERP · │
│   灯光 · 音响 ·        │      │   CRM · WebDAV · FTP ·          │
│   机械狗 · 桌宠终端 · │      │   留言板 · DLNA · ...)         │
│   ...)                │      │                                   │
└──────────────────────┘      └──────────────────────────────────┘
```

***

## 🚀 快速开始

本项目基于纯 Docker 部署，所有环境和依赖都已打包在镜像中。

### 部署方式

| 方式                      | 推荐度     | 说明                               |
| ----------------------- | ------- | -------------------------------- |
| **Docker Compose**      | ⭐ 推荐    | 标准部署方式，直接使用 `docker-compose.yml` |
| **install.sh / ops.sh** | 占位（待优化） | 一键安装 + 运维脚本，暂不推荐使用               |

> `install.sh` 和 `ops.sh` 脚本目前为占位版本，正在优化中，请优先使用下方的 Docker Compose 方式部署。

### 端口说明

| 端口     | 用途                       |
| ------ | ------------------------ |
| `8018` | Web 管理后台 + MCP Server 端点 |
| `1883` | MQTT 设备接入端口              |

### 前置条件

- 任意支持 Docker 的设备（NAS、服务器、树莓派、PC 均可）
- 已安装 Docker 和 Docker Compose
- 确保上述端口未被占用
- 防火墙放行 `8018/tcp` 和 `1883/tcp`

### 部署步骤

**步骤 1：准备 docker-compose.yml**

创建项目目录，从仓库根目录下载 `docker-compose.yml`：

```bash
mkdir -p apex-mcp-bridge && cd apex-mcp-bridge
curl -O https://gitee.com/freen/apex-mcp-bridge/raw/main/docker-compose.yml
```

> **国内用户**：打开 `docker-compose.yml`，找到 `image:` 配置段，注释掉国际镜像行，取消注释阿里云镜像行以加速拉取。同时取消注释 `PIP_INDEX_URL` 行以加速插件依赖安装。

**步骤 2：配置 JWT\_SECRET（必需）**

编辑 `docker-compose.yml`，找到 `JWT_SECRET` 环境变量，设置一个随机密钥：

```yaml
environment:
  - JWT_SECRET=your-random-secret-key-here    # 首次启动前必须配置
```

> ⚠️ **此项必须配置**。用于令牌签发与验证，未配置将导致系统无法正常工作。

**步骤 3：配置 HOST\_HOSTNAME（必需）**

编辑 `docker-compose.yml`，找到 `HOST_HOSTNAME` 环境变量，将其值设置为设备的**局域网 IP** 或 **hostname**：

```yaml
environment:
  - HOST_HOSTNAME=192.168.1.100    # 改成你的设备局域网IP或hostname
```

> ⚠️ **此项必须配置**。系统需要用它来生成 MCP 服务地址和设备注册路由，未配置将导致智能体无法正确连接和设备无法注册。

**步骤 4：启动**

```bash
docker compose up -d
```

等待 1-3 分钟让镜像拉取和容器启动完成。

### 访问

打开浏览器访问：`http://<设备IP>:8018`

**初始账号：**

- 用户名：`admin`
- 密码：`admin123`

> ⚠️ 登录后请立即修改默认密码。

<p align="center">
  <img src="docs/screenshots/login.png" alt="登录页面" width="400">
  <img src="docs/screenshots/dash_board.png" alt="管理后台仪表盘" width="400">
</p>

### 系统使用流程

```
1. 创建用户          → 用户管理
2. 添加设备/插件     → 插件管理 + 设备管理
3. 签发令牌          → MCP 令牌管理 + MCP 权限管理
4. 连接智能体        → MCP 端点 (http://<IP>:8018/mcp) 或 内置智能体对话
5. （可选）配置智能体 → 智能体管理：模型供应商 → 创建智能体 → 绑定令牌
6. （可选）语音交互   → ASR/TTS 供应商配置 → 桌宠指令终端配网
7. 审计所有操作      → 审计中心
```

***

## 🔌 插件安装与可视化

插件将任意网络服务翻译为 MCP 工具。以 SMB 文件插件为例：

1. 从插件仓库下载插件文件夹：<https://gitee.com/freen/apex-mcp-service-plugins>
2. 将插件文件夹复制到 `./data/service-plugins/`
3. 系统自动发现并动态加载——**无需重启**

> **设计理念**：把插件文件夹复制到 `service_plugins/`，系统就会自动检测并加载——无需重启、无需配置、无需注册步骤。

> **真正的威力**：你甚至不需要写一行代码。本项目提供了完整的标准化插件框架——所有方法输入模式、配置模板、标准输入输出通信协议、统一响应格式都已内置。只需把这些模板作为约束交给 AI 智能体，用自然语言描述你想要的服务（打印机插件？数据报表？），智能体就会在框架内生成完整的、即插即用的插件代码。

### 插件可视化

原先插件的调用全部由智能体通过 MCP 协议发起，适合 AI 自动化场景。但很多日常操作（查看文件列表、浏览留言板、控制播放）如果每次都走智能体，既浪费 Token 又不够直观。

**插件可视化功能**解决了这个问题：每个插件可自带 `web_ui/` 目录，在插件管理列表中会出现一个可视化入口按钮，点击即可直接进入插件的 Web 操作页面，对插件内的功能和数据进行直接操作——**无需消耗任何 Token，无需智能体参与**。

<p align="center">
  <img src="docs/screenshots/plugin-visualization-entry.png" alt="插件管理列表中的可视化入口按钮" width="600">
</p>

**当前支持可视化的插件：**

| 插件                        | 可视化页面功能                   |
| ------------------------- | ------------------------- |
| **fnos-smb-file-manager** | 文件浏览、目录创建、文件删除，面包屑导航      |
| **dmc-to-mcp**            | DLNA 设备扫描、媒体库浏览、播放控制、状态查询 |
| **message-board**         | 门店留言管理端 + 大屏轮播展示          |
| **family-message-board**  | 家庭留言看板（大屏/手机均可）           |

***

## 🔧 核心功能

### 五重安全校验体系

| 层级      | 机制                 | 防护目标                   |
| ------- | ------------------ | ---------------------- |
| ① 令牌鉴权  | 每个请求必须携带有效令牌       | 无凭证的智能体连设备列表都看不到       |
| ② 权限校验  | 令牌绑定细粒度权限（设备级/功能级） | 只有被授权的设备/功能才能被控制       |
| ③ 时效校验  | 令牌支持 TTL，秒级撤销      | 令牌泄露后可即时作废             |
| ④ 防绕过检测 | 所有 MCP 请求统一走校验通道   | 知道设备 ID 直接构造调用也会被拦截    |
| ⑤ 频率限制  | 令牌/设备/功能三维度限流      | 防止 AI 幻觉导致的高频循环调用和暴力试探 |

### 工具收敛（核心创新）

| 维度            | 传统 MCP 直连        | Apex MCP Bridge |
| ------------- | ---------------- | --------------- |
| 智能体看到的工具数     | N + M（全部暴露）      | **1**（统一入口）     |
| 每次对话 Token 消耗 | 随设备数线性增长         | **恒定**（与设备数量无关） |
| 无权限设备         | 暴露在工具列表中，靠模型"自律" | **完全不可见**       |
| 幻觉风险          | 工具越多选错概率越高       | **大幅降低**        |

### 系统模块

| 模块           | 功能                                     |
| ------------ | -------------------------------------- |
| **审计中心**     | 审计统计仪表盘、操作审计日志、授权审计、令牌审计               |
| **用户管理**     | 创建/禁用/删除系统用户                           |
| **设备管理**     | 已注册物联网设备、在线状态、能力列表                     |
| **插件管理**     | 安装/卸载/启用/禁用插件，每个插件 = 一组 MCP 工具，支持可视化入口 |
| **MCP 权限管理** | 将工具/设备绑定到令牌，细粒度控制"谁能干什么"               |
| **MCP 令牌管理** | 创建/续期/作废智能体访问令牌，支持 TTL 时效              |
| **智能体管理**    | 模型供应商配置（DeepSeek）、智能体创建、令牌绑定           |
| **ASR 供应商**  | 语音识别供应商配置（阿里云），用于智能硬件语音输入              |
| **TTS 供应商**  | 语音合成供应商配置（阿里云），用于智能硬件语音反馈              |
| **使用中心**     | 智能体对话、插件 Web 可视化操作入口                   |
| **系统设置**     | 端口、日志级别、HOST\_HOSTNAME 等               |

***

## 🤖 智能体模块

Apex MCP Bridge 新增了**解耦的智能体模块**，让系统不再只是被动等待外部智能体调用，而是内置了完整的智能体能力——自带大脑，自主决策。

### 大模型对接

目前已对接 **DeepSeek** 大模型。配置流程如下：

```
管理后台 → 智能体管理 → 模型管理 → 配置模型供应商 DeepSeek 的 API Key
```

> 🔗 **配置演示**：_(预留演示链接地址)_

### 智能体创建与令牌绑定

配置好模型供应商后，即可创建智能体。创建流程：

1. **创建智能体**：进入 `管理后台 → 智能体管理 → 智能体列表`，新增一个智能体
2. **发牌子（绑定令牌）**：将 `MCP 令牌管理` 中已配置好的 MCP Server 令牌绑定给该智能体
   - 这一步相当于给智能体"发牌子"——智能体获得了该令牌下被授权的所有 MCP 工具和设备权限
3. **开始对话**：进入 `使用中心 → 智能体对话`，即可与该智能体进行对话

> 智能体通过绑定的令牌，自动继承令牌权限范围内的所有设备和服务能力。令牌权限的变更会实时影响智能体的可用工具范围——与外部智能体走同一套零信任校验体系，没有任何特权通道。

<p align="center">
  <img src="docs/screenshots/agent-management.png" alt="智能体管理界面 — 模型配置、智能体列表、令牌绑定" width="600">
</p>

<p align="center">
  <img src="docs/screenshots/agent-chat.png" alt="智能体对话界面" width="600">
</p>

> 🔗 **配置演示**：_(预留演示链接地址)_

***

## 🎙️ 语音交互与智能硬件终端

针对桌宠、智能硬件用户，系统新增了\*\*语音识别（ASR）**和**语音合成（TTS）\*\*模块，让智能硬件能够听懂你的话，并反馈执行结果。智能硬件关联的智能体，就是你在智能体模块中创建好的智能体。

### 语音供应商配置

```
管理后台 → 智能体管理 → ASR 供应商 / TTS 供应商 → 新增供应商
```

目前已对接 **阿里云**语音服务供应商。

> 🔗 **配置演示**：_(预留演示链接地址)_

### 桌宠指令终端

目前桌宠的指令终端是市面上常见的基于 **ESP32-C3** 的机械狗，直接烧录固件 bin 文件即可使用。

🖼️ **图片占位**：ESP32-C3 机械狗实物图

<!-- 替换为：<img src="docs/screenshots/esp32-c3-robot-dog.png" alt="ESP32-C3 机械狗" width="400"> -->

#### 配网流程

烧录固件后，进行简单的配网：

1. **设备启动**：如果没有网络，设备会自动开启 **AP 模式**
2. **连接热点**：手机连上设备发出的 WiFi 热点
3. **登录配网页面**：浏览器输入 `192.168.4.1`
4. **输入初始密码**：`apex123`
5. **配置内容**：
   - MCP Bridge 的服务地址
   - 网络配置（WiFi 名称和密码）
   - **Token 配置**（最关键）——此 Token 就是你的智能体 MCP Server 中配置的令牌

> 带上这个 Token，这台设备就成为你的**专用私人指令终端 + 桌宠设备**。设备通过 Token 关联到对应的智能体，语音输入经 ASR 转文字后交给智能体处理，智能体调用授权范围内的 MCP 工具执行操作，执行结果经 TTS 合成语音后通过设备扬声器反馈。

<p align="center">
  <img src="docs/screenshots/device-ap-config.png" alt="设备配网页面 — 服务地址、网络配置、Token 配置" width="500">
</p>

***

## 🧩 关联项目

| 项目                           | 说明                     | 链接                                                        |
| ---------------------------- | ---------------------- | --------------------------------------------------------- |
| **apex-mcp-bridge**          | 核心项目（本仓库）              | [Gitee](https://gitee.com/freen/apex-mcp-bridge)          |
| **apex-mcp-service-plugins** | 插件生态——扩展 Bridge 的服务能力  | [Gitee](https://gitee.com/freen/apex-mcp-service-plugins) |
| **apex-mcp-esp32-s3-v6**     | 硬件框架（ESP32-S3）——开源芯片模板 | [Gitee](https://gitee.com/freen/apex-mcp-esp32-s3-v6)     |
| **apex-mcp-esp32-c3-v6**     | 硬件框架（ESP32-C3）——开源芯片模板 | [Gitee](https://gitee.com/freen/apex-mcp-esp32-c3-v6)     |

***

## ⚠️ 安全提示

- **初始密码安全**：初始部署的数据库密码和管理员密码都设置为简单默认值，仅用于快速体验。**请务必在首次部署后立即修改以下密码，提升密码复杂度**：
  - 数据库密码：修改 `docker-compose.yml` 中的 `MARIADB_ROOT_PASSWORD` 和 `MARIADB_PASSWORD`（修改后重启容器生效）
  - 管理员密码：登录管理后台后，在用户管理中修改 `admin` 用户的密码（当前默认 `admin123`）
- **插件安全**：插件在宿主机上执行任意 Python 代码。只安装来自官方仓库或您完全信任的来源的插件。如果您从非官方渠道获取了一个插件且不理解其代码，**切勿使用**——它可能包含危及系统或数据的恶意逻辑。
- **网络暴露**：Bridge 设计为局域网部署。如果需要远程访问，请使用 VPN 或安全隧道，而非直接将端口暴露到公网。

***

## 🤝 参与贡献

欢迎并感谢任何形式的贡献！每一份帮助都很重要，我们也会始终给予您应有的荣誉。

### 如何贡献？

| 贡献类型       | 方式                                                                          |
| ---------- | --------------------------------------------------------------------------- |
| **报告 Bug** | 提交 Issue，附清晰的复现步骤、环境信息、期望与实际行为对比                                            |
| **建议功能**   | 提交 Issue，描述功能、使用场景、以及为什么它有价值                                                |
| **编写插件**   | 使用插件框架构建新的服务插件，提交到 [插件仓库](https://gitee.com/freen/apex-mcp-service-plugins) |
| **硬件支持**   | 使用硬件框架模板为新芯片/新设备添加支持                                                        |
| **文档改进**   | 修正错误、澄清章节、补充示例、翻译为其他语言                                                      |
| **代码贡献**   | 修复 Bug、实现新功能、提升性能——参考下方工作流程                                                 |

### 开发工作流程

1. **Fork** 本仓库
2. **克隆** 您的 Fork：`git clone https://gitee.com/<你的用户名>/apex-mcp-bridge.git`
3. **创建** 功能分支：`git checkout -b feature/amazing-feature`
4. **编写** 您的改动
5. **提交** 清晰的说明：`git commit -m 'feat: add amazing feature'`
6. **推送** 到分支：`git push origin feature/amazing-feature`
7. **发起** Pull Request

### 插件开发

最容易的贡献方式是构建插件。您不需要深入了解核心代码库——只需遵循插件框架：

1. 从 [apex-mcp-service-plugins](https://gitee.com/freen/apex-mcp-service-plugins) 复制参考插件结构
2. 向 AI 智能体描述您的目标服务（例如"一个支持 CUPS 的打印机插件"）
3. 智能体在框架约束内生成插件代码
4. 本地测试通过后，向插件仓库提交 PR

### 社区

- 如果本项目对您有帮助，请给仓库点个 Star
- 在讨论区分享您的使用场景和插件
- 通过回答 Issue 帮助其他用户

***

## ❓ 常见问题

<details>
<summary><b>Q：支持哪些 MCP 客户端？</b></summary>

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

</details>

<details>
<summary><b>Q：不使用 Docker 能运行吗？</b></summary>

Docker 是官方支持和推荐的部署方式。直接二进制部署对于高级用户是可行的，但没有官方文档。

</details>

<details>
<summary><b>Q：如何将新的服务作为 MCP 工具接入？</b></summary>

两种方式：

1. **插件**：如果已有现成插件，直接复制到 `service_plugins/` 即可
2. **自定义插件**：使用标准插件框架，向 AI 智能体描述您的服务，它会为您生成插件代码

</details>

<details>
<summary><b>Q：支持哪些硬件设备？</b></summary>

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

</details>

<details>
<summary><b>Q：我的数据会离开局域网吗？</b></summary>

不会。Apex MCP Bridge 采用纯本地架构——所有数据都保留在您的网络中。Bridge 从不回传或上传任何数据。

</details>

<details>
<summary><b>Q：插件开发需要什么技能？</b></summary>

**最低要求：基础 Python + 描述需求的能力。**

插件框架处理了所有样板代码——输入模式、通信协议、错误处理、响应格式。您可以：

- **零代码方式**：向 AI 智能体描述服务（"我需要一个 WebDAV 插件"），它会生成代码
- **基础 Python**：如果 AI 输出需要微调，可以修改现有插件或编写简单处理器
- **高级方式**：为复杂服务进行完整的自定义插件开发

核心技能是知道您想要**暴露什么**服务——框架处理**如何暴露**。

</details>

<details>
<summary><b>Q：插件需要什么 Python 版本？</b></summary>

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

</details>

<details>
<summary><b>Q：如何升级到新版本？</b></summary>

```bash
# 1. 拉取最新镜像
docker-compose pull

# 2. 重启容器（保留数据卷中的所有数据）
docker-compose up -d
```

您的配置、插件、设备、令牌和审计日志都存储在 Docker 数据卷（`./data/`）中，**跨升级持久保留**。小版本更新无需迁移步骤。大版本升级请查阅发版说明中的具体指引。

</details>

<details>
<summary><b>Q：能支持多少设备？性能如何？</b></summary>

单台 Apex MCP Bridge 实例可轻松处理：

- **100+ 台已连接物联网设备**（通过 MQTT）
- **50+ 个活跃插件**（网络服务）
- **多智能体并发 MCP 请求**

Rust 核心经过高度优化且非常轻量——正常负载下仅使用约 30-50 MB 内存。在树莓派 4B 上，每秒可处理数百次 MCP 工具调用。对于更大规模的部署（数千台设备），您可以运行多台 Bridge 实例共享配置。

</details>

***

<p align="center">
  <sub>由 Apex MCP Bridge 团队用 ❤️ 打造</sub>
</p>