Spec Workflow MCP

# Справочник инструментов Полная документация для всех инструментов MCP, предоставляемых Spec Workflow MCP. ## Обзор Spec Workflow MCP предоставляет специализированные инструменты для структурированной разработки программного обеспечения. Эти инструменты доступны AI-ассистентам через Model Context Protocol. ## Категории инструментов 1. **Руководства по рабочему процессу** - Документация и руководство 2. **Управление спецификациями** - Создание и управление спецификациями 3. **Контекстные инструменты** - Получение информации о проекте 4. **Инструменты управления** - Руководство на уровне проекта 5. **Инструменты утверждения** - Процесс утверждения документов ## Инструменты руководства по рабочему процессу ### spec-workflow-guide **Цель**: Предоставляет подробное руководство для процесса рабочего процесса на основе спецификаций. **Параметры**: Нет **Возвращает**: Markdown руководство, объясняющее полный рабочий процесс **Пример использования**: ``` "Покажи руководство по spec workflow" ``` **Ответ содержит**: - Обзор рабочего процесса - Пошаговый процесс - Лучшие практики - Примеры запросов ### steering-guide **Цель**: Руководство по созданию управляющих документов проекта. **Параметры**: Нет **Возвращает**: Markdown руководство для создания управляющих документов **Пример использования**: ``` "Покажи как создавать управляющие документы" ``` **Ответ содержит**: - Типы управляющих документов - Процесс создания - Рекомендации по содержанию - Примеры ## Инструменты управления спецификациями ### create-spec-doc **Цель**: Создает или обновляет документы спецификации (требования, дизайн, задачи). **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации (kebab-case) | | docType | string | Да | Тип: "requirements", "design" или "tasks" | | content | string | Да | Содержимое документа в Markdown | | revision | boolean | Нет | Является ли это ревизией (по умолчанию: false) | **Пример использования**: ```typescript { specName: "user-authentication", docType: "requirements", content: "# Требования аутентификации пользователей\n\n## Обзор\n...", revision: false } ``` **Возвращает**: ```typescript { success: true, message: "Документ требований успешно создан", path: ".spec-workflow/specs/user-authentication/requirements.md", requestedApproval: true } ``` **Примечания**: - Создает каталог спецификации, если не существует - Автоматически запрашивает утверждение для новых документов - Проверяет формат markdown - Сохраняет существующие документы при создании новых типов ### spec-list **Цель**: Перечисляет все спецификации с их текущим статусом. **Параметры**: Нет **Возвращает**: Массив сводок спецификаций **Структура ответа**: ```typescript [ { name: "user-authentication", status: "in-progress", progress: 45, documents: { requirements: "approved", design: "pending-approval", tasks: "not-created" }, taskStats: { total: 15, completed: 7, inProgress: 1, pending: 7 } } ] ``` **Пример использования**: ``` "Покажи все мои спецификации" ``` ### spec-status **Цель**: Получает детальную информацию о статусе для конкретной спецификации. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации для проверки | **Возвращает**: Детальный статус спецификации **Структура ответа**: ```typescript { exists: true, name: "user-authentication", documents: { requirements: { exists: true, approved: true, lastModified: "2024-01-15T10:30:00Z", size: 4523 }, design: { exists: true, approved: false, pendingApproval: true, lastModified: "2024-01-15T14:20:00Z", size: 6234 }, tasks: { exists: true, taskCount: 15, completedCount: 7, inProgressCount: 1, progress: 45 } }, overallProgress: 45, currentPhase: "implementation" } ``` **Пример использования**: ``` "Покажи статус спецификации user-authentication" ``` ### manage-tasks **Цель**: Комплексное управление задачами, включая обновления, изменения статуса и отслеживание прогресса. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации | | action | string | Да | Действие: "update", "complete", "list", "progress" | | taskId | string | Иногда | ID задачи (требуется для update/complete) | | status | string | Нет | Новый статус: "pending", "in-progress", "completed" | | notes | string | Нет | Дополнительные заметки для задачи | **Действия**: 1. **Обновить статус задачи**: ```typescript { specName: "user-auth", action: "update", taskId: "1.2.1", status: "in-progress", notes: "Начата реализация" } ``` 2. **Завершить задачу**: ```typescript { specName: "user-auth", action: "complete", taskId: "1.2.1" } ``` 3. **Список задач**: ```typescript { specName: "user-auth", action: "list" } ``` 4. **Получить прогресс**: ```typescript { specName: "user-auth", action: "progress" } ``` **Возвращает**: Информацию о задаче или подтверждение обновления ## Контекстные инструменты ### get-template-context **Цель**: Получает markdown шаблоны для всех типов документов. **Параметры**: Нет **Возвращает**: Объект, содержащий все шаблоны **Структура ответа**: ```typescript { requirements: "# Шаблон требований\n\n## Обзор\n...", design: "# Шаблон дизайна\n\n## Архитектура\n...", tasks: "# Шаблон задач\n\n## Задачи реализации\n...", product: "# Шаблон управления продуктом\n...", tech: "# Шаблон технического управления\n...", structure: "# Шаблон управления структурой\n..." } ``` **Пример использования**: ``` "Получи все шаблоны документов" ``` ### get-steering-context **Цель**: Получает управляющие документы проекта и руководство. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | docType | string | Нет | Конкретный документ: "product", "tech", "structure" или "all" | **Возвращает**: Содержимое управляющего документа **Пример использования**: ```typescript { docType: "tech" // Возвращает только техническое управление } ``` **Структура ответа**: ```typescript { product: "# Управление продуктом\n\n## Видение\n...", tech: "# Техническое управление\n\n## Архитектура\n...", structure: "# Управление структурой\n\n## Организация\n..." } ``` ### get-spec-context **Цель**: Получает полный контекст для конкретной спецификации. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации | | includeContent | boolean | Нет | Включить содержимое документа (по умолчанию: true) | **Возвращает**: Полный контекст спецификации **Структура ответа**: ```typescript { name: "user-authentication", exists: true, documents: { requirements: { exists: true, content: "# Требования\n\n...", approved: true }, design: { exists: true, content: "# Дизайн\n\n...", approved: false }, tasks: { exists: true, content: "# Задачи\n\n...", stats: { total: 15, completed: 7, progress: 45 } } }, relatedSpecs: ["user-profile", "session-management"], dependencies: ["database-setup", "auth-library"] } ``` **Пример использования**: ``` "Получи полный контекст для спецификации user-authentication" ``` ## Инструменты управляющих документов ### create-steering-doc **Цель**: Создает управляющие документы проекта (продукт, техническое, структура). **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | docType | string | Да | Тип: "product", "tech" или "structure" | | content | string | Да | Содержимое документа в Markdown | **Пример использования**: ```typescript { docType: "product", content: "# Управление продуктом\n\n## Видение\nСоздать лучший..." } ``` **Возвращает**: ```typescript { success: true, message: "Документ управления продуктом создан", path: ".spec-workflow/steering/product.md" } ``` **Примечания**: - Создает каталог управления при необходимости - Перезаписывает существующие управляющие документы - Утверждение не требуется для управляющих документов - Должно быть создано перед спецификациями ## Инструменты системы утверждения ### request-approval **Цель**: Запрашивает утверждение документа пользователем. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации | | docType | string | Да | Тип документа для утверждения | | documentId | string | Да | Уникальный ID для отслеживания | | content | string | Да | Содержимое документа для проверки | **Пример использования**: ```typescript { specName: "user-auth", docType: "requirements", documentId: "user-auth-req-v1", content: "# Требования\n\n..." } ``` **Возвращает**: ```typescript { success: true, approvalId: "user-auth-req-v1", message: "Утверждение запрошено. Проверьте панель управления для проверки." } ``` ### get-approval-status **Цель**: Проверяет статус утверждения документа. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации | | documentId | string | Да | ID документа для проверки | **Возвращает**: ```typescript { exists: true, status: "pending" | "approved" | "rejected" | "changes-requested", feedback: "Пожалуйста, добавьте больше деталей об обработке ошибок", timestamp: "2024-01-15T10:30:00Z", reviewer: "user" } ``` **Пример использования**: ``` "Проверь статус утверждения для требований user-auth" ``` ### delete-approval **Цель**: Удаляет завершенные запросы утверждения для очистки очереди утверждения. **Параметры**: | Параметр | Тип | Обязательный | Описание | |-----------|------|----------|-------------| | specName | string | Да | Имя спецификации | | documentId | string | Да | ID документа для удаления | **Возвращает**: ```typescript { success: true, message: "Запись утверждения удалена" } ``` **Пример использования**: ``` "Очисти завершенные утверждения для user-auth" ``` ## Паттерны интеграции инструментов ### Последовательный рабочий процесс Инструменты разработаны для работы в последовательности: 1. `steering-guide` → Изучить управление 2. `create-steering-doc` → Создать управляющие документы 3. `spec-workflow-guide` → Изучить рабочий процесс 4. `create-spec-doc` → Создать требования 5. `request-approval` → Запросить проверку 6. `get-approval-status` → Проверить статус 7. `create-spec-doc` → Создать дизайн (после утверждения) 8. `manage-tasks` → Отслеживать реализацию ### Параллельные операции Некоторые инструменты можно использовать одновременно: - `spec-list` + `spec-status` → Получить обзор и детали - `get-spec-context` + `get-steering-context` → Полный контекст проекта - Несколько `create-spec-doc` → Создать несколько спецификаций ### Обработка ошибок Все инструменты возвращают согласованные структуры ошибок: ```typescript { success: false, error: "Спецификация не найдена", details: "Спецификация с именем 'invalid-spec' не существует", suggestion: "Используйте spec-list для просмотра доступных спецификаций" } ``` ## Лучшие практики ### Выбор инструмента 1. **Сбор информации**: - Используйте `spec-list` для обзора - Используйте `spec-status` для конкретной спецификации - Используйте `get-spec-context` для реализации 2. **Создание документов**: - Всегда создавайте требования сначала - Ждите утверждения перед дизайном - Создавайте задачи после утверждения дизайна 3. **Управление задачами**: - Обновляйте статус при начале задач - Отмечайте как выполненные сразу после завершения - Используйте заметки для важного контекста ### Соображения производительности - **Пакетные операции**: Запрашивайте несколько спецификаций в одном разговоре - **Кэширование**: Инструменты кэшируют чтение файлов для производительности - **Выборочная загрузка**: Используйте `includeContent: false` для более быстрой проверки статуса ### Безопасность - **Валидация пути**: Все пути проверяются и санитизируются - **Изоляция проекта**: Инструменты обращаются только к каталогу проекта - **Санитизация ввода**: Содержимое Markdown санитизируется - **Без выполнения**: Инструменты никогда не выполняют код ## Связанная документация - [Руководство пользователя](USER-GUIDE.ru.md) - Эффективное использование инструментов - [Процесс рабочего процесса](WORKFLOW.ru.md) - Использование инструментов в рабочем процессе - [Руководство по запросам](PROMPTING-GUIDE.ru.md) - Примеры использования инструментов - [Руководство по разработке](DEVELOPMENT.ru.md) - Добавление новых инструментов