Robot NXT Control MCP

Локальный MCP-сервер для совместимого программируемого блока, подключаемого к Windows 11 через USB/WinUSB.

Совместимость и товарные знаки

Этот независимый проект не связан с LEGO Group, не спонсируется и не поддерживается ею. LEGO, MINDSTORMS и NXT являются товарными знаками LEGO Group. Они используются в этой документации только для обозначения совместимого оборудования, программного обеспечения, протоколов и сторонних зависимостей; они не являются частью названия этого проекта, идентификатора сервера или идентификатора плагина.

Переход с более ранних версий

Прежний идентификатор плагина и MCP-сервера заменён на robot-nxt-control, а исполняемые файлы теперь называются robot-nxt-control-mcp, robot-nxt-control-mcp-stdio и robot-nxt-control-mcp-http. После получения этого изменения переустановите пакет в режиме редактирования и замените более ранние записи конфигурации MCP на примеры ниже.

Related MCP server: KentraBOT MCP Server

Установка в Claude Desktop или Codex desktop (Windows)

Сначала выполните установку для Windows. Эти настольные приложения сами запускают MCP-сервер, поэтому не запускайте robot-nxt-control-mcp-stdio.exe вручную. В примерах предполагается, что репозиторий находится в C:\Users\lukas\workspace\NXT-MCP; замените эту часть во всех путях, если ваша копия репозитория расположена в другом месте.

Claude Desktop

1. Полностью закройте Claude Desktop (включая его значок в трее).

2. Откройте %APPDATA%\Claude\claude_desktop_config.json. Создайте файл, если его нет. Если в нём уже есть объект mcpServers, добавьте только запись robot-nxt-control из примера ниже.

3. Сохраните файл и снова запустите Claude Desktop. Сервер должен появиться в разделе Settings → Developer → MCP servers.

{
  "mcpServers": {
    "robot-nxt-control": {
      "command": "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe",
      "cwd": "C:\\Users\\lukas\\workspace\\NXT-MCP"
    }
  }
}

Та же готовая к копированию конфигурация находится в packaging/claude-desktop/mcp.json.

Codex desktop

Хост Codex desktop и Codex CLI используют общую конфигурацию MCP в %USERPROFILE%\.codex\config.toml. Добавьте этот блок (или выполните эквивалентную команду codex mcp add ниже), затем перезапустите приложение Codex:

[mcp_servers.robot-nxt-control]
command = "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe"
cwd = "C:\\Users\\lukas\\workspace\\NXT-MCP"
startup_timeout_sec = 10
tool_timeout_sec = 120

Альтернатива в PowerShell:

codex mcp add robot-nxt-control -- C:\Users\lukas\workspace\NXT-MCP\.venv\Scripts\robot-nxt-control-mcp-stdio.exe
codex mcp list

Для пользовательского интерфейса MCP в ChatGPT desktop: Settings → MCP servers → Add server, выберите STDIO, введите robot-nxt-control, укажите тот же исполняемый файл в качестве команды, сохраните и перезапустите приложение. Локальные клиенты Codex поддерживают и STDIO, и Streamable HTTP и используют эту общую конфигурацию MCP. Официальная документация OpenAI по MCP

Первая проверка

Откройте новый чат и запросите nxt_info. Если подключиться не удаётся, сначала убедитесь, что робот работает, выполнив ./.venv/Scripts/nxt-test.exe --log-level=debug; затем проверьте, что все настроенные пути существуют и NXT включён. Инструменты движения управляют реальным оборудованием: начните с nxt_info или query_all_state, затем используйте команды с низкой мощностью и ограниченным перемещением.

MCP-транспорты, хосты и проверка

Одна и та же фабрика create_server() обеспечивает оба транспорта. robot-nxt-control-mcp-stdio — это локальный процессный транспорт для Claude Desktop, Claude Code, Codex CLI, Codex desktop и локальных плагинов Codex. Он записывает протокольный трафик только в stdout.

Используйте прилагаемый JSON как исходную конфигурацию, заменив абсолютный путь к рабочей области после перемещения копии репозитория:

• Claude Desktop: packaging/claude-desktop/mcp.json

• плагин Claude Code: packaging/claude-code/

• локальный плагин Codex: C:\Users\lukas\plugins\robot-nxt-control (создаётся в личном маркетплейсе)

Для проверки протокола запустите Streamable HTTP на loopback-интерфейсе:

.\.venv\Scripts\robot-nxt-control-mcp-http.exe --port 8000
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list
npx @modelcontextprotocol/conformance server --url http://127.0.0.1:8000/mcp --suite active

Запустите проверки репозитория с помощью .\.venv\Scripts\python.exe -m pytest. Они включают внутрипроцессное согласование MCP, тест tools/list, аннотации и тест tools/call, а также тесты контроллера и поведения. В conformance-baseline.yml записаны только общие сценарии, требующие опциональных возможностей MCP, которые этот узкоспециализированный аппаратный сервер не объявляет; каждая запись — это снимаемое по мере выполнения утверждение, поэтому раннер помечает устаревшие записи.

robot-nxt-control-mcp-http по умолчанию привязывается к 127.0.0.1 и отказывается от привязки вне loopback, если явно не задано NXT_MCP_ALLOW_REMOTE=true. Облачный клиент не может напрямую обратиться к USB NXT: запускайте этот сервер рядом с роботом и размещайте перед конечной точкой Streamable HTTP боевой HTTPS-обратный прокси с проверкой OAuth/токенов, авторизацией, журналами аудита и сетевыми ограничениями. Никогда не открывайте конечную точку управления USB публично, полагаясь только на переопределение через переменную окружения.

См. ARCHITECTURE.md — там описаны архитектура модулей, потоки выполнения MCP и поведений, USB-стек, модель безопасности и диаграммы Mermaid.

Установка в Windows 11

Используйте Python 3.11 x64. В PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

1. Установка драйвера устройства NXT с помощью Zadig

Включите NXT и подключите его по USB. В PowerShell убедитесь, что Windows видит устройство в обычном режиме:

Get-PnpDevice -PresentOnly |
  Where-Object InstanceId -match 'VID_0694&PID_0002' |
  Format-List Status,FriendlyName,InstanceId,Problem

Идентификатор оборудования должен содержать USB\VID_0694&PID_0002. Если в поле Problem указано CM_PROB_FAILED_INSTALL или Диспетчер устройств показывает Code 28, драйвер отсутствует.

1. Скачайте Zadig только с https://zadig.akeo.ie/.

2. Запустите Zadig от имени администратора.

3. Выберите Options > List All Devices.

4. Выберите запись, чей USB ID в точности равен 0694:0002. Ориентируйтесь на идентификатор, а не только на отображаемое имя устройства.

5. В селекторе драйвера выберите WinUSB.

6. Нажмите Install Driver или Replace Driver.

7. Отключите и снова подключите NXT, оставив его включённым.

Не выбирайте 03EB:6124; это режим загрузчика/обновления прошивки NXT. Не заменяйте драйверы для любых посторонних USB-устройств. Установка WinUSB может помешать старому ПО LEGO NXT-G общаться с блоком, пока не будет восстановлен его драйвер LEGO/Fantom.

2. Установка x64-версии библиотеки libusb для PyUSB

WinUSB — это драйвер устройства Windows. PyUSB отдельно требует пользовательскую DLL libusb-1.0.dll. В репозиторий включён вспомогательный скрипт, который загружает официальный архив libusb 1.0.30, проверяет его SHA-256 и устанавливает DLL VS2022 x64 рядом с python.exe из этого окружения:

.\scripts\install-libusb-runtime.ps1

Вспомогательному скрипту требуется 7z.exe в PATH. Для установки вручную скачайте libusb-1.0.30.7z из официального релиза libusb на GitHub, извлеките VS2022\MS64\dll\libusb-1.0.dll и скопируйте его в .venv\Scripts\libusb-1.0.dll. Не используйте DLL MS32 с 64-битным Python.

Проверьте среду выполнения независимо:

$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
.\.venv\Scripts\python.exe -c "import usb.backend.libusb1 as b; assert b.get_backend() is not None; print('libusb OK')"

MCP-сервер автоматически добавляет DLL, установленную рядом с Python из виртуального окружения, в свой путь поиска. nxt-test.exe — это внешняя команда NXT-Python, поэтому перед её использованием сначала выполните строку $env:PATH из примера выше или активируйте виртуальное окружение.

3. Проверка блока

Проверьте оборудование до MCP:

.\.venv\Scripts\nxt-test.exe --log-level=debug

При успешном тесте выводятся имя блока, уровень заряда батареи, версия протокола и версия прошивки. Если по-прежнему сообщается об отсутствии блока, проверьте устройство 0694:0002 в Диспетчере устройств и убедитесь, что его драйвер — WinUSB.

Прошивка

Установка или обновление прошивки не требуется, если NXT нормально загружается и Windows показывает VID 0694 / PID 0002. MCP-сервер использует стандартные прямые команды NXT, а также сообщает установленные версии прошивки и протокола через nxt_info.

Выполняйте восстановление прошивки только в том случае, если блок не может нормально загрузиться, а Windows вместо этого показывает VID 03EB / PID 6124 — это режим обновления прошивки Atmel SAM-BA. Восстановление стирает и перезаписывает прошивку блока и не входит в обычную настройку MCP:

1. Не применяйте обычное правило WinUSB для NXT к 03EB:6124.

2. Восстановите/используйте драйвер обновления прошивки, требуемый оригинальным ПО LEGO MINDSTORMS NXT.

3. В этом ПО используйте Tools > Update NXT Firmware с официальным образом прошивки NXT.

4. После восстановления выполните перезагрузку питания блока. Он должен снова определиться как 0694:0002; затем при необходимости снова установите WinUSB для этого устройства в обычном режиме.

NXT-Python намеренно не предоставляет возможности записи прошивки. Не вызывайте режим загрузчика прошивки и не пытайтесь выполнить обновление только для устранения NoBackendError, Code 28 или сбоя подключения MCP.

Затем откройте MCP Inspector:

.\.venv\Scripts\mcp.exe dev src\nxt_mcp\server.py

Для локального MCP-хоста настройте stdio-сервер с командой .venv\Scripts\robot-nxt-control-mcp.exe и укажите репозиторий в качестве рабочего каталога.

Объявите датчики, подключённые к блоку, до запуска сервера, чтобы снимок всего блока мог сразу возвращать типизированные показания:

$env:NXT_SENSOR_MAP = "1:touch,2:light,4:ultrasonic"
.\.venv\Scripts\robot-nxt-control-mcp.exe

Вызов read_sensor или команда двигателя, управляемая датчиком, также запоминает тип этого порта для последующих снимков.

Высокоуровневые инструменты

• move_motor_relative(port="C", power=40, degrees=2000) перемещает C вперёд на 2000 градусов энкодера. Используйте отрицательную мощность для противоположного направления. Адаптер использует плотный цикл опроса энкодера по USB, поскольку стандартный цикл turn() в NXT-Python опрашивает слишком медленно для небольших перемещений. Для движений около 45 градусов используйте меньшую мощность, например 20.

• zero_motor_position(port="C") задаёт текущую позицию энкодера C как абсолютный 0. Затем move_motor_absolute(port="C", target_degrees=-90, power=20) перемещает в -90. Абсолютное движение определяет направление по целевой точке; его power — это положительная величина.

• motor_position(port="C") сообщает абсолютную/программно-относительную позицию энкодера и «сырые» счётчики таходатчика.

• run_motor(port="C", power=-30) работает непрерывно в отрицательном направлении, пока команда остановки или ограниченное поведение не остановит его. При regulated=true параметр power задаёт регулируемую скорость NXT, а не калиброванное значение в градусах в секунду.

• run_motors(ports=["B", "C"], powers=[30, -30]) запускает группу двигателей одним вызовом MCP. stop_motors, move_motors_relative и move_motors_absolute работают с группами так же. Списки позиционные: каждое значение мощности/градусов относится к порту с тем же индексом.

• run_motor_until_sensor(port="B", power=40, sensor_port=1, sensor_type="touch", condition="pressed") запускает B, пока не будет нажат тактильный датчик S1.

• run_motors_until_sensor(ports=["B", "C"], powers=[40, 40], sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) приводит оба двигателя в движение, пока препятствие не окажется на расстоянии не более 20 см, затем останавливает всю группу.

• run_motor_until_sensor(port="B", power=40, sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) запускает B, пока препятствие не окажется на расстоянии не более 20 см.

• query_all_state(format="text") возвращает один компактный текстовый снимок блока, всех портов двигателей и всех портов датчиков. Используйте format="json" для структурированных данных.

• cycle_motor_on_touch(port="C", touch_port=1, cycles=5) движется вперёд, пока не будет нажат S1, затем реверсирует, пока он не будет отпущен, повторяет пять раз и издаёт звуковой сигнал после успешного завершения. Каждая фаза нажатия и отпускания имеет собственный таймаут и предельный путь энкодера.

Каждое движение, управляемое датчиком, имеет таймаут и ограничение перемещения по энкодеру. Достижение любого из пределов останавливает двигатель и возвращает ok: false с причиной. Двигатель также останавливается при сбое чтения датчика или USB.

Расширенная диагностика, хранение данных и телеметрия

• motor_state(port) сообщает о регулировании, состоянии запуска, тахометрах и настроенном состоянии выхода. drive_sync(left_port, right_port, power, turn_ratio=0) использует синхронизационное регулирование прошивки NXT для пары с дифференциальным приводом; wait_motors(...) имеет предельный срок и останавливает свои порты по истечении времени.

• read_sensor_raw(port, sensor_type?), wait_sensor(...) и sensor_stream(...) предоставляют ограниченную диагностику, ожидание датчиков с подавлением дребезга и конечные выборки.

• Для датчиков света, цвета и ультразвуковых датчиков вызовите zero_sensor_reference(port, sensor_type), затем read_sensor_relative(port, sensor_type). Он возвращает изменение относительно захваченного нуля плюс абсолютное значение. Для цвета используется интенсивность отражённого света (а не дискретная метка красный/синий и т. д.) для осмысленного вычитания.

• log_start, log_status, log_stop и log_export предоставляют ограниченную хост-стороннюю CSV телеметрию. Допустимые каналы: battery_mv, motor:A–motor:C и sensor:1:touch (или другой поддерживаемый тип датчика/порт).

• list_files, read_file, write_file и delete_file управляют ограниченными пользовательскими файлами NXT. Запись ограничена .txt, .csv, .dat и .rso; воспроизведение звука использует play_sound_file(name) и stop_sound().

• mailbox_send / mailbox_receive поддерживают сообщения до 58 байт UTF-8; i2c_transaction — это опциональная низкоскоростная операция, ограниченная 16-байтовыми запросами и ответами. set_brick_name и keep_alive — поддерживаемые административные прямые команды.

Стандартный протокол прямых команд NXT не может использовать ЖК-дисплей NXT или читать его кнопки. Эти функции NXT-G/ROBOTC требуют отдельно установленной резидентной мостовой программы на NXT; они намеренно не предоставляются этим сервером.

Семантика позиционирования моторов

Счётчики энкодера NXT измеряются в градусах на валу мотора, а не в градусах направления робота или линейных миллиметрах. Передаточные числа, длина окружности колеса и проскальзывание колёс должны обрабатываться поведением робота, если нужны физические единицы.

Абсолютный ноль удерживается счётчиком вращения, относительным к программе, в прошивке NXT. Это не датчик начального положения и он не сохраняется: перезагрузка блока или запуск/остановка .rxe-программы делает опорное значение недействительным. Выполните возврат в исходное положение по датчику касания и вызовите zero_motor_position снова, прежде чем полагаться на абсолютные цели.

Групповые команды запускают моторы с помощью последовательных USB-пакетов в пределах одной блокировки контроллера. Они избегают рассинхронизации при обходе MCP/LLM и контролируют все энкодеры вместе, но не являются жёстким реальным временем или механической фазовой синхронизацией. Для двухколёсного робота это подходит для обычного движения; точная синхронизация может потребовать резидентной управляющей программы на NXT.

Ограничение аппаратной отчётности

Прошивка NXT сообщает о настроенном состоянии каждого порта, но не может безопасно определить, подключён ли физически незанятый мотор. Поэтому запрос всего блока сообщает все состояния прошивки A/B/C, а не утверждает наличие моторов. Порты датчиков, уже настроенные с помощью read_sensor или команды, управляемой датчиком, показывают типизированные значения; остальные порты датчиков показывают своё сырое состояние прошивки. Запрос сырого состояния не перенастраивает порты и не кратковременно подаёт питание на оборудование.

Не используйте прямые MCP-команды моторов, пока .rxe-программа управляет теми же портами.

Поведения Python на стороне ПК через MCP

Стандартный NXT не запускает Python. Этот сервер вместо этого может сохранять и запускать ограниченные поведения Python на ПК; каждая операция робота по-прежнему пересекает границу контроллера, поэтому скрипты не открывают USB, не создают экземпляры датчиков NXT-Python и не реализуют собственные циклы опроса.

Пример поведения:

def run(robot):
    robot.configure_sensor(1, "touch")

    for _ in range(5):
        robot.motor_until("C", 20, 1, "pressed")
        robot.motor_until("C", -20, 1, "released")

    robot.play_tone(440, 500)
    return "completed 5 touch cycles"

Тот же пример включён как behaviors/touch_cycle.py. Используйте эти MCP-инструменты:

validate_behavior(source)
submit_behavior(name, source)
list_behaviors()
get_behavior(name)
run_behavior(name, timeout_seconds=120)

Видимый скрипту интерфейс robot содержит:

configure_sensor(port, sensor_type)
read_sensor(port, sensor_type)
read_sensor_raw(port, sensor_type=None)
zero_sensor_reference(port, sensor_type)
read_sensor_relative(port, sensor_type)
wait_sensor(port, sensor_type, condition, ...)
sensor_stream(port, sensor_type, ...)
log_start(channels, interval_ms=100, duration_seconds=10)
log_status(job_id)
log_stop(job_id)
log_export(job_id)
motor_until(port, power, sensor_port, condition, sensor_type="touch", ...)
motor_for_ticks(port, power, ticks, ...)
motor_position(port)
zero_motor_position(port)
motor_to(port, target_degrees, power=20, ...)
run_motor(port, power, regulated=True)
drive_sync(left_port, right_port, power, turn_ratio=0)
wait_motors(ports, ...)
stop_motor(port, brake=False)
run_motors(ports, powers, regulated=True)
stop_motors(ports, brake=False)
motors_relative(ports, powers, degrees, ...)
motors_absolute(ports, powers, target_degrees, ...)
motors_until(ports, powers, sensor_port, condition, ...)
state(format="text")
play_tone(frequency_hz=440, duration_ms=500)
play_sound_file(name, loop=False)
stop_sound()
sleep(seconds)

Импорты, классы, обработка исключений, доступ к приватным атрибутам и вызовы за пределами документированных методов robot и базовых встроенных функций отклоняются. Скрипты ограничены 64 КиБ, одновременно может выполняться только один, и run_behavior принимает предельный срок от 1 до 300 секунд. Все моторы останавливаются, когда скрипт завершается или вызывает исключение.

Эта проверка предназначена для предотвращения случайного доступа за пределами интерфейса robot; это не песочница безопасности для враждебного кода. Предоставляйте доступ MCP только доверенным локальным пользователям. Установите NXT_BEHAVIOR_DIR перед запуском сервера, чтобы хранить поведения в другом месте, отличном от каталога behaviors по умолчанию в рабочем каталоге сервера.

Для демонстрации из командной строки, которая по-прежнему использует MCP stdio, а не импортирует контроллер напрямую:

.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py list
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py submit touch_cycle behaviors\touch_cycle.py
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py run touch_cycle --timeout 120

Последняя команда выполняет физическое движение. Клиент вызывает только MCP-инструменты; MCP-сервер загружает поведение и владеет всей связью с NXT.

Тестирование без блока

$env:PYTHONPATH = "src"
py -3.11 -m pytest