schematic-mcp

Контекст аппаратных схем для ИИ-агентов через MCP.

schematic-mcp позволяет MCP-совместимым агентам анализировать аппаратные схемы как структурированные электрические данные, а не обрабатывать их как скриншоты или длинные текстовые блоки.

Статус: V0.1 / alpha. Первый адаптер нацелен на современные файлы KiCad .kicad_sch.

Зачем это существует

ИИ-агенту, пишущему прошивку, часто нужны ответы на такие вопросы:

• Какой пин ESP32 подключён к SENSOR_OUT?

• Что подключено к U4.GPIO12?

• Какие устройства используют эту I2C-сеть?

• Каковы все пины и разрешённые сети на микроконтроллере?

• Соответствует ли карта GPIO, предполагаемая прошивкой, фактической схеме?

Сервер детерминированно разбирает EDA-файл, строит каноническую модель компонентов/пинов/сетей и предоставляет эту модель через инструменты и ресурсы MCP.

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

Фокус проектирования

schematic-mcp намеренно является файловым слоем аппаратного контекста, а не универсальным сервером автоматизации EDA GUI. Обычные рабочие процессы чтения/запросов KiCad не требуют запущенного приложения KiCad. Специфичные для EDA адаптеры создают канонический электрический граф, в то время как контракт MCP для агентов остаётся нейтральным к формату.

Это делает проект дополняющим автоматизацию редактора/IPC: инструменты редактора ценны для интерактивных изменений в проектировании, тогда как schematic-mcp фокусируется на детерминированных аппаратных фактах, которые могут потреблять агенты кодирования, CI-системы и будущие кросс-EDA адаптеры. Проверка соответствия прошивки и схемы — первый конкретный вариант использования.

См. docs/project-positioning.md о границах проекта и экосистемной концепции.

Related MCP server: mcp-kicad-sch-api

Возможности V0.1

• Разбор современных файлов KiCad .kicad_sch в формате S-выражений

• Чтение компонентов, ссылок, значений и идентификаторов библиотек

• Преобразование геометрии пинов библиотеки в координаты схемы

• Выбор пинов по активной единице KiCad для символов с несколькими единицами

• Построение связности по проводам, меткам и соединениям

• Разрешение именованных и анонимных сетей

• Просмотр одного компонента или пина

• Трассировка пина до всех конечных точек в той же электрической сети

• Генерация компактных карт пинов MCU

• Сравнение ожиданий прошивки по пинам с сетями схемы по физическому номеру пина или символическому имени пина

• Предоставление текущей канонической модели как ресурсов MCP

• Ограничение доступа к файловой системе с помощью SCHEMATIC_MCP_ROOT или --root

• Локальный запуск через stdio или Streamable HTTP

• Автоматизированные тесты парсера, графа и границ файловой системы в GitHub Actions

Инструменты MCP

Ресурсы:

• schematic://current/summary

• schematic://current/model

Установка из GitHub

Требуется Python 3.10+. До выхода первого релиза в реестре пакетов текущую ветку main можно установить напрямую из GitHub:

python -m pip install "git+https://github.com/vonpanda/schematic-mcp.git"
schematic-mcp --help

Для воспроизводимого продакшена зафиксируйте тег релиза или коммит, а не отслеживайте незакреплённую ветку разработки. Первый пакетный релиз отслеживается в issue #8.

Установка для разработки

git clone https://github.com/vonpanda/schematic-mcp.git
cd schematic-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Проект использует стабильную линию v2 официального MCP Python SDK.

Запуск

Локальный stdio

schematic-mcp

или:

python -m schematic_mcp

Вы можете ограничить читаемые файлы без установки переменной окружения:

schematic-mcp --root /absolute/path/to/your/hardware-projects

Попробуйте встроенный фикстур

Репозиторий содержит небольшую синтетическую схему KiCad, безопасную для демонстраций и тестов:

schematic-mcp --root "$PWD/examples"

Затем MCP-совместимый клиент может вызвать:

open_schematic("minimal.kicad_sch")
schematic_summary()
list_components()
trace_signal("U1", "1")

Пример должен разрешить U1.1 на SENSOR_OUT и показать U2.1 как другую конечную точку. См. examples/README.md.

Демонстрация проверки прошивки ↔ схемы

Второй синтетический пример демонстрирует аппаратную ошибку, которую агент кодирования не может безопасно обнаружить только по исходному коду. Прошивка намеренно меняет местами назначения GPIO SENS_INT и LED_STATUS, в то время как схема сохраняет правильное электрическое сопоставление.

Запустите детерминированную локальную демонстрацию:

python examples/demo_firmware_validation.py

Она извлекает простой контракт GPIO из examples/firmware_with_pin_bug.c, разбирает examples/esp32_firmware_validation.kicad_sch и сообщает два совпадения и два несовпадения.

Через MCP то же сравнение выглядит так:

open_schematic("esp32_firmware_validation.kicad_sch")
validate_pinmap(
  "U1",
  {
    "GPIO8": "I2C_SDA",
    "GPIO9": "I2C_SCL",
    "GPIO12": "LED_STATUS",
    "GPIO13": "SENSOR_INT"
  }
)

См. docs/firmware-validation-demo.md для полного рабочего процесса агента и ожидаемого результата.

Streamable HTTP

schematic-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Конечная точка MCP доступна по адресу http://127.0.0.1:8000/mcp. Хост по умолчанию — только loopback; не выставляйте неаутентифицированный сервер разработки напрямую в публичный интернет.

Для MCP Inspector:

mcp dev src/schematic_mcp/server.py

Пример конфигурации MCP-клиента

{
  "mcpServers": {
    "schematic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/schematic-mcp", "run", "schematic-mcp"],
      "env": {"SCHEMATIC_MCP_ROOT": "/absolute/path/to/your/hardware-projects"}
    }
  }
}

Затем агент может вызвать:

open_schematic("board/main.kicad_sch")
get_component("U4")
get_mcu_pinmap("U4")
trace_signal("U4", "12")

Безопасность файловой системы

По умолчанию локальный сервер может открывать пути, доступные его процессу. Для агентов, которым вы не полностью доверяете, установите SCHEMATIC_MCP_ROOT или передайте --root в разрешённую директорию проекта. Попытки открыть файлы за её пределами отклоняются, включая пути, которые разрешаются за пределами разрешённого корня.

См. SECURITY.md для отчётов об уязвимостях и рекомендаций по развёртыванию.

Текущие ограничения

V0.1 намеренно мал. Иерархические дочерние листы обнаруживаются, но пока не рекурсивно объединяются в один граф между листами. Необычные конструкции с несколькими единицами/библиотеками и экспорт KiCad от третьих сторон всё ещё требуют более широких фикстур совместимости. Семантика шин пока не восстанавливается. PDF, Altium и EasyEDA пока не реализованы.

trace_signal следует только разрешённой связности сети; он не предполагает, что отдельные пины внутри ИС электрически соединены. validate_pinmap сравнивает явное ожидаемое сопоставление; автоматическое извлечение из произвольных фреймворков прошивки пока не является частью основного парсера.

Дорожная карта

• V0.2 — иерархический граф проекта KiCad и более богатая семантика шин/сетей

• V0.3 — адаптер PDF/векторных схем с метаданными уверенности

• V0.4 — адаптеры Altium и EasyEDA

• V0.5 — контекст даташитов и рассуждения об электрических правилах

• V0.6 — извлечение прошивки для конкретных фреймворков (ESP-IDF/Arduino/Zephyr) и проверки контрактов пинов в CI

• Позже — PCB, BOM, Gerber и производственный контекст

Долгосрочная цель — нейтральный к вендору сервер аппаратного контекста для ИИ-агентов.

Вклад

Инженеры по аппаратному обеспечению, разработчики встраиваемых систем и пользователи EDA могут больше всего помочь, внося минимальные фикстуры совместимости, крайние случаи парсера, тесты и реальные рабочие процессы агентов.

Начните с CONTRIBUTING.md. Агенты кодирования и мейнтейнеры также должны прочитать AGENTS.md для инвариантов архитектуры, ограничений безопасности и ожидаемого цикла разработки. Пожалуйста, никогда не вносите проприетарные схемы клиентов без явного разрешения на их публикацию.

Полезные документы мейнтейнера/проекта:

• AGENTS.md — правила для агентов кодирования и мейнтейнеров

• docs/project-positioning.md — границы проекта и ценность экосистемы

• docs/architecture.md — архитектура парсера/модели/MCP

• docs/firmware-validation-demo.md — демонстрация несоответствия прошивки ↔ схемы

• examples/README.md — запускаемые синтетические фикстуры

• CHANGELOG.md — история релизов

• SECURITY.md — политика безопасности

• docs/oss-readiness.md — чек-лист готовности к публичному принятию и OSS-программам

Лицензия и атрибуция

Лицензировано под Apache License 2.0. Коммерческое использование, модификация и распространение разрешены в соответствии с условиями лицензии. Распространение должно сохранять применимую информацию об авторских правах, лицензии и NOTICE, как требуется Apache-2.0.

См. LICENSE и NOTICE.

Первоначально разработано под SYANKOR.