Skip to main content
Glama
Industrial-Robot-Welding-Simulator

Industrial-Robot-Welding-Simulator

by ajdanoff
README.md
# MCP Robot Welding (`mcp-robot-welding-sim`)

Прототип MCP-сервиса (**MCP SDK v2**) для генерации, кинематической валидации и постпроцессинга программ сварки 6-осевым промышленным роботом.

Проект демонстрирует безопасный инженерный подход к интеграции LLM в робототехнические системы: **LLM не генерирует управляющие команды моторам напрямую**, а работает через строго типизированные контракты MCP Tools, после чего детерминированный планировщик и физический валидатор проверяют траекторию перед компиляцией кода для контроллера.

---

## Ключевой принцип

**LLM не является источником истины для безопасности и корректности робототехнической программы.**

* **Роль LLM / MCP-клиента:**
  * Интерпретировать запрос оператора на естественном языке.
  * Извлекать целевые идентификаторы швов и технологические параметры.
  * Формулировать высокоуровневую последовательность вызовов инструментов и объяснять результат.
* **Роль детерминированного ядра (Quality Gates):**
  * Решение прямой и обратной кинематики 6-DoF манипулятора (`SE(3)` / `SO(3)`, геометрический якобиан, метод Левенберга — Марквардта).
  * Контроль ограничений суставов и непрерывности траектории в пространстве обобщённых координат (`MAX_JOINT_JUMP_DEGREES`).
  * Плотная проверка коллизий звеньев манипулятора со столом и геометрией заготовки (`AABB`, 20 проверок на каждый сварной шов).
  * Компиляция проверенной траектории в синтаксис конкретного промышленного контроллера через постпроцессор (`MELFA-BASIC` / `ISO G-code`).

---

## Архитектура

```text
User / MCP Client (LLM Agent)
        │
        ▼  (Model Context Protocol v2)
MCP Server (Industrial-Robot-Welding-Simulator)
        │
        ├─► inspect_workpiece() / scene://workpiece/seams
        │        └─► CAD metadata & available weld seams
        │
        ├─► plan_and_simulate_weld(seam_ids, weld_speed_mm_s)
        │        ├─► Trajectory Planner (HOME -> APPROACH -> WELD -> RETRACT -> HOME)
        │        ├─► 6-DoF Inverse Kinematics Solver (Geometric Jacobian + DLS)
        │        ├─► Joint-Space Continuity Gate (anti-flip check)
        │        └─► Dense AABB Link-Chain Collision Validator
        │
        └─► export_robot_program(dialect="melfa" | "gcode")
                 └─► Vendor-Specific Postprocessor (MELFA-BASIC / G-code)
```

---

## Реализованные MCP Tools и Resources

### Resource: `scene://workpiece/seams`
Возвращает метаданные загруженной CAD-заготовки (`Bracket_Assembly_REV_B`) и список доступных сварных швов в формате JSON.

### Tool 1: `inspect_workpiece`
Возвращает имя детали, описания швов и их стартовые/конечные координаты в системе координат базы робота.

### Tool 2: `plan_and_simulate_weld`
Строит траекторию подхода, линейной сварки (`MOVL`) и отхода по нормали, решает 6-DoF IK для каждой точки с выбором наиболее плавной конфигурации суставов и проверяет отсутствие коллизий вдоль всего шва.

```json
{
  "seam_ids": ["seam_top_rib", "seam_left_flange"],
  "weld_speed_mm_s": 30.0,
  "approach_clearance_mm": 40.0
}
```

### Tool 3: `export_robot_program`
Транслирует последний валидированный план в исполняемый код контроллера (`melfa` для MELFA-BASIC или `gcode`).

```json
{
  "dialect": "melfa",
  "program_name": "BRACKET_WELD_01"
}
```

---

## Пример сгенерированной программы (`MELFA-BASIC`)

```basic
' PROGRAM: BRACKET_WELD_01
' GENERATED BY MCP-ROBOT-WELDING-SIM
SERVO ON
OVRD 50
P1 = (450.000, 0.000, 500.000, 180.000, 0.000, 180.000)(6, 0)
P2 = (480.000, 0.000, 220.000, 180.000, 0.000, 180.000)(6, 0)
P3 = (480.000, 0.000, 180.000, 180.000, 0.000, 180.000)(6, 0)
...
SPD 150.000
MOVJ P1 ' HOME_SAFE
SPD 120.000
MOVJ P2 ' seam_top_rib_APPROACH
SPD 30.000
MOVL P3 ' seam_top_rib_START
HOPEN 1 ' ARC_START (WELDING POWER ON)
DLY 0.300
```

---

## Запуск и проверка

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Запуск интеграционных и модульных тестов (7 passed)
pytest -v

# Запуск сквозной CLI-демонстрации
python3 demo.py

# Запуск MCP-сервера (stdio transport)
python3 -m mcp_robot_welding.mcp_server
```

---

## Направления дальнейшего развития

* **Геометрия и коллизии:** переход от `AABB` к иерархии ограничивающих объёмов (`BVH` / OBB на базе кодов Мортона) для сложных CAD-моделей.
* **Симуляция и робототехника:** интеграция с **ROS 2 / MoveIt 2 / Gazebo** и промышленными симуляторами.
* **Постпроцессоры:** расширение генераторов под **KUKA KRL**, **ABB RAPID** и **FANUC TP**.
* **Продакшн-инфраструктура:** асинхронная очередь задач (`RabbitMQ`), хранение программ (`PostgreSQL`), телеметрия (`Prometheus / Grafana`) и *Human-in-the-loop* подтверждение перед загрузкой на реальный контроллер.