Skip to main content
Glama
HBConline

HLORO-AI

by HBConline
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

HLORO-AI控制助手 — 项目说明

版本: v0.3.0

一、项目概述

HLORO-AI控制助手 是一套基于 MCP (Model Context Protocol) 的工业机器人控制系统。通过 DeepSeek 大语言模型把自然语言翻译为机器人控制指令，控制 HRB400 三轴 SCARA 工业机械臂。

核心能力：

  • 自然语言 → 机器人运动指令（DeepSeek V4 驱动）

  • PySide6 桌面 GUI（微信风格聊天界面）+ CLI 客户端

  • 安全边界校验 + 急停锁机制

  • MCP Server：STDIO / HTTP / OAuth 2.1 三种传输模式

⚠️ 当前状态：src/server.py 目前固定运行 仿真模式（SimRobotArm）。仓库内含远程桥接（robot_bridge.py）与硬件适配器（robot_remote.py / robot_hardware.py），但尚未接入 server.py。下文的"远程控制"为目标架构，接线后生效。

Related MCP server: RobotArm MCP P340

二、系统架构

目标架构（远程控制，待接线）

Windows PC (192.168.1.100)               Raspberry Pi (192.168.1.101)
┌────────────────────────────┐  HTTP     ┌──────────────────────────┐
│ robot-assistant.exe        │◄────────►│ robot_bridge.py          │
│  ├─ GUI (PySide6)          │  :3000    │  ├─ HTTPServer :3000     │
│  ├─ MCP Server (FastMCP)   │           │  ├─ robot_lib 翻译层     │
│  ├─ RemoteRobotArm ⚠️未接入 │           │  └─ numpy→JSON 安全转换  │
│  └─ DeepSeek API (云端)    │           │           ↓              │
└────────────────────────────┘           │  pi_share → CAN → HRB400│
                                         └──────────────────────────┘

当前实际链路（仿真）

GUI / CLI → STDIO → server.py (FastMCP) → SimRobotArm（内存状态）
                                                ↓
                                        SafetyChecker 边界校验

三、运行模式

模式

适配器

接线状态

sim（默认）

SimRobotArm

✅ 已接入 server.py

remote

RemoteRobotArm + Pi robot_bridge.py

⚠️ 模块已开发，未接入

hardware

HRB400RobotArm（Pi 本地直连）

⚠️ 模块已开发，未接入

三个适配器方法签名完全一致，接入 server.py 时按 ROBOT_MODE 选择即可，其余代码零改动。

四、项目文件结构

D:\mcp-robot-server\
├── main.py                    MCP Server 入口
├── robot_bridge.py            ★ Pi 端桥接服务（零依赖 stdlib）⚠️ 未接入
├── build.spec                 PyInstaller 打包配置
├── config.yaml                HRB400 工作范围 / 速度 / 硬件参数
├── .env                       环境变量（ROBOT_MODE / BRIDGE_URL / DEEPSEEK_API_KEY）
├── .mcp.json                  Claude Code MCP 连接配置
│
├── src/
│   ├── server.py              ★ FastMCP Server: 11 tools + 4 resources + 3 prompts
│   ├── robot.py               SimRobotArm（仿真模式，当前唯一接入）
│   ├── robot_remote.py        RemoteRobotArm（HTTP 远程桥接）⚠️ 未接入
│   ├── robot_hardware.py      HRB400RobotArm（Pi 本地直连）⚠️ 未接入
│   ├── safety.py              SafetyChecker 安全边界校验
│   ├── types.py               Position / RobotStatus / ActionResult
│   ├── config.py              AppConfig（config.yaml 驱动）
│   ├── logging.py             日志输出（stderr）
│   └── auth/                  OAuth 2.1 授权（LocalJWT / Introspection）
│
├── gui/                       PySide6 桌面端（聊天 + 状态面板）
├── client/                    CLI 客户端（DeepSeek 驱动）
├── tests/                     单元测试（103 passed, 4 skipped）
├── dist/                      robot-assistant.exe + HLORO-AI 部署包（未跟踪）
└── offline_mcp/               离线安装 wheels（未跟踪）

五、MCP 工具列表（11）

工具

参数

说明

move_to

x, y, z, speed?

绝对移动 (mm)

move_relative

dx, dy, dz, speed?

相对移动 (mm)

move_joint

joint_id, angle

单关节旋转 (°)

home

-

回零

stop

-

减速停止

emergency_stop

-

急停 + 锁定

unlock

-

解除锁定

gripper_open

-

张开夹爪

gripper_close

-

夹紧夹爪

ping

-

连接检测（只读）

get_status

-

完整状态（只读）

资源（4）：robot-arm://status / //position / //config / //dashboard（HTML 仪表盘，3 秒自动刷新） Prompt（3）：robot-home / robot-status / robot-emergency

六、安全机制

层级

机制

坐标校验

SafetyChecker（服务器端预检）

速度校验

10 ~ 200 mm/s 范围限制

急停锁

软件 locked 状态，急停后所有运动被拒，需 unlock

工具注解

readOnlyHint / destructiveHint / idempotentHint 供客户端识别

错误码

标准 JSON-RPC 错误码（-32602 参数 / -32603 内部 / -32000 急停锁）

OAuth

HTTP 模式可选 Bearer token 验证（Local JWT / RFC 7662 Introspection）

七、测试

cd D:\mcp-robot-server
uv run pytest tests/ -v        # 103 passed, 4 skipped

测试覆盖：仿真机械臂（test_robot.py）、安全边界（test_safety.py）、MCP 集成（test_server.py）、OAuth（test_auth.py）、HTTP+OAuth 端到端（test_http_server.py）、客户端（test_client.py）、硬件适配器（test_robot_hardware.py，需 pi_share 环境）。

八、Pi 端部署（目标架构，待接线）

robot_bridge.py

位置：Pi 上 /home/hr400/robot_bridge.py 依赖：仅 pi_share 项目的 .venv（无需额外安装） 功能：监听 0.0.0.0:3000，接收 JSON-RPC 调用，翻译为 robot_lib API 调用，自动转换坐标单位（m ↔ mm），numpy 数组安全转 JSON。

启动：

/home/hr400/HRobotStudiov1.0-rc.2/.venv/bin/python3 /home/hr400/robot_bridge.py

启动成功输出：

Robot Bridge -> 0.0.0.0:3000
  pi_share: /home/hr400/HRobotStudiov1.0-rc.2
  robot online: True

开机自启（可选）

sudo nano /etc/systemd/system/robot-bridge.service
[Unit]
Description=HLORO Robot Bridge
After=network.target

[Service]
Type=simple
User=hr400
ExecStart=/home/hr400/HRobotStudiov1.0-rc.2/.venv/bin/python3 /home/hr400/robot_bridge.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl enable robot-bridge
sudo systemctl start robot-bridge

九、Windows 端启动

方式一：直接运行 exe 双击 dist\robot-assistant.exe

方式二：源码运行

cd D:\mcp-robot-server
uv run python gui/main.py        # GUI 桌面端
uv run python main.py            # MCP Server（STDIO）
uv run robot-client              # CLI 客户端

注意：源码运行时 server 为仿真模式，get_status 返回内存中的模拟位置。接入真实机械臂需先完成"运行模式"接线。

十、常见问题

问题

解决

GUI 无法连接服务端

检查服务端是否能启动：uv run python main.py

位置数据全为 0

仿真模式正常现象；接真机需接线远程适配器

DeepSeek API 错误

检查 .env 中 DEEPSEEK_API_KEY 是否有效

打包 exe

uv run pyinstaller build.spec --noconfirm

测试失败

确认 config.yaml 为 HRB400 工作范围（X[-50,300] 等）

十一、依赖清单

Windows 端（uv）：httpx, mcp[cli], openai, pyjwt, python-dotenv, pyyaml, pyside6, pyinstaller, numpy Pi 端（robot_bridge.py）：仅需 pi_share 项目已有的 .venv，无需额外安装。

Install Server
F
license - not found
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • PlanExe

    MCP server for generating rough-draft project plans from natural-language prompts.

  • mcp

    GibsonAI MCP server: manage your databases with natural language

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HBConline/HLORO-AI'

If you have feedback or need assistance with the MCP directory API, please join our Discord server