rigol-oscilloscope-mcp

MCP-сервер (Model Context Protocol), который позволяет LLM (Claude, Codex и др.) управлять осциллографами RIGOL через SCPI (LAN / USB) — подключаться, настраивать каналы/развёртку/синхронизацию, измерять, захватывать формы сигналов и скриншоты, декодировать последовательные протоколы, выполнять БПФ-анализ на стороне хоста и управлять встроенным AFG — всё через семантические инструменты с четырёхуровневой политикой безопасности. Проверено на реальном RIGOL MHO98; другие модели RIGOL работают по принципу best-effort через профили устройств. Документация в настоящее время на японском языке.

MCP-сервер для управления осциллографами RIGOL через LLM.

Естественно-языковые инструкции, такие как «сделай видимым сигнал 1 кГц 3 В с помощью пробника x10» или «сделай скриншот текущего сигнала и сохрани», преобразуются LLM (Claude / Codex и т. д.) в вызовы MCP Tool, а этот сервер управляет прибором по SCPI (LAN / USB). Автоматизация GUI не используется.

• Проверено на реальном RIGOL MHO98 (→ docs/verification/mho98-mvp.md)

• Другие модели RIGOL поддерживаются по принципу best-effort через профили устройств (неизвестные модели работают с профилем generic, и это явно указывается).

• Вендоры, отличные от RIGOL, не поддерживаются (при подключении возвращается предупреждение, но не отказ).

Возможности

• Подключение на основе диалога — адрес подключения обычно задаётся пользователем в разговоре (connect(address="...")). Значения по умолчанию из переменных окружения — необязательный запасной вариант.

• 26 инструментов MCP — подключение / идентификация / получение состояния / измерения / формы сигналов / анализ (статистика, БПФ) / скриншоты / настройка каналов, развёртки и синхронизации / Run, Stop, Single, Autoset / настройка последовательного декодирования и получение результатов / настройка генератора сигналов (AFG), получение состояния и управление выходом (включение выхода — с процедурой подтверждения). LLM не нужно писать строки SCPI; предоставляются только семантические инструменты.

• Политика безопасности из 4 классов + confirm-токен — все операции классифицируются как READ_ONLY / SAFE_WRITE / RESTRICTED_WRITE / DANGEROUS_WRITE. Вход 50 Ом и Auto Setup требуют двухэтапного подтверждения (confirm-токен), не зависящего от UI хоста.

• Сохранение скриншотов — сохранение в указанный путь в форматах png / jpg / bmp / webp, само изображение также возвращается LLM (место записи ограничено разрешёнными каталогами).

• Профили устройств — диалекты SCPI, наличие функций и диапазоны параметров объявляются во встроенных YAML-файлах; разрешение выполняется в три уровня: точное совпадение модели → семейство → универсальный RIGOL.

• Возврат обоих значений: requested / applied — поскольку прибор может округлять заданные значения в зависимости от модели, возвращаются и запрошенное, и считанное (read-back) значения.

• Журнал аудита — операции записи записываются в JSONL с полями Before / Action / After.

Related MCP server: Rigol DHO824 MCP Server

Установка и запуск

Стандартный способ запуска — через uvx из репозитория GitHub.

uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

По умолчанию версия зафиксирована тегом (@v0.1.0). Чтобы использовать последнюю разрабатываемую версию (main), удалите @v0.1.0.

Claude Code — плагин (рекомендуется)

Этот репозиторий также является плагином Claude: вместе с MCP-сервером устанавливаются навыки рабочих процессов измерений (рекомендуемые настройки для каждого типа сигнала, процедуры измерения UART/неизвестных сигналов, безопасные подсказки). Сначала добавьте маркетплейс, затем установите (после @ указывается имя маркетплейса):

/plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
/plugin install rigol-oscilloscope@rigol-oscilloscope-mcp

Claude Code (.mcp.json или claude mcp add)

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"],
      "env": { "RIGOL_MCP_SCREENSHOT_DIR": "~/scope-captures" }
    }
  }
}

Codex — плагин

Также включён плагин Codex (.codex-plugin/ + определение маркетплейса), позволяющий установить MCP-сервер и навыки рабочих процессов измерений одним пакетом.

codex plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
codex plugin install rigol-oscilloscope

(Если плагин не используется, навыки можно скопировать в ~/.agents/skills/ из skills/measurement-workflows — они будут распознаны. Если нужен только MCP-сервер, достаточно следующей настройки config.toml)

Codex (~/.codex/config.toml)

[mcp_servers.rigol-oscilloscope]
command = "uvx"
args = ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"]

[mcp_servers.rigol-oscilloscope.env]
RIGOL_MCP_SCREENSHOT_DIR = "~/scope-captures"

Запуск из локального клона

Если вы клонировали репозиторий и хотите использовать разрабатываемую версию, запускайте через uv run --directory.

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/rigol-oscilloscope-mcp", "rigol-oscilloscope-mcp"],
      "env": { "PYTHONDONTWRITEBYTECODE": "1" }
    }
  }
}

• command указывайте абсолютным путём, если в PATH GUI-хоста (настольного приложения) нет uv. Путь можно узнать через which uv (или mise which uv, если используется mise).

• Явно задайте PYTHONDONTWRITEBYTECODE=1. При запуске извне проекта [env] из mise.toml не действует, поэтому это предотвращает запись __pycache__ в клон.

• Каталог по умолчанию для скриншотов — рабочий каталог, из которого запущен сервер, а не каталог, указанный в --directory. Чтобы зафиксировать его, задайте RIGOL_MCP_SCREENSHOT_DIR.

• Если в path передаётся относительный путь, он также отсчитывается от этого каталога по умолчанию. Сохранение вне каталога по умолчанию, RIGOL_MCP_ALLOWED_DIRS и временного каталога невозможно (будет отклонено).

Настройка (переменные окружения)

Все настройки можно задать через переменные окружения (также можно использовать TOML-файл конфигурации). Приоритет: аргументы Tool (указания пользователя в диалоге) > переменные окружения > файл конфигурации > встроенные значения по умолчанию.

Подробнее см. docs/Requirements.md, глава 9.

Попробовать без реального устройства

Если запустить с RIGOL_MCP_FAKE=1, сервер подключится к встроенному FakeScope вместо реального прибора. Это позволяет проверить настройки MCP на стороне хоста и диалоговый процесс без осциллографа.

RIGOL_MCP_FAKE=1 uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

Разработка

Версия Python управляется через mise, зависимости и виртуальное окружение — через uv.

mise install          # Python + uv
uv sync               # 依存の解決
uv run pytest         # ユニットテスト(実機不要)
uv run rigol-oscilloscope-mcp   # stdioで起動

Тесты с реальным прибором выполняются только если адрес подключения передан через переменную окружения (иначе автоматически пропускаются). Никогда не указывайте IP-адрес реального прибора в репозитории (tests/test_ip_guard.py проверяет это автоматически).

# read-only スイート(機器の設定を変更しない)
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> uv run pytest -m device

# write スイート(設定変更 → read-back → 必ず復元)。二重ゲート
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> RIGOL_TEST_ALLOW_WRITE=1 uv run pytest -m device_write

В <ваш IP осциллографа> подставьте адрес вашего прибора (если нужен пример, используйте зарезервированный для документации 192.0.2.x (TEST-NET-1)).

Устранение неполадок

Меры безопасности

Многие осциллографы RIGOL, включая MHO98, не имеют гальванической развязки (GND каждого входа общий с GND корпуса, USB и т. д., категория измерения Category I). Этот сервер предотвращает опасные изменения настроек, но не гарантирует электрическую безопасность как таковую.

• Точки подключения пробников, зажим заземления (Ground Clip), фактическое напряжение DUT, допустимое напряжение пробников и состояние изоляции невозможно проверить через MCP.

• Измерение сетевого питания (100 В AC, розетки, первичная сторона, AC mains) не поддерживается. Не выполняйте автоматически процедуры измерения обычными пассивными пробниками. Предполагается, что человек подтверждает использование дифференциальных или изолированных пробников.

• Обновление прошивки, калибровка, заводское обслуживание и изменение сетевых настроек не поддерживаются.

Подробнее см. docs/Requirements.md, глава 6 (требования безопасности).

Модель доверия для confirm-процедуры: двухэтапное подтверждение (confirm-токен) предназначено для предотвращения ошибок и поспешных действий LLM, а не для защиты от вредоносного MCP-хоста (токен возвращается тому же вызывающему, поэтому если сам хост злонамерен, он может просто вызвать дважды). Физическая безопасность может быть обеспечена только человеком, который управляет тем, что подключено. Кроме того, токен для enable_afg привязан к настройкам AFG на момент выдачи; если после выдачи изменить настройки (например, амплитуду), токен станет недействительным.

Отказ от ответственности: данное программное обеспечение предоставляется без каких-либо гарантий (LICENSE). Автор не несёт ответственности за повреждение измерительных приборов, объектов измерения (DUT) или периферийного оборудования, ошибки в результатах измерений и любые убытки, возникшие в результате использования данного программного обеспечения.

Лицензия

MIT License — Copyright (c) 2026 zinntikumugai

Документация

Список документов и порядок чтения приведены в docs/README.md.

• docs/Requirements.md — документ с требованиями (нормативный)

• docs/tools.md — каталог инструментов MCP

• docs/device-profiles.md — спецификация профилей устройств

• docs/verification/ — записи проверок на реальном оборудовании

• docs/roadmap.md — планы на будущее