# verilator-mcp

[English](README.en.md) · [Участие в разработке](CONTRIBUTING.md) · [Безопасность](SECURITY.md)

Переносимый локальный MCP-сервер для симуляции, диагностики и верификации RTL с Verilator.

> **Статус: bootstrap / экспериментальный (0.0.1).** Проект содержит проверяемый каркас MCP, безвредное обнаружение установленного инструмента и ограниченный разбор текстовых диагностик. Он **пока не запускает** синтез или симуляцию и не может подтверждать работоспособность коммерческих инструментов. См. [план](docs/ROADMAP.md).

## Для чего нужен

Сборка и запуск SystemVerilog-тестбенчей, воспроизводимые регрессии и структурированные результаты.

**Принципы:** отдельно от `agent-dev-toolkit`; свободная установка из исходников; никаких встроенных EDA-бинарников, лицензий, облачных запросов и непрошеных изменений файлов проекта. Каждая команда имеет ограниченную область доступа и возвращает наблюдаемые доказательства, а не догадки.

## Быстрый старт

Нужен Python 3.11+ и установленный `uv`. Для самого MCP-сервера нужен совместимый MCP SDK v2.3.0; SDK будет установлен в локальное виртуальное окружение при выполнении `uv sync`.

```bash
git clone https://github.com/chinn-choppa/verilator-mcp.git
cd verilator-mcp
uv sync
uv run verilator-mcp
```

Локальная конфигурация клиента MCP (пример структуры; конкретный путь к `uv`/проекту и формат конфигурации зависят от клиента):

```json
{
  "mcpServers": {
    "verilator-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/verilator-mcp", "run", "verilator-mcp"]
    }
  }
}
```

Это пример для клиентов с ключом `mcpServers`; Codex и OpenCode используют собственные схемы. Все пути должны указывать на доверенную локальную копию.

## Доступные инструменты прототипа

| Tool | Назначение | Граница |
| --- | --- | --- |
| `server_info` | Идентификатор сервера, состояние, ограничения | Только чтение |
| `tool_status` | Поиск установленного `verilator` или пути из переменной `VERILATOR_MCP_EXECUTABLE` | Не запускает EDA-продукт |
| `parse_diagnostics` | Выделение диагностических сообщений из переданного текста | До 1 МиБ и 200 записей |

В первом выпуске не выполняются команды lint/simulate: для них требуется отдельный обзор безопасности и тесты на реальном Verilator.

## Воспроизводимые проверки

```bash
python -m unittest discover -s tests -v
python -m compileall -q src tests
```

После `uv sync` проверьте запуск `uv run verilator-mcp` с MCP Inspector или настоящим MCP-клиентом. Одна лишь установка или `tools/list` **не доказывает** успешное выполнение EDA-команды. До появления соответствующих реализаций состояние таких проверок — `NOT_RUN`.

## Ограничения

Verilator не является полной заменой четырёхсостояниевой симуляции. Его успешный запуск не доказывает эквивалентность Questa.

См. [архитектуру](docs/ARCHITECTURE.md), [совместимость](docs/COMPATIBILITY.md), [контракт результатов](docs/TOOL_CONTRACT.md), [тестирование](docs/TESTING.md) и [дорожную карту](docs/ROADMAP.md).

## Лицензия

Apache License 2.0. Настоящий репозиторий не связан с производителем Verilator и не является его официальным продуктом.