BLE-MCP 服务器（BLE 模型上下文协议后端）

使用说明（Markdown）

• 项目简介

  • 这是一个基于 MCP 的服务器实现，用于通过AI代理/LLM客户端与实际的BLE设备进行交互。服务器提供BLE相关的资源、工具和规格（Specs），并通过JSON-RPC/stdio对外暴露，便于在撰写设备驱动、自动化测试和智能协作场景中作为后端上下文服务。

• 主要功能点

  • 资源与数据访问：提供BLE设备的读写、发现、MTU、描述符等核心工具，并以结构化JSON形式返回结果。
  • 工具注册与执行：支持插件系统，通过插件扩展新的工具，插件可自定义执行逻辑并注册相应工具与处理器。
  • 协议模板（Specs）管理：支持protocol specs的创建、注册、检索、附着和搜索，使LLM能理解目标设备的BLE协议。
  • 追踪与调试：内置请求追踪，记录每次工具调用的输入/输出，便于调试和审计。
  • 会话与状态管理：在同一MCP会话中缓存连接、订阅、扫描等状态，并实现资源使用的限制控制（连接数、扫描数、订阅数等）。
  • 设备通知与断开告警：通过MCP日志/通知机制，将BLE设备断开、特征通知等事件传达给客户端。

• 安装步骤

  • Python环境要求：Python 3.11+。
  • 安装依赖并直接运行服务（本实现以stdio传输为主，不对外开放HTTP端口）：
    • 通过源码运行：直接以模块执行 ble_mcp_server 入口，或使用已有的脚本/容器执行入口启动。
  • 运行前的准备
    • BLE 运行环境需具备 Bleak 依赖（跨平台的BLE栈）。
    • 如需要无写权限、或启用插件/写入特性，请在启动时设置相应环境变量，如 BLE_MCP_ALLOW_WRITES、BLE_MCP_PLUGINS 等。
  • 启动示例（命令行直接执行，不是客户端代码示例）
    • python -m ble_mcp_server

• 服务器配置（MCP客户端需要的最小配置） 说明：以下JSON配置用于MCP客户端在连接前了解如何启动服务器。服务器名称与启动命令需与仓库信息对应，确保客户端能正确启动并连接到后端。实际使用中客户端不要求包含此配置代码块，仅供参考配置。

{ "server": { "name": "ble-mcp-server", "command": ["python", "-m", "ble_mcp_server"], "args": [], "env": { "BLE_MCP_ALLOW_WRITES": "true", // 允许对BLE特征写操作（需要时开启，避免误写硬件） "BLE_MCP_PLUGINS": "all" // 插件策略：全部插件可用，或按名称限定 } } }

• 基本使用方法
  • 启动后，客户端可以调用服务器暴露的工具（如 ble.scan_start、ble.connect、ble.read 等）执行BLE设备交互。
  • 通过规格（Specs）和插件（Plugins）扩展 agent 的能力，提升对未知设备的理解与控制。
  • 使用Inspector等工具进行交互式测试和调试，查看工具输出和通知流。