Skip to main content
Glama
yjdaaa

moss-xiaozhi-mcp

by yjdaaa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MOSS 小智 MCP 本地能力助手

License: MIT

面向小智/MOSS 语音助手的本地 MCP 服务：通过 WebSocket 接入点把本机工具暴露给助手，并围绕文字激光任务提供预览、参数建议、材料校准和确认发送流程。

当前版本：0.1.0（Alpha）

功能概览

能力

作用

默认状态

文字激光任务

根据文字生成素材、预览和 G-code/NC，并支持反馈调参和重新生成

启用

图片与文字 G-code

生成文字图片，或将图片、文字轮廓转换为激光加工文件

启用

激光硬件控制

通过串口 GRBL 或 Grbl_ESP32 网络接口检查状态、发送任务和查询命令

启用，发送需确认

材料参数与校准

查询材料库、推荐参数、生成校准矩阵并保存最佳单元格

启用

本机 Web 页面

浏览器输入文字、生成预览并在确认后提交网络发送

启用

Excalidraw 画板

在网页画图并导出激光加工文件

实验性

摄像头识别

通过 ONVIF 摄像头拍照并分析画面

需 ENABLED_IP_CAMERA=true

本机自动化

打开应用、执行命令和发送快捷键

启用

生成图片、预览、推荐参数和生成 G-code 不等于启动设备。完整文件发送、运动、切割、开激光和危险 GRBL 命令都受确认门禁保护。

Related MCP server: BambuStudio MCP Server

工作方式

小智/MOSS
   | WebSocket MCP_ENDPOINT
   v
moss_mcp/bridge.py
   | stdin/stdout
   v
moss_mcp/server.py (FastMCP)
   | 动态发现并调用 register_tool(mcp)
   v
tools/ ---------------> core/
   ^                      |
   |                      +-- G-code、材料、运行时和硬件逻辑
   |
浏览器 ----------------> moss_mcp/web_server.py
                          |
                          +-- 本机 Web 预览与确认流程

moss_mcp.server 会自动发现 tools/*.py，优先注册激光主链路模块；模块必须提供 register_tool(mcp) 才会注册。摄像头由环境变量控制，Home Assistant 和 LaserGRBL GUI 当前在服务端默认不注册。

快速安装

要求 Python 3.10+。依赖和可选功能组统一维护在 pyproject.toml 中：

# 基础 MCP 服务
python -m pip install -e .

# 激光、图像和串口相关能力
python -m pip install -e ".[laser]"

# 摄像头识别
python -m pip install -e ".[vision]"

# 桌面自动化
python -m pip install -e ".[desktop]"

# 本地测试和激光测试依赖
python -m pip install -e ".[dev,laser]"

快速开始

1. 创建本机配置

在项目根目录复制配置模板：

# macOS / Linux
cp .env.example .env

# Windows
copy .env.example .env

至少填写小智/MOSS 控制台生成的 MCP 接入点：

MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=<your-token>

真实 token、设备地址、摄像头账号密码、Home Assistant token 和本机私有路径只放在 .env，不要提交到 Git。

2. 启动 MCP 服务

手动启动桥接和 MCP 服务：

python -m moss_mcp.bridge moss_mcp.server

Windows 用户也可以运行：

scripts\start.bat

该脚本会创建或复用虚拟环境，检查依赖，启动本机 Web 页面，然后启动 MCP 桥接。支持 -SkipInstall、-NoBrowser、-Host、-Port 和 -VenvDir 参数。

3. 打开本机 Web 页面

单独启动 Web 页面：

python -m moss_mcp.web_server

默认地址为 http://127.0.0.1:8766/。也可以显式指定监听地址和端口：

python -m moss_mcp.web_server --host 127.0.0.1 --port 8767

Windows 启动脚本会同时运行 Web 页面和 MCP 桥接；如果只需要 Web 页面，可直接执行上面的 python -m moss_mcp.web_server 命令。

页面中的“生成预览”只准备文字任务、预览图和 G-code；确认材料、厚度、功率、速度、次数和设备信息后，才可进入网络发送流程。不要把 Web 页面绑定到公网地址。

4. 连接小智/MOSS

确认控制台中的 MCP 接入点与 .env 中的 MCP_ENDPOINT 一致。连接后可以从文字任务开始，例如请求助手生成一个名字牌预览；正式发送前必须明确确认。

MCP 工具

以下工具由当前 tools/ 模块注册。实际可用列表还会受到环境变量和服务端禁用列表影响。

文字、图片与工作流

工具

用途

generate_text_laser_task_tool

创建文字激光任务、预览和 G-code/NC

refine_laser_params_from_feedback_tool

根据加工反馈生成参数调整建议

regenerate_text_laser_task_tool

使用新的参数重新生成任务

generate_text_image_tool

生成文字素材图片

generate_text_image_gcode_tool

将文字素材转换为 G-code，支持栅格、轮廓和切割路径

ai_laser_gcode_tool

统一处理图片/文字素材、候选文件、预览摘要和生成结果

laser_workflow_tool

为语音、Web 和其他客户端提供预览、状态、确认发送、取消和反馈入口

激光设备

工具

用途

check_laser_connection_tool

只读检查串口和网络设备是否可达

laser_safe_action_tool

执行状态查询、解锁、归零、设置原点、关激光、移动、急停和软复位等语义动作

laser_grbl_tool

串口 GRBL 机型信息、图片转 G-code、任务发送、任务状态和命令查询

laser_network_grbl_tool

Grbl_ESP32/ESP3D 的 HTTP/Telnet 查询、任务发送、任务状态和取消

完整文件发送会要求 confirmed=true，并在发送前执行只读在线探测。网络完整文件发送使用受控的 Telnet 传输路径；设备不可达或无响应时不会继续发送。

材料与校准

工具

用途

material_params_tool

查询、保存、导入和导出材料参数

recommend_laser_params_tool

根据材料、厚度和模式读取推荐参数

run_calibration_grid_tool

生成材料参数校准测试矩阵

select_calibration_cell_tool

选择校准矩阵中的最佳单元格并写入材料库

start_tuned_job_tool

使用材料推荐或校准结果准备正式任务

材料参数默认维护在 .lasergrbl_materials.json，也可以通过 LASER_MATERIAL_PARAMS_FILE 指定本机文件。测试矩阵和参数管理不会绕过发送确认门禁。

本机自动化与可选工具

工具

用途

默认状态

open_app_tool

打开本机应用或网站

启用

open_jsjds_website_tool

打开中国大学生计算机设计大赛官网

启用

command_execution_tool

执行本机终端命令

启用，高风险

shortcut_key_execution_tool

发送预定义媒体快捷键

启用

camera_tool、adjust_the_camera_view_tool

ONVIF 摄像头识别和云台控制

需 ENABLED_IP_CAMERA=true

homeasstant_tool

Home Assistant 小米屏幕挂灯控制

服务端默认禁用

lasergrbl_gui_tool

LaserGRBL 桌面 GUI 自动化

服务端默认禁用

配置参考

常用配置位于 .env.example：

配置项

作用

MCP_ENDPOINT

小智/MOSS MCP WebSocket 接入点，必填

ENABLED_IP_CAMERA

是否注册 ONVIF 摄像头工具，默认 false

LASER_DEFAULT_CONNECTION_MODE

默认连接模式：network 或 serial

LASER_ENGRAVING_MODE

默认雕刻方式：raster 或 outline

LASER_NETWORK_HOST

网络激光控制器地址

GRBL_DEFAULT_PORT、GRBL_BAUDRATE

串口 GRBL 默认端口和波特率

LASER_WEB_HOST、LASER_WEB_PORT

本机 Web 服务监听地址和端口

LASER_MATERIAL_PARAMS_FILE

本机材料参数库路径

未配置的可选能力保持安全默认值；不要为了启用功能把真实凭据写进仓库文件。

安全边界

  • 生成图片、G-code/NC、文字任务、预览、参数推荐和反馈调参默认不连接设备。

  • 发送完整文件、运动、切割、开激光、GRBL 设置修改和危险单命令必须经过代码中的确认门禁。

  • 发送前会进行只读设备探测；串口或网络设备不可达时，请求直接结束，不重试、不继续发送。

  • Web 页面默认只绑定 127.0.0.1。绑定 0.0.0.0 只适用于可信局域网，不应映射到公网。

  • 测试中的串口、HTTP、Telnet、摄像头、GUI、子进程和本地应用都应使用 mock、fake 或临时目录。

详细安全约束见 docs/developer/safety.md 和 docs/laser/README.md。

项目结构

.
├─ moss_mcp/                 # MCP 桥接、工具注册和本机 Web 入口
├─ core/                     # G-code、材料、运行时和硬件共享逻辑
├─ tools/                    # MCP 工具模块，每个模块提供 register_tool(mcp)
├─ apps/
│  ├─ laser_web/             # 本机激光 Web UI
│  └─ excalidraw_lab/        # Excalidraw 激光画板和 UI 测试页面
├─ tests/                    # Python 单元测试
├─ docs/                     # 用户、开发者、激光和集成文档
├─ scripts/                  # Windows 启动脚本
├─ assets/                   # 文档和界面资源
├─ .github/workflows/        # CI：Python、Web 和 UI Preview
├─ .env.example              # 配置模板
├─ pyproject.toml            # 唯一依赖和打包配置
└─ README.md

测试与构建

运行 Python 测试：

python -m unittest discover -s tests

Excalidraw Web 应用的测试和构建：

cd apps/excalidraw_lab/web
npm ci
npm test
npm run build

UI Preview 的测试：

cd apps/excalidraw_lab/ui-preview
npm ci
npm test

CI 配置位于 .github/workflows/ci.yml。

文档导航

主题

内容

链接

开始使用

安装、配置、启动和默认安全激光流程

用户快速入口

Windows

Windows 启动脚本和环境说明

Windows 指南

开发规范

代码组织、注册约定、测试和文档维护

开发规范

安全

高风险能力、确认门和测试边界

开发者安全指南

激光

硬件基线、网络命令、G-code 和工具边界

激光文档索引

功能

面向维护者的功能和模块总览

功能字典

小智/MOSS 集成

控制台提示词和知识库文本归档

提示词归档

贡献

开发环境、测试和提交约定

CONTRIBUTING.md

安全报告

漏洞报告和敏感信息处理

SECURITY.md

贡献与许可

新增 MCP 工具请保持 register_tool(mcp) 注册约定，并为校验、安全门禁和外部效果添加测试。提交前请确认没有包含 .env、运行产物、虚拟环境、设备凭据或本机私有路径。

本项目采用 MIT License，详见 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • BambuStudio MCP Server

    hunter-stradley
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    Provides end-to-end 3D printing automation for Bambu Lab printers, allowing users to generate, slice, and monitor prints using natural language. It features model generation from text or images, real-time camera monitoring, and automated print quality improvement.
    MIT

  • Voice MCP

    shreyaskarnik
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables bidirectional voice interaction for Claude Code using local speech-to-text and text-to-speech models optimized for Apple Silicon. It provides tools to listen to user speech via microphone and speak responses aloud through system speakers.
    16
    Apache 2.0

  • CNCjs MCP Server

    brs077
    A
    license
    B
    quality
    D
    maintenance
    Bridges Claude Code to CNCjs to enable remote control and monitoring of GRBL-based CNC machines. It provides a comprehensive toolset for managing G-code jobs, machine movement, and safety operations through natural language.
    30
    1
    MIT