Spec Workflow MCP

# Руководство по конфигурации Это руководство охватывает все параметры конфигурации для Spec Workflow MCP. ## Параметры командной строки ### Базовое использование ```bash npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options] ``` ### Доступные параметры | Параметр | Описание | Пример | |--------|-------------|---------| | `--help` | Показать подробную информацию об использовании | `npx -y @pimzino/spec-workflow-mcp@latest --help` | | `--dashboard` | Запустить только панель управления (порт по умолчанию: 5000) | `npx -y @pimzino/spec-workflow-mcp@latest --dashboard` | | `--port <number>` | Указать пользовательский порт панели управления (1024-65535) | `npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080` | ### Важные замечания - **Один экземпляр панели управления**: Запускается только одна панель управления одновременно. Все серверы MCP подключаются к одной панели. - **Порт по умолчанию**: Панель управления использует порт 5000 по умолчанию. Используйте `--port` только если 5000 недоступен. - **Отдельная панель управления**: Всегда запускайте панель управления отдельно от серверов MCP. ## Примеры использования ### Типичный рабочий процесс 1. **Запустите панель управления** (сделайте это первым, только один раз): ```bash # Использует порт 5000 по умолчанию npx -y @pimzino/spec-workflow-mcp@latest --dashboard ``` 2. **Запустите серверы MCP** (по одному на проект, в отдельных терминалах): ```bash # Проект 1 npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1 # Проект 2 npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2 # Проект 3 npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3 ``` Все проекты появятся на панели управления по адресу http://localhost:5000 ### Панель управления с пользовательским портом Используйте пользовательский порт только если порт 5000 недоступен: ```bash # Запустить панель управления на порту 8080 npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080 ``` ## Переменные окружения ### SPEC_WORKFLOW_HOME Переопределяет каталог глобального состояния по умолчанию (`~/.spec-workflow-mcp`). Это полезно для изолированных сред, где `$HOME` доступен только для чтения. | Переменная | По умолчанию | Описание | |----------|---------|-------------| | `SPEC_WORKFLOW_HOME` | `~/.spec-workflow-mcp` | Каталог для глобальных файлов состояния | **Файлы, хранящиеся в этом каталоге:** - `activeProjects.json` - Реестр проектов - `activeSession.json` - Информация о сеансе панели управления - `settings.json` - Глобальные настройки - `job-execution-history.json` - История выполнения задач - `migration.log` - Отслеживание миграции журнала реализации **Примеры использования:** ```bash # Абсолютный путь SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace # Относительный путь (разрешается относительно текущего рабочего каталога) SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest . # Для режима панели управления SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard ``` **Изолированные среды (например, Codex CLI):** При работе в изолированных средах, таких как Codex CLI с `sandbox_mode=workspace-write`, установите `SPEC_WORKFLOW_HOME` на доступное для записи место в вашем рабочем пространстве: ```bash SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace ``` ## Управление сеансом панели управления Панель управления хранит информацию о сеансе в `~/.spec-workflow-mcp/activeSession.json` (или `$SPEC_WORKFLOW_HOME/activeSession.json`, если установлено). Этот файл: - Обеспечивает один экземпляр панели управления - Позволяет серверам MCP обнаружить работающую панель управления - Автоматически очищается при остановке панели управления ### Обеспечение одного экземпляра Только одна панель управления может работать одновременно. Если вы попытаетесь запустить вторую панель управления: ``` Dashboard is already running at: http://localhost:5000 You can: 1. Use the existing dashboard at: http://localhost:5000 2. Stop it first (Ctrl+C or kill PID), then start a new one Note: Only one dashboard instance is needed for all your projects. ``` ## Управление портами **Порт по умолчанию**: 5000 **Пользовательский порт**: Используйте `--port <number>` только если порт 5000 недоступен ### Конфликты портов Если порт 5000 уже используется другим сервисом: ```bash Failed to start dashboard: Port 5000 is already in use. This might be another service using port 5000. To use a different port: spec-workflow-mcp --dashboard --port 8080 ``` ## Конфигурационный файл (устарело) ### Расположение по умолчанию Сервер ищет конфигурацию по адресу: `<project-dir>/.spec-workflow/config.toml` ### Формат файла Конфигурация использует формат TOML. Вот полный пример: ```toml # Каталог проекта (по умолчанию текущий каталог) projectDir = "/path/to/your/project" # Порт панели управления (1024-65535) port = 3456 # Запустить режим только панели управления dashboardOnly = false # Язык интерфейса # Варианты: en, ja, zh, es, pt, de, fr, ru, it, ko, ar lang = "en" # Звуковые уведомления (только расширение VSCode) [notifications] enabled = true volume = 0.5 # Дополнительные настройки [advanced] # Попытки повторного подключения WebSocket maxReconnectAttempts = 10 # Настройки наблюдателя файлов [watcher] enabled = true debounceMs = 300 ``` ### Параметры конфигурации #### Базовые настройки | Параметр | Тип | По умолчанию | Описание | |--------|------|---------|-------------| | `projectDir` | string | Текущий каталог | Путь к каталогу проекта | | `port` | number | Эфемерный | Порт панели управления (1024-65535) | | `dashboardOnly` | boolean | false | Запустить панель управления без сервера MCP | | `lang` | string | "en" | Язык интерфейса | > **Примечание**: Параметр `autoStartDashboard` был удален в версии 2.0.0. Панель управления теперь использует унифицированный многопроектный режим, доступный через флаг `--dashboard`. #### Языковые параметры - `en` - English - `ja` - Japanese (日本語) - `zh` - Chinese (中文) - `es` - Spanish (Español) - `pt` - Portuguese (Português) - `de` - German (Deutsch) - `fr` - French (Français) - `ru` - Russian (Русский) - `it` - Italian (Italiano) - `ko` - Korean (한국어) - `ar` - Arabic (العربية) ### Создание пользовательской конфигурации 1. Скопируйте пример конфигурации: ```bash cp .spec-workflow/config.example.toml .spec-workflow/config.toml ``` 2. Отредактируйте конфигурацию: ```toml # Конфигурация моего проекта projectDir = "/Users/myname/projects/myapp" port = 3000 lang = "en" ``` 3. Используйте конфигурацию: ```bash # Использует .spec-workflow/config.toml автоматически npx -y @pimzino/spec-workflow-mcp@latest # Или укажите явно npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml ``` ## Приоритет конфигурации Значения конфигурации применяются в следующем порядке (от наивысшего к низшему приоритету): 1. **Аргументы командной строки** - Всегда имеют приоритет 2. **Пользовательский конфигурационный файл** - Указанный с `--config` 3. **Конфигурационный файл по умолчанию** - `.spec-workflow/config.toml` 4. **Встроенные значения по умолчанию** - Резервные значения ### Пример приоритета ```toml # config.toml port = 3000 ``` ```bash # Аргумент командной строки переопределяет конфигурационный файл npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000 # Результат: port = 4000 (CLI выигрывает) ``` ## Конфигурации для конкретных сред ### Конфигурация для разработки ```toml # dev-config.toml projectDir = "./src" port = 3000 lang = "en" [advanced] debugMode = true verboseLogging = true ``` Использование: ```bash npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml ``` ### Производственная конфигурация ```toml # prod-config.toml projectDir = "/var/app" port = 8080 lang = "en" [advanced] debugMode = false verboseLogging = false ``` Использование: ```bash npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml ``` ## Конфигурация порта ### Допустимый диапазон портов Порты должны быть в диапазоне от 1024 до 65535. ### Эфемерные порты Когда порт не указан, система автоматически выбирает доступный эфемерный порт. Это рекомендуется для: - Сред разработки - Нескольких одновременных проектов - Избежания конфликтов портов ### Фиксированные порты Используйте фиксированные порты, когда вам нужно: - Последовательные URL для закладок - Интеграция с другими инструментами - Совместная работа в команде с общими конфигурациями ### Разрешение конфликтов портов Если порт уже используется: 1. **Проверьте, что использует порт:** - Windows: `netstat -an | findstr :3000` - macOS/Linux: `lsof -i :3000` 2. **Решения:** - Используйте другой порт: `--port 3001` - Завершите процесс, использующий порт - Пропустите `--port` для использования эфемерного порта ## Настройка нескольких проектов ### Отдельные конфигурации Создайте конфигурации для конкретных проектов: ```bash # Проект A project-a/ .spec-workflow/ config.toml # port = 3000 # Проект B project-b/ .spec-workflow/ config.toml # port = 3001 ``` ### Общая конфигурация Используйте общую конфигурацию с переопределениями: ```bash # Общая базовая конфигурация ~/configs/spec-workflow-base.toml # Переопределения для конкретных проектов npx -y @pimzino/spec-workflow-mcp@latest \ --config ~/configs/spec-workflow-base.toml \ --port 3000 \ /path/to/project-a ``` ## Конфигурация расширения VSCode Расширение VSCode имеет свои настройки: 1. Откройте настройки VSCode (Cmd/Ctrl + ,) 2. Найдите "Spec Workflow" 3. Настройте: - Языковые предпочтения - Звуковые уведомления - Видимость архива - Интервал автообновления ## Устранение проблем с конфигурацией ### Конфигурация не загружается 1. **Проверьте расположение файла:** ```bash ls -la .spec-workflow/config.toml ``` 2. **Проверьте синтаксис TOML:** ```bash # Установите инструмент TOML CLI npm install -g @iarna/toml # Проверьте toml .spec-workflow/config.toml ``` 3. **Проверьте права доступа:** ```bash # Убедитесь, что файл доступен для чтения chmod 644 .spec-workflow/config.toml ``` ### Распространенные проблемы | Проблема | Решение | |-------|----------| | Порт уже используется | Используйте другой порт или пропустите для эфемерного | | Конфигурационный файл не найден | Проверьте путь и используйте абсолютный путь при необходимости | | Неверный синтаксис TOML | Проверьте с помощью TOML линтера | | Настройки не применяются | Проверьте приоритет конфигурации | ## Лучшие практики 1. **Используйте контроль версий** для конфигурационных файлов 2. **Документируйте пользовательские настройки** в README вашего проекта 3. **Используйте эфемерные порты** в разработке 4. **Храните конфиденциальные данные** вне конфигурационных файлов 5. **Создавайте конфигурации для конкретных сред** 6. **Тестируйте изменения конфигурации** перед развертыванием ## Связанная документация - [Руководство пользователя](USER-GUIDE.ru.md) - Использование настроенного сервера - [Руководство по интерфейсам](INTERFACES.ru.md) - Настройки панели управления и расширения - [Устранение неполадок](TROUBLESHOOTING.ru.md) - Распространенные проблемы конфигурации