@vitalyostanin/youtrack-mcp 0.10.0 → 0.10.2

package/README-ru.md

@@ -43,12 +43,13 @@ MCP сервер для полноценной интеграции с YouTrack
     - [Сервис](#сервис)
     - [Задачи](#задачи)
     - [Связи задач](#связи-задач)
+    - [Статусы задач](#статусы-задач)
     - [Звездочки задач](#звездочки-задач)
+    - [Вложения](#вложения)
     - [Трудозатраты](#трудозатраты)
     - [Пользователи и проекты](#пользователи-и-проекты)
     - [Статьи](#статьи)
     - [Лента активности](#лента-активности)
-    - [Вложения](#вложения)
 
 ## Требования
 
@@ -274,10 +275,12 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 ### Параметры сохранения файлов
 
-Многие инструменты поддерживают опциональные параметры `saveToFile` и `filePath` для работы с большими датасетами:
+Многие инструменты поддерживают опциональные параметры сохранения файлов для работы с большими датасетами:
 
 - `saveToFile` — boolean, сохраняет результаты в JSON файл вместо возврата напрямую (полезно для больших датасетов)
 - `filePath` — string, пользовательский путь к файлу (опционально, генерируется автоматически если не указан, директория создается при необходимости)
+- `format` — string, формат вывода при сохранении в файл: `jsonl` (JSON Lines) или `json` (JSON массив). По умолчанию `jsonl`
+- `overwrite` — boolean, разрешить перезапись существующих файлов при использовании явного пути к файлу. По умолчанию `false`
 
 Когда `saveToFile` установлено в `true`, инструменты возвращают метаданные о сохраненном файле вместо полных данных.
 
@@ -291,18 +294,18 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `issue_lookup` | Краткая информация о задаче. **Использование:** Быстрый просмотр базовой информации о задаче без полной детализации. **Возвращает:** предопределенные поля - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, project, parent, assignee. Пользовательские поля не включены. | `issueId` — код задачи (например, `PROJ-123`) |
-| `issues_lookup` | Краткая информация о нескольких задачах (пакетный режим, макс 50). **Использование:** Эффективное получение информации о множестве задач одновременно. **Возвращает:** те же поля, что и `issue_lookup`. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач (например, `['PROJ-123', 'PROJ-124']`), макс 50; `briefOutput` — опционально (по умолчанию `true`) |
-| `issue_details` | Режимы краткий/полный для деталей задачи. **Использование:** Просмотр деталей задачи. **Краткий (по умолчанию):** предопределённые поля — id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project, parent, assignee, reporter, updater, watchers(hasStar). **Полный (`briefOutput=false`):** добавляет `customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation))`, включая поле `State`. | `issueId` — код задачи; `briefOutput` — опционально (по умолчанию `true`) |
-| `issues_details` | Режимы краткий/полный для множества задач (макс 50). **Краткий:** предопределённые поля. **Полный (`briefOutput=false`):** добавляет `customFields` для каждой задачи. **Замечание:** объём ответа может быть большим, поэтому по умолчанию используется краткий режим. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач, макс 50; `briefOutput` — опционально (по умолчанию `true`) |
-| `issue_comments` | Комментарии задачи. **Использование:** Просмотр всех комментариев к задаче. **Возвращает:** предопределенные поля - id, text, textPreview, usesMarkdown, author (id, login, name), created, updated, commentUrl (прямая ссылка на комментарий) | `issueId` — код задачи |
-| `issues_comments` | Комментарии для нескольких задач (пакетный режим, макс 50). **Использование:** Эффективное получение комментариев для множества задач одновременно. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач, макс 50; `briefOutput` — опционально (по умолчанию `true`) |
+| `issue_lookup` | Получить информацию о задаче YouTrack. **Использование:** Быстрый просмотр базовой информации о задаче. **Возвращает:** предопределенные поля включая метки времени (created, updated) и базовую информацию - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). Пользовательские поля не включены по умолчанию. Используйте `briefOutput=false` для получения всех пользовательских полей включая State. | `issueId` — код задачи (например, `PROJ-123`); `briefOutput` — опционально (по умолчанию `true`) |
+| `issues_lookup` | Получить информацию о нескольких задачах YouTrack (пакетный режим, макс 50). **Использование:** Эффективное получение информации о множестве задач одновременно. **Возвращает:** те же поля, что и `issue_lookup`. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач (например, `['PROJ-123', 'PROJ-124']`), макс 50; `briefOutput` — опционально (по умолчанию `true`) |
+| `issue_details` | Режимы краткий/полный для деталей задачи. **Использование:** Просмотр деталей задачи. **Краткий (по умолчанию):** предопределённые поля — id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project, parent, assignee, reporter, updater, watchers(hasStar). **Полный (`briefOutput=false`):** добавляет `customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation))`, включая поле `State`. | `issueId` — код задачи; `briefOutput` — опционально (по умолчанию `true`); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issues_details` | Режимы краткий/полный для множества задач (макс 50). **Краткий:** предопределённые поля. **Полный (`briefOutput=false`):** добавляет `customFields` для каждой задачи. **Замечание:** объём ответа может быть большим, поэтому по умолчанию используется краткий режим. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач, макс 50; `briefOutput` — опционально (по умолчанию `true`); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issue_comments` | Комментарии задачи. **Использование:** Просмотр всех комментариев к задаче. **Возвращает:** предопределенные поля - id, text, textPreview, usesMarkdown, author (id, login, name), created, updated, commentUrl (прямая ссылка на комментарий) | `issueId` — код задачи; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issues_comments` | Комментарии для нескольких задач (пакетный режим, макс 50). **Использование:** Эффективное получение комментариев для множества задач одновременно. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач, макс 50; `briefOutput` — опционально (по умолчанию `true`); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `issue_create` | Создание новой задачи в YouTrack. **Использование:** Создание задач, подзадач (через `parentIssueId`), назначение исполнителя при создании, одновременное создание дополнительных связей. **Возвращает:** стандартные поля созданной задачи (id, idReadable, summary, description, wikifiedDescription, usesMarkdown, project, parent, assignee). Пользовательские поля не включены. | `projectId` — внутренний ID проекта, `summary`, опционально `description`, `parentIssueId`, `assigneeLogin`, `stateName`, `usesMarkdown`, `links[]` — массив объектов связи |
 | `issue_update` | Обновление существующей задачи. **Использование:** Изменение summary, description, родительской задачи. **Примечание:** для изменения исполнителя используйте `issue_assign`. Пустая строка в `parentIssueId` удаляет родителя. **Возвращает:** стандартные поля обновленной задачи | `issueId` — ID или код задачи, опционально `summary`, `description`, `parentIssueId` (пустая строка очищает родителя), `usesMarkdown` |
 | `issue_assign` | Назначение исполнителя для задачи. **Использование:** Изменение исполнителя задачи. Поддерживает алиас `me` для текущего пользователя. **Возвращает:** стандартные поля обновленной задачи | `issueId` — ID или код задачи, `assigneeLogin` — логин исполнителя или `me` |
 | `issue_comment_create` | Добавление комментария к задаче. **Использование:** Оставлять комментарии, заметки, обсуждения в задачах. Поддерживает Markdown. **Возвращает:** поля комментария - id, text, textPreview, usesMarkdown, author, created, updated | `issueId` — ID или код задачи, `text` — текст комментария, опционально `usesMarkdown` |
 | `issue_comment_update` | Обновление существующего комментария. **Использование:** Редактирование текста комментария, изменение режима форматирования, исправление опечаток. Поддерживает Markdown. **Возвращает:** поля комментария - id, text, textPreview, usesMarkdown, author, created, updated, commentUrl | `issueId` — ID или код задачи, `commentId` — ID комментария, опционально `text`, `usesMarkdown`, `muteUpdateNotifications` |
-| `issue_activities` | Получение истории изменений задачи (активности). **Использование:** Просмотр полной истории задачи, отслеживание изменений полей во времени, мониторинг кто и когда что изменил, анализ эволюции задачи, аудит модификаций. **Возвращает:** Элементы активности с временными метками (ISO datetime), авторами, категориями, типами изменений и деталями изменений (добавленные/удалённые значения). Поддерживает фильтрацию по автору, диапазону дат и категориям активности. **Примечание:** Возвращает предопределённые поля - id, timestamp, author (id, login, name), category (id), target (text), добавленные значения, удалённые значения, тип активности. Полезно для понимания жизненного цикла задачи, отслеживания модификаций полей, просмотра истории комментариев и анализа паттернов совместной работы. | `issueId` — код задачи, опционально `author` (логин пользователя), `startDate` (формат YYYY-MM-DD, timestamp или Date), `endDate`, `categories` (через запятую: `CustomFieldCategory` для изменений полей, `CommentsCategory` для комментариев, `AttachmentsCategory` для вложений, `LinksCategory` для связей, `VcsChangeActivityCategory` для VCS изменений, `WorkItemsActivityCategory` для трудозатрат), `limit` (макс 200), `skip` для пагинации |
+| `issue_activities` | Получение истории изменений задачи (активности). **Использование:** Просмотр полной истории задачи, отслеживание изменений полей во времени, мониторинг кто и когда что изменил, анализ эволюции задачи, аудит модификаций. **Возвращает:** Элементы активности с временными метками (ISO datetime), авторами, категориями, типами изменений и деталями изменений (добавленные/удалённые значения). Поддерживает фильтрацию по автору, диапазону дат и категориям активности. **Примечание:** Возвращает предопределённые поля - id, timestamp, author (id, login, name), category (id), target (text), добавленные значения, удалённые значения, тип активности. Полезно для понимания жизненного цикла задачи, отслеживания модификаций полей, просмотра истории комментариев и анализа паттернов совместной работы. | `issueId` — код задачи, опционально `author` (логин пользователя), `startDate` (формат YYYY-MM-DD, timestamp или Date), `endDate`, `categories` (через запятую: `CustomFieldCategory` для изменений полей, `CommentsCategory` для комментариев, `AttachmentsCategory` для вложений, `LinksCategory` для связей, `VcsChangeActivityCategory` для VCS изменений, `WorkItemsActivityCategory` для трудозатрат), `limit` (макс 200), `skip` для пагинации; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `issue_change_state` | Изменение состояния/статуса задачи через переходы workflow. **Использование:** Перемещение задач через состояния рабочего процесса (например, 'Открыта' → 'В работе'). Автоматически определяет доступные переходы и валидирует запрошенное изменение состояния. Регистронезависимое сопоставление имён состояний. **Возвращает:** информацию о предыдущем состоянии, новом состоянии и использованном переходе | `issueId` — код задачи, `stateName` — имя целевого состояния (например, 'В работе', 'Открыта', 'Исправлена', 'Проверена'). Регистронезависимое |
 
 ### Связи задач
@@ -324,6 +327,13 @@ YOUTRACK_TOKEN = "perm:your-token-here"
   - `sourceId` — опционально. Если не указан, исходной считается новая задача; укажите его, чтобы привязать новую задачу как `target` к уже существующей.
 - После создания задачи повторно запросите связи (`issue_links`) для подтверждения, что YouTrack применил все отношения.
 
+### Статусы задач
+
+| Tool | Описание | Основные параметры |
+| --- | --- | --- |
+| `issue_status` | Получить статус задачи YouTrack. Возвращает поле State задачи. | `issueId` — код задачи (например, `PROJ-123`) |
+| `issues_status` | Получить статусы нескольких задач YouTrack (пакетный режим, макс 50). Возвращает поле State каждой задачи. | `issueIds[]` — массив кодов задач (например, `['PROJ-123', 'PROJ-124']`), макс 50 |
+
 ### Звездочки задач
 
 | Tool | Описание | Основные параметры |
@@ -338,25 +348,25 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `workitems_list` | Получение трудозатрат текущего или указанного пользователя. **Использование:** Просмотр учтенного времени, фильтрация по задаче, автору, периоду. **Возвращает:** предопределенные поля - id, date, duration (minutes, presentation), text, textPreview, usesMarkdown, description, issue (id, idReadable), author (id, login, name, email) | Опционально `issueId`, `author` (логин пользователя), `startDate` (формат YYYY-MM-DD, timestamp или date-time), `endDate`, `allUsers` |
-| `workitems_all_users` | Получение трудозатрат всех пользователей. **Использование:** Просмотр времени всей команды, анализ загрузки проекта. **Возвращает:** те же поля, что и `workitems_list` | Опционально `issueId`, `startDate`, `endDate` |
-| `workitems_for_users` | Получение трудозатрат выбранных пользователей. **Использование:** Просмотр времени конкретных участников команды, сравнение загрузки между пользователями. **Возвращает:** те же поля, что и `workitems_list` | `users[]` — массив логинов пользователей, опционально `issueId`, `startDate`, `endDate` |
-| `workitems_recent` | Получение последних записей трудозатрат с сортировкой по времени обновления (новые первыми). **Использование:** Быстрый просмотр недавних записей времени, мониторинг текущей активности. **Возвращает:** те же поля, что и `workitems_list`. **Ограничение:** по умолчанию 50 записей, макс 200 | Опционально `users[]` (по умолчанию текущий пользователь), `limit` (по умолчанию 50, макс 200) |
+| `workitems_list` | Получение трудозатрат текущего или указанного пользователя. **Использование:** Просмотр учтенного времени, фильтрация по задаче, автору, периоду. **Возвращает:** предопределенные поля - id, date, duration (minutes, presentation), text, textPreview, usesMarkdown, description, issue (id, idReadable), author (id, login, name, email) | Опционально `issueId`, `author` (логин пользователя), `startDate` (формат YYYY-MM-DD, timestamp или date-time), `endDate`, `allUsers`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_all_users` | Получение трудозатрат всех пользователей. **Использование:** Просмотр времени всей команды, анализ загрузки проекта. **Возвращает:** те же поля, что и `workitems_list` | Опционально `issueId`, `startDate`, `endDate`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_for_users` | Получение трудозатрат выбранных пользователей. **Использование:** Просмотр времени конкретных участников команды, сравнение загрузки между пользователями. **Возвращает:** те же поля, что и `workitems_list` | `users[]` — массив логинов пользователей, опционально `issueId`, `startDate`, `endDate`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_recent` | Получение последных записей трудозатрат с сортировкой по времени обновления (новые первыми). **Использование:** Быстрый просмотр недавних записей времени, мониторинг текущей активности. **Возвращает:** те же поля, что и `workitems_list`. **Ограничение:** по умолчанию 50 записей, макс 200 | Опционально `users[]` (по умолчанию текущий пользователь), `limit` (по умолчанию 50, макс 200); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `workitem_create` | Создание записи трудозатрат. **Использование:** Учет времени на задачу за конкретную дату. **Возвращает:** предопределенные поля созданной записи. **Примечание:** может создавать дубликаты, для предотвращения используйте `workitem_create_idempotent` | `issueId` — ID задачи, `date` (формат YYYY-MM-DD, timestamp или date-time), `minutes` — количество минут (>0), опционально `summary` — краткий текст, `description`, `usesMarkdown` |
 | `workitem_create_idempotent` | Создание записи без дублей (по описанию и дате). **Использование:** Безопасное создание записи времени с предотвращением дублирования. Проверяет существование похожей записи по описанию. **Возвращает:** предопределенные поля созданной или найденной записи | `issueId` — ID задачи, `date`, `minutes`, `description` — текст для поиска существующей записи, опционально `usesMarkdown` |
 | `workitem_update` | Обновление записи трудозатрат. **Использование:** Исправление учтенного времени, даты или описания. **Возвращает:** предопределенные поля обновленной записи | `issueId` — ID задачи, `workItemId` — ID записи трудозатрат, опционально `date`, `minutes`, `summary` — новый текст, `description`, `usesMarkdown` |
 | `workitem_delete` | Удаление записи трудозатрат. **Использование:** Удаление ошибочно созданных или неактуальных записей | `issueId` — ID задачи, `workItemId` — ID записи трудозатрат |
 | `workitems_create_period` | Массовое создание трудозатрат по диапазону дат. **Использование:** Учет регулярной работы за период, автоматическое исключение выходных и праздников. **Возвращает:** массив созданных записей с предопределенными полями. **Примечание:** автоматически пропускает выходные при `excludeWeekends=true` и даты из списка `holidays` | `issueId`, `startDate`, `endDate`, `minutes` — минут в день, опционально `summary`, `description`, `usesMarkdown`, `excludeWeekends` — исключить субботы и воскресенья, `excludeHolidays`, `holidays[]` — массив дат праздников (YYYY-MM-DD, timestamp или date-time), `preHolidays[]` — массив предпраздничных дат |
-| `workitems_report_summary` | Сводный отчёт по трудозатратам. **Использование:** Анализ загрузки за период, сравнение плана и факта, выявление недостатка/избытка часов. **Возвращает:** общую статистику - общее количество минут, ожидаемое количество, отклонение, количество рабочих дней, данные по дням | Опционально `author` (логин), `issueId`, `startDate`, `endDate`, `expectedDailyMinutes` — норма минут в день (например, 480 для 8 часов), `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers` — включить всех пользователей |
-| `workitems_report_invalid` | Список дней с отклонением от нормы времени. **Использование:** Поиск дней с недостатком или избытком учтенного времени, контроль соблюдения нормы. **Возвращает:** массив дней, где факт отличается от нормы, с детализацией по записям | Те же параметры, что и для `workitems_report_summary` |
-| `workitems_report_users` | Отчёт по трудозатратам списка пользователей. **Использование:** Сравнительный анализ загрузки нескольких пользователей, командная статистика. **Возвращает:** отчет по каждому пользователю с общей статистикой и детализацией по дням | `users[]` — массив логинов пользователей + общие параметры отчёта (`issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`) |
-| `workitems_report` | Генерация отчёта по трудозатратам (устаревший). **Использование:** Для совместимости со старыми клиентами. Рекомендуется использовать специализированные инструменты отчётов (`workitems_report_summary`, `workitems_report_invalid`, `workitems_report_users`) | Опционально `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers` |
+| `workitems_report_summary` | Сводный отчёт по трудозатратам. **Использование:** Анализ загрузки за период, сравнение плана и факта, выявление недостатка/избытка часов. **Возвращает:** общую статистику - общее количество минут, ожидаемое количество, отклонение, количество рабочих дней, данные по дням | Опционально `author` (логин), `issueId`, `startDate`, `endDate`, `expectedDailyMinutes` — норма минут в день (например, 480 для 8 часов), `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers` — включить всех пользователей; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_report_invalid` | Список дней с отклонением от нормы времени. **Использование:** Поиск дней с недостатком или избытком учтенного времени, контроль соблюдения нормы. **Возвращает:** массив дней, где факт отличается от нормы, с детализацией по записям | Те же параметры, что и для `workitems_report_summary`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_report_users` | Отчёт по трудозатратам списка пользователей. **Использование:** Сравнительный анализ загрузки нескольких пользователей, командная статистика. **Возвращает:** отчет по каждому пользователю с общей статистикой и детализацией по дням | `users[]` — массив логинов пользователей + общие параметры отчёта (`issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_report` | Генерация отчёта по трудозатратам (устаревший). **Использование:** Для совместимости со старыми клиентами. Рекомендуется использовать специализированные инструменты отчётов (`workitems_report_summary`, `workitems_report_invalid`, `workitems_report_users`) | Опционально `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 
 ### Пользователи и проекты
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `users_list` | Список всех пользователей YouTrack. **Использование:** Просмотр доступных пользователей, поиск логинов для назначения задач. **Возвращает:** предопределенные поля - id, login, name, fullName, email | — |
+| `users_list` | Список всех пользователей YouTrack. **Использование:** Просмотр доступных пользователей, поиск логинов для назначения задач. **Возвращает:** предопределенные поля - id, login, name, fullName, email | `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `user_get` | Получение пользователя по логину. **Использование:** Проверка существования пользователя, получение деталей профиля. **Возвращает:** предопределенные поля - id, login, name, fullName, email | `login` — логин пользователя |
 | `user_current` | Получение текущего аутентифицированного пользователя. **Использование:** Проверка, под каким пользователем работает API токен, получение собственного ID для операций. **Возвращает:** предопределенные поля - id, login, name, fullName, email | — |
 | `projects_list` | Список всех проектов YouTrack. **Использование:** Просмотр доступных проектов, поиск ID проекта для создания задач. **Возвращает:** предопределенные поля - id, shortName, name | — |
@@ -370,24 +380,24 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | `article_list` | Список статей с фильтрами. **Использование:** Просмотр структуры базы знаний, навигация по статьям. **Возвращает:** предопределенные поля - id, idReadable, summary, usesMarkdown, parentArticle (id, idReadable), project (id, shortName, name). Поле content не включено для производительности | Опционально `parentArticleId` — фильтр по родительской статье, `projectId` — фильтр по проекту |
 | `article_create` | Создание статьи в базе знаний. **Использование:** Создание документации, инструкций, статей поддержки. Поддерживает иерархическую структуру через `parentArticleId`. **Возвращает:** предопределенные поля созданной статьи - id, idReadable, summary, content, contentPreview, usesMarkdown, parentArticle, project | `summary` — заголовок статьи, опционально `content` — содержимое, `parentArticleId` — ID родительской статьи для создания подстатьи, `projectId` — ID проекта, `usesMarkdown` — использовать Markdown форматирование, `returnRendered` — вернуть отрендеренный preview |
 | `article_update` | Обновление существующей статьи. **Использование:** Редактирование содержимого, изменение заголовка статьи. **Возвращает:** предопределенные поля обновленной статьи | `articleId` — ID статьи, опционально `summary` — новый заголовок, `content` — новое содержимое, `usesMarkdown`, `returnRendered` |
-| `article_search` | Поиск статей в базе знаний по тексту. **Использование:** Полнотекстовый поиск по заголовкам и содержимому статей, поиск документации. Поддерживает фильтрацию по проекту и родительской статье. **Возвращает:** предопределенные поля - id, idReadable, summary, usesMarkdown, contentPreview (если `returnRendered=true`), parentArticle, project. Поле content не включено для производительности. **Ограничение:** минимум 2 символа в запросе, максимум 200 результатов | `query` — текст для поиска (минимум 2 символа), опционально `projectId` — фильтр по проекту, `parentArticleId` — фильтр по родительской статье, `limit` — максимум результатов (макс 200), `returnRendered` — вернуть отрендеренный preview содержимого |
-| `articles_search` | Полнотекстовый поиск по статьям базы знаний YouTrack по заголовку и содержимому. Возвращает `webUrl` для прямого перехода. | `query`, `limit`, `skip`, опционально `projectId`, `parentArticleId` |
-| `issues_search` | Полнотекстовый поиск по задачам YouTrack по summary, description и комментариям. Если `query` не указан или пуст, будут возвращены все задачи. Поддерживает фильтрацию по проектам, исполнителю, автору, статусу и типу. | `query` (необязательный), `limit`, `skip`, `countOnly` (необязательный), `projects` (необязательный), `assignee` (необязательный), `reporter` (необязательный), `state` (необязательный), `type` (необязательный) |
-| `issues_list` | Список задач по фильтрам с поддержкой сортировки. **Использование:** Дашборды, аудит командной загрузки, подготовка батч-операций. Поддерживает фильтрацию по проектам, датам создания/обновления, статусам, типам, исполнителю. **Возвращает:** краткие или полные данные задачи в зависимости от `briefOutput`, а также информацию о сортировке и пагинации. | Фильтры: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; сортировка: `sortField` (`created`/`updated`), `sortDirection` (`asc`/`desc`); пагинация: `limit`, `skip`; формат: `briefOutput` |
-| `issues_count` | Подсчёт задач с теми же фильтрами, что у `issues_list`, с разбивкой по проектам. **Использование:** Быстрая оценка объёмов работ перед загрузкой полного списка, подготовка аналитических отчётов. При запросе одного проекта обращается к `/api/issuesGetter/count`, иначе считает постранично. | Те же фильтры, что и `issues_list`; опциональный `top` ограничивает объём ручной агрегации (при необходимости частичной выборки) |
+| `article_search` | Поиск статей в базе знаний по тексту. **Использование:** Полнотекстовый поиск по заголовкам и содержимому статей, поиск документации. Поддерживает фильтрацию по проекту и родительской статье. **Возвращает:** предопределенные поля - id, idReadable, summary, usesMarkdown, contentPreview (если `returnRendered=true`), parentArticle, project. Поле content не включено для производительности. **Ограничение:** минимум 2 символа в запросе, максимум 200 результатов | `query` — текст для поиска (минимум 2 символа), опционально `projectId` — фильтр по проекту, `parentArticleId` — фильтр по родительской статье, `limit` — максимум результатов (макс 200), `returnRendered` — вернуть отрендеренный preview содержимого; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `articles_search` | Полнотекстовый поиск по статьям базы знаний YouTrack по заголовку и содержимому. Возвращает `webUrl` для прямого перехода. | `query`, `limit`, `skip`, опционально `projectId`, `parentArticleId`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issues_search` | Полнотекстовый поиск по задачам YouTrack по summary, description и комментариям. Если `query` не указан или пуст, будут возвращены все задачи. Поддерживает фильтрацию по проектам, исполнителю, автору, статусу и типу. | `query` (необязательный), `limit`, `skip`, `countOnly` (необязательный), `projects` (необязательный), `assignee` (необязательный), `reporter` (необязательный), `state` (необязательный), `type` (необязательный); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issues_list` | Список задач по фильтрам с поддержкой сортировки. **Использование:** Дашборды, аудит командной загрузки, подготовка батч-операций. Поддерживает фильтрацию по проектам, датам создания/обновления, статусам, типам, исполнителю. **Возвращает:** краткие или полные данные задачи в зависимости от `briefOutput`, а также информацию о сортировке и пагинации. | Фильтры: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; сортировка: `sortField` (`created`/`updated`), `sortDirection` (`asc`/`desc`); пагинация: `limit`, `skip`; формат: `briefOutput`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issues_count` | Подсчёт задач с теми же фильтрами, что у `issues_list`, с разбивкой по проектам. **Использование:** Быстрая оценка объёмов работ перед загрузкой полного списка, подготовка аналитических отчётов. При запросе одного проекта обращается к `/api/issuesGetter/count`, иначе считает постранично. | Те же фильтры, что и `issues_list`; опциональный `top` ограничивает объём ручной агрегации (при необходимости частичной выборки); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 
 ### Лента активности
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `users_activity` | Авторо-центричная лента активности на базе `/api/activities`. **Использование:** аудит обновлений коллеги, накопление комментариев/смен состояний по множеству задач, проверка таймлайна выката. Возвращает нормализованные записи с ISO-временем, ссылками на задачи и полями `added`/`removed`. После анализа обязательно повторно запросите затронутые задачи или рабочие элементы, чтобы убедиться в актуальном состоянии. Поддерживаемые категории: `CustomFieldCategory` (изменения полей), `CommentsCategory` (комментарии), `AttachmentsCategory` (файлы), `LinksCategory` (ссылки), `VcsChangeActivityCategory` (VCS изменения), `WorkItemsActivityCategory` (трудозатраты). | `author` *(обязательный)* — логин пользователя (например, `vyt`); `categories` *(обязательный)* — список категорий через запятую из перечня выше; опционально `start` / `end` (ISO-строка, timestamp в мс или `Date`) для ограничения диапазона, `reverse` (boolean) для прямого хронометража, `limit` (по умолчанию 100, макс 200), `skip` (смещение пагинации), `fields` (расширенный перегруз возвращаемых полей). |
+| `users_activity` | Авторо-центричная лента активности на базе `/api/activities`. **Использование:** аудит обновлений коллеги, накопление комментариев/смен состояний по множеству задач, проверка таймлайна выката. Возвращает нормализованные записи с ISO-временем, ссылками на задачи и полями `added`/`removed`. После анализа обязательно повторно запросите затронутые задачи или рабочие элементы, чтобы убедиться в актуальном состоянии. Поддерживаемые категории: `CustomFieldCategory` (изменения полей), `CommentsCategory` (комментарии), `AttachmentsCategory` (файлы), `LinksCategory` (ссылки), `VcsChangeActivityCategory` (VCS изменения), `WorkItemsActivityCategory` (трудозатраты). | `author` *(обязательный)* — логин пользователя (например, `vyt`); `categories` *(обязательный)* — список категорий через запятую из перечня выше; опционально `start` / `end` (ISO-строка, timestamp в мс или `Date`) для ограничения диапазона, `reverse` (boolean) для прямого хронометража, `limit` (по умолчанию 100, макс 200), `skip` (смещение пагинации), `fields` (расширенный перегруз возвращаемых полей); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов. |
 
 ### Вложения
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `issue_attachments_list` | Получение списка вложений задачи. **Использование:** Просмотр всех файлов, прикрепленных к задаче. **Возвращает:** метаданные всех вложений задачи | `issueId` — код задачи (например, `PROJ-123`) |
-| `issue_attachment_get` | Получение детальной информации о конкретном вложении. **Использование:** Проверка метаданных файла (размер, имя, тип, автор, дата). **Возвращает:** подробные метаданные вложения | `issueId` — код задачи, `attachmentId` — ID вложения |
-| `issue_attachment_download` | Получение информации для скачивания вложения. **Использование:** Получение подписанного URL для загрузки файла. **Возвращает:** метаданные вложения и подписанный URL, который можно использовать напрямую без дополнительной аутентификации | `issueId` — код задачи, `attachmentId` — ID вложения |
+| `issue_attachments_list` | Получение списка вложений задачи. **Использование:** Просмотр всех файлов, прикрепленных к задаче. **Возвращает:** метаданные всех вложений задачи | `issueId` — код задачи (например, `PROJ-123`); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issue_attachment_get` | Получение детальной информации о конкретном вложении. **Использование:** Проверка метаданных файла (размер, имя, тип, автор, дата). **Возвращает:** подробные метаданные вложения | `issueId` — код задачи, `attachmentId` — ID вложения; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `issue_attachment_download` | Получение URL для скачивания вложения или прямая загрузка файла в локальную файловую систему. **Использование:** Получение подписанного URL для загрузки файла или прямая загрузка файла в локальную файловую систему. **Возвращает:** метаданные вложения и подписанный URL, который можно использовать напрямую без дополнительной аутентификации, или информацию о загруженном файле | `issueId` — код задачи, `attachmentId` — ID вложения; `downloadToFile` — boolean, загрузить файл непосредственно в локальную файловую систему (по умолчанию: false); `downloadPath` — путь для сохранения файла (генерируется автоматически, если не указан); `overwrite` — разрешить перезапись существующих файлов (по умолчанию: false, выдает ошибку, если файл существует); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `issue_attachment_upload` | Загрузка файлов к задаче YouTrack. **Использование:** Прикрепление документов, скриншотов, логов к задаче. Файлы должны существовать в локальной файловой системе. **Примечание:** можно прикреплять файлы только к существующим задачам, не при создании. **Ограничение:** максимум 10 файлов за запрос | `issueId` — код задачи, `filePaths[]` — массив абсолютных путей к файлам (макс 10), опционально `muteUpdateNotifications` — не отправлять уведомления об обновлении |
 | `issue_attachment_delete` | Удаление вложения из задачи YouTrack. **ВАЖНО:** Требует явного подтверждения через параметр `confirmation` для предотвращения случайного удаления. **Использование:** Удаление устаревших или ошибочно загруженных файлов. Это деструктивная операция, которую нельзя отменить. | `issueId` — код задачи, `attachmentId` — ID вложения для удаления, `confirmation` — должен быть явно установлен в `true` для подтверждения удаления (обязательный параметр безопасности) |

package/README.md

@@ -45,7 +45,9 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
     - [Service](#service)
     - [Issues](#issues)
     - [Issue Links](#issue-links)
+    - [Issues Status](#issues-status)
     - [Issue Stars](#issue-stars)
+    - [Attachments](#attachments)
     - [Work Items](#work-items)
     - [Users and Projects](#users-and-projects)
     - [Articles](#articles)
@@ -278,10 +280,12 @@ To use this MCP server with [Cline](https://github.com/cline/cline) extension in
 
 ### File Storage Parameters
 
-Many tools support optional `saveToFile` and `filePath` parameters for handling large datasets:
+Many tools support optional file storage parameters for handling large datasets:
 
 - `saveToFile` — boolean, saves results to a JSON file instead of returning directly (useful for large datasets)
 - `filePath` — string, custom file path (optional, auto-generated if not provided, directory created if needed)
+- `format` — string, output format when saving to file: `jsonl` (JSON Lines) or `json` (JSON array format). Default is `jsonl`
+- `overwrite` — boolean, allow overwriting existing files when using explicit filePath. Default is `false`
 
 When `saveToFile` is `true`, tools return metadata about the saved file instead of the full data.
 
@@ -295,22 +299,22 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `issue_lookup` | Brief issue information | `issueId` — issue code (e.g., PROJ-123) |
-| `issues_lookup` | Brief information about multiple issues (batch mode, max 50) | `issueIds[]` — array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50; `briefOutput` — optional boolean (default `true`) |
-| `issue_details` | Issue details with brief/full modes | `issueId` — issue code; `briefOutput` — optional boolean (default `true`). Brief: predefined fields only. Full (`false`): adds `customFields` including `State` |
-| `issues_details` | Detailed information about multiple issues (batch mode, max 50). Brief (default): predefined fields only. Full (`briefOutput=false`): adds `customFields` for each issue | `issueIds[]` — array of issue codes, max 50; `briefOutput` — optional boolean (default `true`) |
-| `issue_comments` | Issue comments | `issueId` — issue code |
-| `issues_comments` | Comments for multiple issues (batch mode, max 50) | `issueIds[]` — array of issue codes, max 50; `briefOutput` — optional boolean (default `true`) |
+| `issue_lookup` | Get information about YouTrack issue. Note: Returns predefined fields including timestamps (created, updated) and basic info - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). By default, custom fields are not included. Use briefOutput=false to get all customFields including State. | `issueId` — issue code (e.g., PROJ-123); `briefOutput` — optional boolean (default `true`) |
+| `issues_lookup` | Get information about multiple YouTrack issues (batch mode, max 50). Note: Returns predefined fields including timestamps (created, updated) and basic info - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). By default, custom fields are not included. Use briefOutput=false to get all customFields including State. | `issueIds[]` — array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50; `briefOutput` — optional boolean (default `true`) |
+| `issue_details` | Issue details with brief/full modes | `issueId` — issue code; `briefOutput` — optional boolean (default `true`). Brief: predefined fields only. Full (`false`): adds `customFields` including `State`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issues_details` | Detailed information about multiple issues (batch mode, max 50). Brief (default): predefined fields only. Full (`briefOutput=false`): adds `customFields` for each issue | `issueIds[]` — array of issue codes, max 50; `briefOutput` — optional boolean (default `true`); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issue_comments` | Issue comments | `issueId` — issue code; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issues_comments` | Comments for multiple issues (batch mode, max 50) | `issueIds[]` — array of issue codes, max 50; `briefOutput` — optional boolean (default `true`); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 | `issue_create` | Create issue | `projectId`, `summary`, optional `description`, `parentIssueId`, `assigneeLogin`, `stateName`, `usesMarkdown`, `links` (array of link objects) |
 | `issue_update` | Update existing issue | `issueId`, optionally `summary`, `description`, `parentIssueId` (empty string clears parent), `usesMarkdown` |
 | `issue_assign` | Assign issue to user | `issueId`, `assigneeLogin` (login or `me`) |
 | `issue_comment_create` | Add comment to issue | `issueId`, `text` — comment text, optionally `usesMarkdown` |
 | `issue_comment_update` | Update existing comment | `issueId`, `commentId`, optionally `text`, `usesMarkdown`, `muteUpdateNotifications` |
-| `issue_activities` | Get issue change history | `issueId` — issue code, optionally `author` (login), `startDate` (YYYY-MM-DD, timestamp, or Date), `endDate`, `categories` (comma-separated: `CustomFieldCategory` for field changes, `CommentsCategory` for comments, `AttachmentsCategory` for attachments, `LinksCategory` for links, `VcsChangeActivityCategory` for VCS changes, `WorkItemsActivityCategory` for work items), `limit` (max 200), `skip` for pagination. Returns activity items with timestamps (ISO datetime), authors, categories, and change details (added/removed values). Useful for tracking field modifications, reviewing comment history, and analyzing collaboration patterns |
+| `issue_activities` | Get issue change history | `issueId` — issue code, optionally `author` (login), `startDate` (YYYY-MM-DD, timestamp, or Date), `endDate`, `categories` (comma-separated: `CustomFieldCategory` for field changes, `CommentsCategory` for comments, `AttachmentsCategory` for attachments, `LinksCategory` for links, `VcsChangeActivityCategory` for VCS changes, `WorkItemsActivityCategory` for work items), `limit` (max 200), `skip` for pagination; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options. Returns activity items with timestamps (ISO datetime), authors, categories, and change details (added/removed values). Useful for tracking field modifications, reviewing comment history, and analyzing collaboration patterns |
 | `issue_change_state` | Change issue state/status through workflow transitions | `issueId` — issue code, `stateName` — target state name (e.g., 'In Progress', 'Open', 'Fixed', 'Verified'). Case-insensitive. Automatically discovers available transitions and validates requested state change. Returns information about previous state, new state, and transition used. Use for moving issues through workflow states |
-| `issue_attachments_list` | Get list of attachments | `issueId` — issue code |
-| `issue_attachment_get` | Get attachment info | `issueId`, `attachmentId` |
-| `issue_attachment_download` | Get download URL for attachment | `issueId`, `attachmentId` — returns signed URL |
+| `issue_attachments_list` | Get list of attachments | `issueId` — issue code; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issue_attachment_get` | Get attachment info | `issueId`, `attachmentId`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issue_attachment_download` | Get download URL for attachment or download file directly to local filesystem | `issueId`, `attachmentId` — returns signed download URL when downloadToFile=false; `downloadToFile` — boolean, download file directly to local system (default: false); `downloadPath` — custom path to save file (auto-generated if not provided); `overwrite` — allow overwriting existing files (default: false, throws error if file exists); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options for metadata |
 | `issue_attachment_upload` | Upload files to issue | `issueId`, `filePaths[]` — array of file paths (max 10), optionally `muteUpdateNotifications` |
 | `issue_attachment_delete` | Delete attachment (requires confirmation) | `issueId`, `attachmentId`, `confirmation` (must be `true`) |
 
@@ -323,6 +327,13 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 | `issue_link_add` | Create a link between two issues | `sourceId`, `targetId`, `linkType` (name or id), optionally `direction` (`outbound` or `inbound`) |
 | `issue_link_delete` | Delete a link by id for a specific issue | `issueId` — issue code, `linkId` — link id to delete |
 
+### Issues Status
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `issue_status` | Get status of a YouTrack issue. Returns the State of the issue. | `issueId` — issue code (e.g., PROJ-123) |
+| `issues_status` | Get status of multiple YouTrack issues (batch mode, max 50). Returns the State of each issue. | `issueIds[]` — array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50 |
+
 ### Issue Stars
 
 | Tool | Description | Main Parameters |
@@ -337,25 +348,25 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `workitems_list` | Get work items for current or specified user | Optionally `issueId`, `author`, `startDate`, `endDate`, `allUsers` |
-| `workitems_all_users` | Get work items for all users | Optionally `issueId`, `startDate`, `endDate` |
-| `workitems_for_users` | Get work items for selected users | `users[]`, optionally `issueId`, `startDate`, `endDate` |
-| `workitems_recent` | Get recent work items sorted by update time (newest first) | Optionally `users[]` (defaults to current user), `limit` (default 50, max 200) |
+| `workitems_list` | Get work items for current or specified user | Optionally `issueId`, `author`, `startDate`, `endDate`, `allUsers`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_all_users` | Get work items for all users | Optionally `issueId`, `startDate`, `endDate`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_for_users` | Get work items for selected users | `users[]`, optionally `issueId`, `startDate`, `endDate`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_recent` | Get recent work items sorted by update time (newest first) | Optionally `users[]` (defaults to current user), `limit` (default 50, max 200); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 | `workitem_create` | Create work item entry | `issueId`, `date`, `minutes`, optionally `summary`, `description`, `usesMarkdown` |
 | `workitem_create_idempotent` | Create work item without duplicates (by description and date) | `issueId`, `date`, `minutes`, `description`, optionally `usesMarkdown` |
 | `workitem_update` | Update work item (recreate) | `issueId`, `workItemId`, optionally `date`, `minutes`, `summary`, `description`, `usesMarkdown` |
 | `workitem_delete` | Delete work item | `issueId`, `workItemId` |
 | `workitems_create_period` | Batch create for date range | `issueId`, `startDate`, `endDate`, `minutes`, optionally `summary`, `description`, `usesMarkdown`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]` |
-| `workitems_report_summary` | Summary report for work items | Common parameters: `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers` |
-| `workitems_report_invalid` | Days with deviation from expected hours | Same parameters as summary |
-| `workitems_report_users` | Work items report for list of users | `users[]` + common report parameters |
-| `workitems_report` | Report structure (compatibility with older clients) | Optionally `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers` |
+| `workitems_report_summary` | Summary report for work items | Common parameters: `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_report_invalid` | Days with deviation from expected hours | Same parameters as summary; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_report_users` | Work items report for list of users | `users[]` + common report parameters; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_report` | Report structure (compatibility with older clients) | Optionally `author`, `issueId`, `startDate`, `endDate`, `expectedDailyMinutes`, `excludeWeekends`, `excludeHolidays`, `holidays[]`, `preHolidays[]`, `allUsers`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 
 ### Users and Projects
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `users_list` | List all YouTrack users | — |
+| `users_list` | List all YouTrack users | `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 | `user_get` | Get user by login | `login` — user login |
 | `user_current` | Get current authenticated user | — |
 | `projects_list` | List all YouTrack projects | — |
@@ -369,9 +380,9 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 | `article_list` | List articles with filters | Optionally `parentArticleId`, `projectId` |
 | `article_create` | Create article in knowledge base | `summary`, optionally `content`, `parentArticleId`, `projectId`, `usesMarkdown`, `returnRendered` |
 | `article_update` | Update article | `articleId`, optionally `summary`, `content`, `usesMarkdown`, `returnRendered` |
-| `article_search` | Search articles in knowledge base | `query`, optionally `projectId`, `parentArticleId`, `limit`, `returnRendered` |
-| `articles_search` | Full-text search across YouTrack knowledge base articles by title and content. Returns `webUrl` for direct access. | `query`, `limit`, `skip`, optionally `projectId`, `parentArticleId` |
-| `issues_search` | Full-text search across YouTrack issues by summary, description, and comments. If `query` is not provided or empty, all issues will be returned. Supports filtering by projects, assignee, reporter, state, and type. | `query` (optional), `limit`, `skip`, `countOnly` (optional), `projects` (optional), `assignee` (optional), `reporter` (optional), `state` (optional), `type` (optional) |
+| `article_search` | Search articles in knowledge base | `query`, optionally `projectId`, `parentArticleId`, `limit`, `returnRendered`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `articles_search` | Full-text search across YouTrack knowledge base articles by title and content. Returns `webUrl` for direct access. | `query`, `limit`, `skip`, optionally `projectId`, `parentArticleId`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issues_search` | Full-text search across YouTrack issues by summary, description, and comments. If `query` is not provided or empty, all issues will be returned. Supports filtering by projects, assignee, reporter, state, and type. | `query` (optional), `limit`, `skip`, `countOnly` (optional), `projects` (optional), `assignee` (optional), `reporter` (optional), `state` (optional), `type` (optional); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 
 ### Search
 
@@ -384,9 +395,9 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `users_activity` | Author-centric activity feed backed by `/api/activities`. **Use for:** auditing a teammate's updates, gathering comment/state changes across many issues, and reviewing deployment timelines. Returns normalized entries with ISO timestamps, optional issue references, and `added`/`removed` payloads. Always follow up by re-fetching the affected issue or work-item to confirm the latest state. Supported categories: `CustomFieldCategory` (field changes), `CommentsCategory` (comments), `AttachmentsCategory` (file events), `LinksCategory` (issue links), `VcsChangeActivityCategory` (VCS changes), `WorkItemsActivityCategory` (work items). | `author` *(required)* — login such as `vyt`; `categories` *(required)* — comma-separated list built from the supported categories above; optional `start` / `end` (ISO string, timestamp in ms, or `Date`) to bound the range, `reverse` (boolean) to switch to chronological order, `limit` (default 100, max 200), `skip` (pagination offset), `fields` (advanced override of response fields). |
-| `issues_list` | List issues across projects with filtering and sorting | Filters: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; Sorting: `sortField`, `sortDirection`; Pagination: `limit`, `skip`; Output mode: `briefOutput` |
-| `issues_count` | Count issues using same filters as `issues_list`, returns per-project breakdown | Same filters as above, optional `top` to cap manual aggregation when many projects are involved |
+| `users_activity` | Author-centric activity feed backed by `/api/activities`. **Use for:** auditing a teammate's updates, gathering comment/state changes across many issues, and reviewing deployment timelines. Returns normalized entries with ISO timestamps, optional issue references, and `added`/`removed` payloads. Always follow up by re-fetching the affected issue or work-item to confirm the latest state. Supported categories: `CustomFieldCategory` (field changes), `CommentsCategory` (comments), `AttachmentsCategory` (file events), `LinksCategory` (issue links), `VcsChangeActivityCategory` (VCS changes), `WorkItemsActivityCategory` (work items). | `author` *(required)* — login such as `vyt`; `categories` *(required)* — comma-separated list built from the supported categories above; optional `start` / `end` (ISO string, timestamp in ms, or `Date`) to bound the range, `reverse` (boolean) to switch to chronological order, `limit` (default 100, max 200), `skip` (pagination offset), `fields` (advanced override of response fields); `saveToFile`, `filePath`, `format`, `overwrite` — file storage options. |
+| `issues_list` | List issues across projects with filtering and sorting | Filters: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; Sorting: `sortField`, `sortDirection`; Pagination: `limit`, `skip`; Output mode: `briefOutput`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `issues_count` | Count issues using same filters as `issues_list`, returns per-project breakdown | Same filters as above, optional `top` to cap manual aggregation when many projects are involved; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
 
 ## Important Notes
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vitalyostanin/youtrack-mcp",
-    "version": "0.10.0",
+    "version": "0.10.2",
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "postbuild": "chmod +x dist/index.js",

package/dist/src/server.js

@@ -13,6 +13,7 @@ import { registerAttachmentTools } from "./tools/attachment-tools.js";
 import { registerIssueStarTools } from "./tools/issue-star-tools.js";
 import { registerIssueLinkTools } from "./tools/issue-link-tools.js";
 import { registerIssueListTools } from "./tools/issue-list-tools.js";
+import { registerIssueStatusTools } from "./tools/issue-status-tools.js";
 import { usersActivityArgs, usersActivityHandler } from "./tools/users-activity-tools.js";
 import { YoutrackClient } from "./youtrack-client.js";
 import { loadConfig } from "./config.js";
@@ -52,6 +53,7 @@ export class YoutrackServer {
         registerIssueStarTools(this.server, this.client);
         registerIssueLinkTools(this.server, this.client);
         registerIssueListTools(this.server, this.client);
+        registerIssueStatusTools(this.server, this.client);
     }
     async connect(transport) {
         await this.server.connect(transport);

package/dist/src/tools/article-search-tools.d.ts

@@ -8,6 +8,8 @@ export declare const articlesSearchArgs: {
     parentArticleId: z.ZodOptional<z.ZodString>;
     saveToFile: z.ZodOptional<z.ZodBoolean>;
     filePath: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["json", "jsonl"]>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
 };
 export declare const articlesSearchSchema: z.ZodObject<{
     query: z.ZodString;
@@ -17,11 +19,15 @@ export declare const articlesSearchSchema: z.ZodObject<{
     parentArticleId: z.ZodOptional<z.ZodString>;
     saveToFile: z.ZodOptional<z.ZodBoolean>;
     filePath: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["json", "jsonl"]>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     query: string;
     skip: number;
     limit: number;
     filePath?: string | undefined;
+    format?: "json" | "jsonl" | undefined;
+    overwrite?: boolean | undefined;
     saveToFile?: boolean | undefined;
     projectId?: string | undefined;
     parentArticleId?: string | undefined;
@@ -30,6 +36,8 @@ export declare const articlesSearchSchema: z.ZodObject<{
     skip?: number | undefined;
     limit?: number | undefined;
     filePath?: string | undefined;
+    format?: "json" | "jsonl" | undefined;
+    overwrite?: boolean | undefined;
     saveToFile?: boolean | undefined;
     projectId?: string | undefined;
     parentArticleId?: string | undefined;

package/dist/src/tools/article-search-tools.js

@@ -9,6 +9,8 @@ export const articlesSearchArgs = {
     parentArticleId: z.string().optional().describe("Filter by parent article ID"),
     saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
     filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+    format: z.enum(["json", "jsonl"]).optional().describe("Output format when saving to file: jsonl (JSON Lines) or json (JSON array format). Default is jsonl."),
+    overwrite: z.boolean().optional().describe("Allow overwriting existing files when using explicit filePath. Default is false."),
 };
 export const articlesSearchSchema = z.object(articlesSearchArgs);
 export async function articlesSearchHandler(client, rawInput) {
@@ -34,7 +36,7 @@ export async function articlesSearchHandler(client, rawInput) {
                 webUrl: `${baseUrl}/articles/${article.idReadable}`,
             }))
             : data;
-        const processedResult = processWithFileStorage(articlesWithLinks, input.saveToFile, input.filePath);
+        const processedResult = await processWithFileStorage(articlesWithLinks, input.saveToFile, input.filePath, input.format ?? 'jsonl', input.overwrite);
         if (processedResult.savedToFile) {
             return toolSuccess({
                 savedToFile: true,

package/dist/src/tools/attachment-tools.js

@@ -1,10 +1,14 @@
 import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
 import { processWithFileStorage } from "../utils/file-storage.js";
+import { downloadFileFromUrl, extractFilenameFromUrlOrHeader } from "../utils/file-download.js";
+import { join } from "path";
 const issueIdArgs = {
     issueId: z.string().min(1).describe("Issue code (e.g., PROJ-123)"),
     saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
     filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+    format: z.enum(["json", "jsonl"]).optional().describe("Output format when saving to file: jsonl (JSON Lines) or json (JSON array format). Default is jsonl."),
+    overwrite: z.boolean().optional().describe("Allow overwriting existing files when using explicit filePath. Default is false."),
 };
 const issueIdSchema = z.object(issueIdArgs);
 const attachmentGetArgs = {
@@ -12,6 +16,13 @@ const attachmentGetArgs = {
     attachmentId: z.string().min(1).describe("Attachment ID"),
 };
 const attachmentGetSchema = z.object(attachmentGetArgs);
+const attachmentDownloadArgs = {
+    ...issueIdArgs,
+    attachmentId: z.string().min(1).describe("Attachment ID"),
+    downloadToFile: z.boolean().optional().describe("Download the attachment file directly to local file system"),
+    downloadPath: z.string().optional().describe("Path to save the downloaded file (optional, auto-generated if not provided based on attachment name). Directory will be created if it doesn't exist."),
+};
+const attachmentDownloadSchema = z.object(attachmentDownloadArgs);
 const attachmentUploadArgs = {
     ...issueIdArgs,
     filePaths: z
@@ -35,7 +46,7 @@ export function registerAttachmentTools(server, client) {
         try {
             const payload = issueIdSchema.parse(rawInput);
             const result = await client.listAttachments(payload.issueId);
-            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            const processedResult = await processWithFileStorage(result, payload.saveToFile, payload.filePath, payload.format ?? 'jsonl', payload.overwrite);
             if (processedResult.savedToFile) {
                 return toolSuccess({
                     savedToFile: true,
@@ -62,12 +73,54 @@ export function registerAttachmentTools(server, client) {
             return errorResponse;
         }
     });
-    server.tool("issue_attachment_download", "Get download information for an attachment. Returns attachment metadata and a signed URL for downloading the file. The signed URL can be used directly without additional authentication.", attachmentGetArgs, async (rawInput) => {
+    server.tool("issue_attachment_download", "Get download information for an attachment. Returns attachment metadata and a signed URL for downloading the file. The signed URL can be used directly without additional authentication. With downloadToFile=true, will download the file directly to local filesystem.", attachmentDownloadArgs, async (rawInput) => {
         try {
-            const payload = attachmentGetSchema.parse(rawInput);
-            const result = await client.getAttachmentDownloadInfo(payload.issueId, payload.attachmentId);
-            const response = toolSuccess(result);
-            return response;
+            const payload = attachmentDownloadSchema.parse(rawInput);
+            // If downloadToFile is true, download the file directly
+            if (payload.downloadToFile) {
+                // Get attachment info to obtain the download URL and filename
+                const attachmentInfo = await client.getAttachmentDownloadInfo(payload.issueId, payload.attachmentId);
+                const { downloadUrl, attachment } = attachmentInfo;
+                // Determine the file path for download
+                let downloadFilePath;
+                if (payload.downloadPath) {
+                    downloadFilePath = payload.downloadPath;
+                }
+                else {
+                    // Generate filename from attachment info
+                    const filename = attachment.name || extractFilenameFromUrlOrHeader(downloadUrl);
+                    downloadFilePath = join("downloads", payload.issueId, filename);
+                }
+                // Download the file
+                const downloadedPath = await downloadFileFromUrl({
+                    url: downloadUrl,
+                    filePath: downloadFilePath,
+                    overwrite: payload.overwrite,
+                });
+                // Return success response with download info
+                const response = toolSuccess({
+                    downloaded: true,
+                    filePath: downloadedPath,
+                    attachmentId: payload.attachmentId,
+                    issueId: payload.issueId,
+                    originalAttachmentInfo: attachment,
+                });
+                return response;
+            }
+            // If downloadToFile is false, return the original download info
+            else {
+                const result = await client.getAttachmentDownloadInfo(payload.issueId, payload.attachmentId);
+                const processedResult = await processWithFileStorage(result, payload.saveToFile, payload.filePath, payload.format ?? 'jsonl', payload.overwrite);
+                if (processedResult.savedToFile) {
+                    return toolSuccess({
+                        savedToFile: true,
+                        filePath: processedResult.filePath,
+                        attachmentId: payload.attachmentId,
+                        issueId: payload.issueId,
+                    });
+                }
+                return toolSuccess(result);
+            }
         }
         catch (error) {
             const errorResponse = toolError(error);

package/dist/src/tools/issue-activity-tools.js

@@ -28,7 +28,9 @@ const issueActivitiesArgs = {
         .describe("Maximum number of activities to return (default: no limit, max: 200)"),
     skip: z.number().int().min(0).optional().describe("Number of activities to skip for pagination (default: 0)"),
     saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    format: z.enum(["json", "jsonl"]).optional().describe("Output format when saving to file: jsonl (JSON Lines) or json (JSON array format). Default is jsonl."),
     filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+    overwrite: z.boolean().optional().describe("Allow overwriting existing files when using explicit filePath. Default is false."),
 };
 const issueActivitiesSchema = z.object(issueActivitiesArgs);
 export function registerIssueActivityTools(server, client) {
@@ -71,7 +73,7 @@ export function registerIssueActivityTools(server, client) {
                     skip: input.skip ?? 0,
                 },
             };
-            const processedResult = processWithFileStorage(payload, input.saveToFile, input.filePath);
+            const processedResult = await processWithFileStorage(payload, input.saveToFile, input.filePath, input.format ?? 'jsonl', input.overwrite);
             if (processedResult.savedToFile) {
                 return toolSuccess({
                     savedToFile: true,

package/dist/src/tools/issue-list-tools.js

@@ -68,6 +68,11 @@ const issueListArgs = {
         .string()
         .optional()
         .describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+    format: z
+        .enum(["json", "jsonl"])
+        .optional()
+        .describe("Output format when saving to file: jsonl (JSON Lines) or json (JSON array format). Default is jsonl."),
+    overwrite: z.boolean().optional().describe("Allow overwriting existing files when using explicit filePath. Default is false."),
 };
 const issueListSchema = z.object(issueListArgs);
 export function registerIssueListTools(server, client) {
@@ -89,7 +94,7 @@ export function registerIssueListTools(server, client) {
                 limit: payload.limit,
                 skip: payload.skip,
             });
-            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            const processedResult = await processWithFileStorage(result, payload.saveToFile, payload.filePath, payload.format ?? 'jsonl', payload.overwrite);
             if (processedResult.savedToFile) {
                 return toolSuccess({
                     savedToFile: true,