bmahs-mcp-gateway-node
This server is a BMAHS-to-MCP gateway that lets AI clients discover, inspect, exclusively occupy, and control LAN hardware devices through MCP tools.
Discover devices:
bmahs_deviceslists all found devices with ID, name, description, type, status, holder, and address; optional type filter.Rescan network:
bmahs_refreshre-sends multicast queries and refreshes device self-descriptions.Inspect device capabilities:
bmahs_describereturns a device's full operations, security boundaries, and natural-language self-description.Manage exclusive access:
bmahs_occupyobtains a timed lease (default 120s, max capped) andbmahs_releasefrees it; tokens are managed internally and automatically attached.Call device actions generically:
bmahs_callexecutes any operation in a device's operations list with arbitrary args.Capture screenshots:
bmahs_screenshotgrabs a JPEG frame from devices that declareuicapability, returning the image and saved path.Dynamic per-device tools: Each device's operations are auto-mapped to MCP tools named
<device_id>__<action>with JSON Schema and natural-language descriptions.Safety features: Automatic occupy-before-control, token suppression, parameter coercion/loop-guard, and fixed device tools for controlled operation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bmahs-mcp-gateway-node find all BMAHS devices on my network"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bmahs-mcp-gateway-node
BMAHS(比马斯) 是一个开放的局域网硬件协议:每台设备上电即用自然语言「自我介绍」——我是谁、能做什么、安全边界在哪——让大模型智能体像接入 USB 设备一样,即插即用地发现、识别、按权限独占并安全地操作它们。
BMAHS(比马斯)设备协议 ↔ MCP 网关的 Node.js / TypeScript 实现:把局域网内按 bmahs/1.0 协议发布的硬件设备(解析侧兼容旧版 1–1.2 字段名)动态映射为 Model Context Protocol 工具,让大模型客户端可以直接发现、占用与操作这些设备。
与 Python 版(bmahs-mcp-gateway)功能全量对齐,两者可互换使用,也可与对方的参考设备跨语言互通(npm run smoke:py)。
特性
零配置发现:UDP 组播(
239.255.42.42:5354/[ff02::4242]:5354,多网卡全 join + 自愈)+ Bonjour/mDNS 双通道;BMAHS_STATIC_DEVICES静态设备表适配容器/跨网段。动态工具映射:设备
operations自动映射为 MCP 工具(<设备id>__<动作>),含 JSON Schema、any_of 约束与自然语言说明,无需为每类设备写适配。协议级占用安全:控制前自动
occupy(有限租约)、token 按会话保管并自动携带、进程退出统一release、token 递归遮蔽绝不回显。参数死循环防护(1.3.0,默认开启):参数净化器自动矫正畸形入参(device 传成
{id: 名称}对象、数字加引号、id/动作名近似错),同参连续失败升级提示直至停止令;报错附可逐字照抄的retry_with模板。两种接入模式:stdio(单客户端)与 Streamable HTTP(多客户端共享,Bearer Token 常量时间鉴权,占用方可追溯到
-sN会话)。实验性抓屏:声明了
ui能力的设备可bmahs_screenshot抓帧(§4.9 二进制流解析)。
Related MCP server: MCP-Edge
安装
npm install -g bmahs-mcp-gateway-node # 全局安装,得到命令 bmahs-mcp-node(与 pip 版的 bmahs-mcp 不冲突)
npx -y bmahs-mcp-gateway-node@latest serve # 免安装直接运行验证:bmahs-mcp-node --version 输出 bmahs-mcp-node 0.1.1。要求 Node.js ≥ 20。国内网络安装慢可临时走镜像 --registry=https://registry.npmmirror.com(同步可能有几分钟延迟)。
从源码构建开发:
npm install
npm run build # tsc → dist/
node dist/bin.js --version快速开始
# 扫描局域网内的 BMAHS 设备(全局安装后把 node dist/bin.js 换成 bmahs-mcp-node)
node dist/bin.js discover
# 联调:对设备执行一个动作(控制类动作自动 occupy → 执行 → release)
node dist/bin.js ctl 客厅灯 on
node dist/bin.js ctl 客厅灯 brightness --arg level=80
node dist/bin.js ctl 客厅灯 scene --arg name=cinema --ttl 600 # 指定占用租约 600 秒
node dist/bin.js ctl 客厅灯 on --no-release # 动作后保持占用(打印 token)
node dist/bin.js ctl 客厅灯 release --arg token=<占有时返回的 token> # 手动释放保持的占用
# 启动 MCP 网关(stdio,默认子命令)
node dist/bin.js serve
# 以 Streamable HTTP 共享模式启动(多客户端同时连接)
node dist/bin.js http --host 0.0.0.0 --port 9530 --token 换成你的令牌在 MCP 客户端中配置 stdio 接入:
{
"mcpServers": {
"bmahs-node": {
"command": "node",
"args": ["/绝对路径/bmahs-mcp-gateway-node/dist/bin.js", "serve"]
}
}
}HTTP 模式端点为 http://<host>:9530/mcp;设置了 --token 后客户端须携带 Authorization: Bearer <token>。
重启客户端后,模型可见两类工具:7 个固定工具——bmahs_devices(列设备)、bmahs_refresh(重扫描)、bmahs_describe(读自述)、bmahs_occupy / bmahs_release(占用/释放)、bmahs_call(泛化调用)、bmahs_screenshot(ui 设备抓屏);以及每台设备的动态工具——<设备id>__<动作>(如 demo-light-001__brightness),参数说明来自设备自述。典型流程:bmahs_devices 选型 → 直接调动态工具(网关自动 occupy 并携带 token,默认 120 秒租约)→ 用完 bmahs_release;token 由网关代管并遮蔽,不进模型上下文。
常见问题
扫不到设备? 确认设备已上电且同网段、Windows 防火墙放行 UDP 5354 入站;多网卡机器用
BMAHS_MCAST_IF_V4指定网卡;跨网段/容器用BMAHS_STATIC_DEVICES=tcp://IP:端口静态表兜底。报「正被 xxx 占用」(occupied)? 设备独占中:
bmahs_devices看holder/until,等租约到期或请占用方bmahs_release;协议无强夺机制(防止两个模型打架)。HTTP 模式 401? 请求头须带
Authorization: Bearer <--token 设置的值>。stdio 模式没有输出? 正常:stdout 是 MCP 协议通道,日志全走 stderr(
BMAHS_LOG_LEVEL=debug调高)。
环境变量
与 Python 版同名同义:
变量 | 默认 | 说明 |
|
| 网关在协议中的智能体 id |
| 空 | 静态设备表,逗号/分号分隔 |
|
|
|
|
| 自动占用策略与租约上限 |
|
| 调用超时、query 周期与设备过期时限 |
| 空 | 动态工具黑白名单(fnmatch 通配符,deny 优先) |
|
| bmahs_screenshot 帧落盘目录 |
| 自动枚举 | 手动指定组播网卡(逗号分隔本机 IPv4) |
|
| HTTP 模式默认参数 |
|
| 日志级别(一律走 stderr) |
|
| 参数净化器(防线②):device 传成对象自动解包、字符串数字转声明类型、id/动作名近似矫正; |
|
| 防循环守卫(防线③):同一工具同参连续失败第 2 次升级提示、第 N 次下达停止令 |
|
| bmahs_describe 的 device 可选(唯一设备自动选中,多台返回选择清单) |
|
| 备用:为每台设备生成零参数 |
开发与测试
npm test # vitest 单元/集成测试(假设备,不需要真实硬件)
npm run smoke # 端到端 17 项契约(假设备 + stdio 网关 + MCP 客户端)
npm run smoke:py # 跨语言联调(拉起 ../examples/demo_light.py,需要上层 .venv)测试拓扑:fake-device.ts 是只实现控制层与 UI 流的测试假设备(不绑组播、状态可注入),与 Python 版 tests/fake_device.py 行为对齐。
协议
完整协议文档见 Python 主仓库的 docs/BMAHS1.0.md:UDP 组播一报文一 JSON(≤1400 字节)负责发现,TCP 一行 JSON + \n 负责控制,连上先读 hello;网关在协议中承担「智能体」角色(§4.8)。
License
Available Tools
7 toolsbmahs_callA
对 BMAHS 设备执行任意其操作清单内(operations)的动作,参数按该动作的 args 传。适合调用尚未生成独立工具的动作,或临时查看新设备。
Inputs: action (required), device (required), args.
bmahs_describeARead-only
读取某台 BMAHS 设备的完整操作清单(operations)、安全边界(security)与自然语言自述。
Inputs: device (required).
bmahs_devicesARead-only
列出当前发现的全部 BMAHS 设备(id、显示名、自然语言自述、类型、状态、占用方与连接地址)。选设备、查占用状态时先用这个工具。
Inputs: type.
bmahs_occupyA
独占占用一台 BMAHS 设备(返回的 token 由网关保存并自动携带)。租约由网关强制为有限时长:不带 ttl 默认 120 秒(2 分钟),请求值超过上限(默认 3600 秒)会被截断,不支持无限期占用。租约到期设备自动收回占用权;任务结束也可调用 bmahs_release 提前释放。
Inputs: device (required), ttl.
bmahs_refreshARead-only
重新扫描 BMAHS 设备:发送组播 query 并刷新各设备的自述(hello)。当设备列表为空、新设备刚上电、或怀疑列表过期时调用。
Inputs: no named parameters.
bmahs_releaseA
释放对某台 BMAHS 设备的占用。任务结束、失败或取消后必须调用,否则其它智能体会一直收到「被占用」。
Inputs: device (required).
bmahs_screenshotA
(实验)对声明了 ui 能力的 BMAHS 设备抓取一帧当前画面:自动 ui.start → 二进制流取一帧 JPEG → ui.stop,返回图片与保存路径。
Inputs: device (required), max_width.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct operation: listing, refreshing, describing, occupying, releasing, generic calling, and screenshotting. The only minor ambiguity is between bmahs_devices and bmahs_refresh (both concern device discovery), but their descriptions clearly separate current listing from force-rescanning.
All tools share the uniform bmahs_ prefix and snake_case style, with simple verbs (refresh, describe, occupy, release, call). The slight inconsistency is that bmahs_devices uses a noun instead of a verb like list_devices, and bmahs_screenshot is a noun-verb hybrid, but the pattern remains predictable.
Seven tools is a well-scoped size for a device gateway. Each tool covers a distinct phase of the device lifecycle: discovery, inspection, access control, and execution, without unnecessary redundancy or bloat.
The tool surface provides a full workflow: discover devices (devices/refresh), understand capabilities (describe), reserve access (occupy/release), execute actions (call), and capture UI (screenshot). The generic bmahs_call fills gaps for unmodeled actions, making the set effectively complete for the stated gateway purpose.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes MCP tools that enable remote LLMs to query local Docker containers, OS processes, and system services in real time.-
- AlicenseNot gradedqualityCmaintenanceEnables cloud LLM agents to discover and invoke physical hardware on edge and IoT devices through standard MCP tools, bridging constrained device channels like UART, BLE, and Wi-Fi.19 PyPI3MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to discover and interact with iOS apps through a local MCP gateway, converting remote Streamable HTTP MCP endpoints into stdio tools. Provides dynamic device discovery, tool schema introspection, and deterministic tool calling for app analysis.-
- AlicenseAqualityBmaintenanceEnables AI clients to discover, occupy, and operate LAN hardware devices that speak the BMAHS protocol by mapping their actions to MCP tools.767 PyPIMIT