Полная инструкция: Claude Code + Vivado MCP для Windows

Содержание

  1. Обзор
  2. Установка Claude Code
  3. Настройка DeepSeek API
  4. Установка навыка xilinx-suite
  5. Установка Python и vivado-mcp
  6. Настройка MCP в Claude Code
  7. Какие окна должны быть открыты постоянно
  8. Запуск и проверка
  9. Режимы работы сессии
  10. Полезные команды
  11. Возможные проблемы
  12. Итоговая схема работы

1. Обзор

Данная инструкция описывает полный цикл настройки Claude Code на Windows для работы с Vivado 2025.2 через MCP-сервер vivado-mcp. В результате вы получите:

  • Claude Code, подключённый к DeepSeek API;
  • навык xilinx-suite для генерации корректных Tcl-скриптов и XDC-ограничений;
  • MCP-сервер vivado-mcp, позволяющий Claude напрямую управлять Vivado;
  • работающую связку: Claude Code ↔ vivado-mcp ↔ Vivado GUI.

Архитектура

┌─────────────────┐         ┌──────────────────────┐
│   Claude Code   │  MCP    │    vivado-mcp        │
│  (окно 1)       │◄───────►│  (Python-процесс)    │
│  + навык        │         │                      │
│  xilinx-suite   │         │                      │
└─────────────────┘         └──────────┬───────────┘
                                       │ TCP :9999
                                       ▼
                            ┌──────────────────────┐
                            │   Vivado GUI         │
                            │  (окно 2, постоянно  │
                            │   открыто)           │
                            └──────────────────────┘

2. Установка Claude Code

2.1. Системные требования

  • Windows 10/11 (Windows 10 1809+ или Windows Server 2019+).
  • Git for Windows (рекомендуется; без него Claude Code использует PowerShell вместо Git Bash).

2.2. Установка через PowerShell

Откройте PowerShell и выполните:

irm https://claude.ai/install.ps1 | iex

Альтернативный способ через WinGet:

winget install Anthropic.ClaudeCode

2.3. Проверка установки

claude --version

3. Настройка DeepSeek API

3.1. Получение API-ключа

Зарегистрируйтесь на платформе DeepSeek и создайте API-ключ: https://platform.deepseek.com/api_keys.

3.2. Рабочая конфигурация

Файл C:\Users\<ваше_имя>\.claude\settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-<ваш ключ DeepSeek>",
    "ANTHROPIC_MODEL": "claude-opus[1m]"
  },
  "extraKnownMarketplaces": {
    "xilinx-skill": {
      "source": {
        "source": "github",
        "repo": "QingquanYao/xilinx-skill"
      }
    }
  },
  "autoUpdatesChannel": "latest",
  "theme": "dark",
  "enabledPlugins": {
    "xilinx-suite@xilinx-skill": true
  }
}

Важно: именно такая структура подтверждена как рабочая. Обратите внимание:

  • Секция env содержит только три переменные: ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL.
  • Переменные ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL и т.д. не нужны — они не влияют на работу через DeepSeek.
  • Значение ANTHROPIC_MODEL — claude-opus[1m]. Это внутренняя метка Claude Code; DeepSeek автоматически маршрутизирует её на deepseek-v4-pro.
  • enabledPlugins с xilinx-suite@xilinx-skill: true активирует навык без ручного /reload-plugins.

После сохранения перезапустите терминал.

3.3. Проверка подключения

Запустите Claude Code и введите /status. Убедитесь, что Anthropic base URL указывает на https://api.deepseek.com/anthropic.

4. Установка навыка xilinx-suite

Навык xilinx-suite даёт Claude Code знания о Vivado, Vitis HLS, Vitis Unified и PetaLinux. Без него Claude не знает синтаксис Tcl-скриптов, XDC-ограничений и структуру проектов Xilinx.

4.1. Добавление marketplace

В сессии Claude Code выполните:

/plugin marketplace add QingquanYao/xilinx-skill

Эта команда добавит запись в extraKnownMarketplaces вашего settings.json.

4.2. Установка плагина

/plugin install xilinx-suite@xilinx-skill

При выборе области установки выберите Install for you (user scope).

После установки в settings.json автоматически появится секция:

"enabledPlugins": {
  "xilinx-suite@xilinx-skill": true
}

4.3. Проверка активации

/plugin list

В списке должен быть xilinx-suite со статусом enabled.

5. Установка Python и vivado-mcp

5.1. Установка Python 3.10–3.12

Откройте PowerShell от имени администратора:

winget install -e --id Python.Python.3.11 --scope machine

Перезапустите PowerShell и проверьте:

python --version

5.2. Создание виртуального окружения

cd C:\Users\admin
python -m venv vivado-mcp-env

Если активация блокируется политикой:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Активируйте окружение:

.\vivado-mcp-env\Scripts\activate

5.3. Установка vivado-mcp

python -m pip install vivado-mcp

5.4. Инъекция в Vivado

Укажите путь к вашему Vivado и выполните инъекцию:

$env:VIVADO_PATH = "C:\FPGA\2025.2\Vivado\bin\vivado.bat"
vivado-mcp install --port 9999

Важно: путь должен указывать именно на bin\vivado.bat. Не указывайте bin\vivado (это shell-скрипт для Linux) и внутренние исполняемые файлы из каталога unwrapped. Если Vivado установлен в защищённый каталог (например, C:\Program Files\), запустите PowerShell от имени администратора.

5.5. Диагностика

vivado-mcp doctor

Ожидаемый результат (при закрытом GUI Vivado):

[OK]   vivado_executable: Vivado найден
[OK]   vivado_init_tcl: инъекция выполнена и актуальна
[WARN] vivado_tcp_server: GUI Vivado не запущен — это нормально
overall: warning (exit 1)
  • vivado_executable: OK — путь к Vivado определён верно;
  • vivado_init_tcl: OK — инъекция в Vivado_init.tcl выполнена;
  • vivado_tcp_server: WARN — нормально, если GUI Vivado не запущен.

6. Настройка MCP в Claude Code

6.1. Автоматическая настройка

vivado-mcp doctor --fix --client all

Эта команда пропишет MCP-конфигурацию в C:\Users\admin\.claude.json.

6.2. Ручная настройка (если --fix не сработал)

Откройте C:\Users\admin\.claude.json и добавьте в mcpServers:

"vivado": {
  "command": "C:/Users/admin/vivado-mcp-env/Scripts/python.exe",
  "args": ["-m", "vivado_mcp"],
  "env": {
    "VIVADO_PATH": "C:/FPGA/2025.2/Vivado/bin/vivado.bat"
  },
  "type": "stdio"
}

Важно: путь к python.exe должен указывать на виртуальное окружение vivado-mcp-env.

7. Какие окна должны быть открыты постоянно

7.1. Два обязательных окна

Окно Что там должно быть запущено Назначение
Окно Vivado Vivado GUI с автоматически запущенным TCP-сервером на порту 9999 Принимает команды от Claude Code через TCP-соединение
Окно Claude Code Claude Code с подключённым MCP-сервером vivado и активным навыком xilinx-suite Отправляет команды в Vivado через MCP

7.2. Как запустить TCP-сервер в Vivado

Способ 1: автоматически (рекомендуется). После выполнения vivado-mcp install TCP-сервер запускается автоматически при каждом старте Vivado GUI. Просто откройте Vivado — сервер поднимется сам.

Способ 2: вручную (если нужно). В Tcl-консоли Vivado выполните:

::vmcp::start

Если команда не найдена, загрузите скрипт вручную:

source "C:/Users/admin/vivado-mcp-env/Lib/site-packages/vivado_mcp/scripts/vivado_mcp_server.tcl"
::vmcp::start

7.3. Что вы должны увидеть

В Tcl-консоли Vivado при успешном запуске сервера появится:

vivado-mcp server ready on port 9999

8. Запуск и проверка

8.1. Запустите Vivado GUI

Откройте Vivado вручную (или он запустится автоматически при первом запросе от Claude). Дождитесь, пока в Tcl-консоли появится сообщение о запуске TCP-сервера.

8.2. Запустите Claude Code

cd D:\projects\xilinx\AC7020C\forth
claude

8.3. Проверка связи

В чате Claude Code попросите:

«Подключись к Vivado на порту 9999 и покажи версию»

Claude вызовет start_session(mode="attach", port=9999), подключится к вашему работающему Vivado и вернёт номер версии.

8.4. Проверка навыка Xilinx

Спросите Claude:

«Создай проект Vivado для Zynq-7020 с PS и двумя AXI GPIO»

Если навык xilinx-suite активен, Claude сгенерирует корректные Tcl-команды с учётом особенностей Zynq-7000.

9. Режимы работы сессии

vivado-mcp поддерживает три режима:

Режим Что делает Когда использовать
gui (по умолчанию) Проверяет порт 9999: если сервер есть — подключается (attach), если нет — запускает новый GUI Интерактивная разработка, наблюдение за дизайном
tcl Запускает Vivado в Tcl-режиме без GUI CI/CD, пакетная обработка, скорость
attach Только подключается к существующей сессии, не запускает новую Строгая гарантия, что новый GUI не будет запущен

10. Полезные команды

Команда Назначение
/plugin Управление плагинами Claude Code
/reload-plugins Активация плагина без перезапуска
/mcp Статус MCP-серверов
/status Проверка конфигурации Claude Code
vivado-mcp doctor Диагностика окружения
vivado-mcp doctor --fix Автоисправление конфигурации
vivado-mcp uninstall Удаление инъекции из Vivado

11. Возможные проблемы

Проблема Решение
pip не распознан Установите Python с галочкой «Add to PATH»
Ошибка 2503 при установке Используйте winget вместо MSI
Активация venv заблокирована Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
MCP не видит Vivado Проверьте путь в VIVADO_PATH, используйте прямые слеши /
TCP-сервер не запускается Проверьте инъекцию: vivado-mcp doctor → vivado_init_tcl должен быть OK
Порт 9999 занят vivado-mcp install --port <другой_порт>
Навык Xilinx не активируется Проверьте: /plugin list → xilinx-suite должен быть в списке
Claude Code не видит vivado-mcp Проверьте /mcp → сервер vivado должен быть connected

12. Итоговая схема работы

┌─────────────────┐         ┌──────────────────────┐
│   Claude Code   │  MCP    │    vivado-mcp        │
│  (окно 1)       │◄───────►│  (Python-процесс)    │
│  + навык        │         │                      │
│  xilinx-suite   │         │                      │
└─────────────────┘         └──────────┬───────────┘
                                       │ TCP :9999
                                       ▼
                            ┌──────────────────────┐
                            │   Vivado GUI         │
                            │  (окно 2, постоянно  │
                            │   открыто)           │
                            └──────────────────────┘

Ключевое правило: окно Vivado должно быть открыто постоянно во время работы с Claude Code. TCP-сервер живёт внутри Vivado и умирает вместе с ним.

Приложение: Совместимость версий Vivado

Версия Vivado Статус совместимости с vivado-mcp
2019.1 Основная база (полное тестирование)
2018.3 Частично проверена
2022.2 Проверена сообществом
2025.2 Экспериментальная совместимость