@vitalyostanin/youtrack-mcp 0.10.2 → 0.12.0

package/README-ru.md

@@ -40,6 +40,8 @@ MCP сервер для полноценной интеграции с YouTrack
   - [Конфигурация для VS Code Cline](#конфигурация-для-vs-code-cline)
   - [Инструменты MCP](#инструменты-mcp)
     - [Параметры сохранения файлов](#параметры-сохранения-файлов)
+    - [Пагинация](#пагинация)
+    - [Подтверждение деструктивных операций](#подтверждение-деструктивных-операций)
     - [Сервис](#сервис)
     - [Задачи](#задачи)
     - [Связи задач](#связи-задач)
@@ -62,6 +64,7 @@ MCP сервер для полноценной интеграции с YouTrack
   - `YOUTRACK_PRE_HOLIDAYS` — опциональный список предпраздничных дат через запятую, для которых норма времени уменьшается автоматически
   - `YOUTRACK_USER_ALIASES` — опциональный список соответствий `alias:login` через запятую (например, `me:vyt,petya:p.petrov`), используется при автоматическом выборе исполнителей
   - `YOUTRACK_DEFAULT_PROJECT` — опциональный код проекта (shortName или ID), используемый по умолчанию при создании задач/статей и для преобразования коротких идентификаторов (например, `1234` → `PROJ-1234`)
+  - `YOUTRACK_OUTPUT_DIR` — опциональный корневой каталог для файлов, создаваемых через `saveToFile` и `downloadToFile`. По умолчанию используется текущий рабочий каталог. Абсолютные пути и сегменты с `..` (выход за пределы корня) отвергаются ради безопасности
 
 
 ## Установка
@@ -278,11 +281,23 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 Многие инструменты поддерживают опциональные параметры сохранения файлов для работы с большими датасетами:
 
 - `saveToFile` — boolean, сохраняет результаты в JSON файл вместо возврата напрямую (полезно для больших датасетов)
-- `filePath` — string, пользовательский путь к файлу (опционально, генерируется автоматически если не указан, директория создается при необходимости)
+- `filePath` — string, пользовательский путь к файлу относительно `YOUTRACK_OUTPUT_DIR` (опционально, генерируется автоматически если не указан, директория создается при необходимости)
 - `format` — string, формат вывода при сохранении в файл: `jsonl` (JSON Lines) или `json` (JSON массив). По умолчанию `jsonl`
 - `overwrite` — boolean, разрешить перезапись существующих файлов при использовании явного пути к файлу. По умолчанию `false`
 
-Когда `saveToFile` установлено в `true`, инструменты возвращают метаданные о сохраненном файле вместо полных данных.
+Когда `saveToFile` установлено в `true`, инструменты возвращают метаданные о сохранённом файле вместо полных данных. Все пути разрешаются относительно `YOUTRACK_OUTPUT_DIR`; абсолютные пути и сегменты `..` отвергаются.
+
+### Пагинация
+
+Большинство read-инструментов поддерживают `limit` (по умолчанию 100, максимум 200) и `skip` (по умолчанию 0); оба параметра прокидываются в YouTrack как `$top`/`$skip`. В ответах с агрегированным счётчиком используется поле `returned` (количество элементов на текущей странице) вместо `total`. Используйте последовательные значения `skip` для постраничного обхода больших выборок.
+
+### Подтверждение деструктивных операций
+
+Инструменты, удаляющие данные, требуют явного литерала `confirmation: true` во входных параметрах:
+
+- `issue_attachment_delete`
+- `issue_link_delete`
+- `workitem_delete`
 
 ### Сервис
 
@@ -298,7 +313,7 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | `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` — параметры сохранения файлов |
+| `issue_comments` | Комментарии задачи с серверной пагинацией. **Использование:** Просмотр всех комментариев к задаче. **Возвращает:** предопределенные поля - id, text, textPreview, usesMarkdown, author (id, login, name), created, updated, commentUrl (прямая ссылка на комментарий) | `issueId` — код задачи; `limit` (по умолчанию 100, макс 200), `skip` для пагинации; `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` |
@@ -312,10 +327,10 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `issue_links` | Список связей (линков) для задачи: «relates to», «duplicate», «parent/child». Возвращает id связи, направление (inward/outbound), тип связи и краткую информацию о связанной задаче | `issueId` — код задачи |
+| `issue_links` | Список связей (линков) для задачи с серверной пагинацией. Возвращает id связи, направление (inward/outbound), тип связи и краткую информацию о связанной задаче | `issueId` — код задачи; `limit` (по умолчанию 100, макс 200), `skip` для пагинации |
 | `issue_link_types` | Список доступных типов связей в YouTrack. Полезно для подбора корректного типа при создании связи | — |
 | `issue_link_add` | Создание связи между двумя задачами | `sourceId` — исходная задача, `targetId` — целевая задача, `linkType` — имя или id типа связи (например, `Relates` или UUID), опционально `direction` (`outbound` или `inbound`) |
-| `issue_link_delete` | Удаление существующей связи по её id для указанной задачи | `issueId` — код задачи, `linkId` — id связи для удаления |
+| `issue_link_delete` | Удаление существующей связи по её id (требует `confirmation: true`) | `issueId`, `linkId`, опционально `targetId`, `confirmation` — обязательно булев литерал `true` |
 
 **issue_create — дополнительные параметры:**
 
@@ -348,14 +363,14 @@ 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`; `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_list` | Получение трудозатрат текущего или указанного пользователя с серверной пагинацией. **Использование:** Просмотр учтенного времени, фильтрация по задаче, автору, периоду | Опционально `issueId`, `author`, `startDate`, `endDate`, `allUsers`; `limit` (по умолчанию 100, макс 200), `skip` для пагинации; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_all_users` | Получение трудозатрат всех пользователей с серверной пагинацией. **Возвращает:** те же поля, что и `workitems_list` | Опционально `issueId`, `startDate`, `endDate`; `limit` (по умолчанию 100, макс 200), `skip` для пагинации; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `workitems_for_users` | Получение трудозатрат выбранных пользователей с per-user пагинацией. **Возвращает:** те же поля, что и `workitems_list` | `users[]` — массив логинов пользователей, опционально `issueId`, `startDate`, `endDate`; `limit` (по умолчанию 100, макс 200), `skip` применяются на каждого пользователя; `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 записи трудозатрат |
+| `workitem_delete` | Удаление записи трудозатрат (требует `confirmation: true`). **Использование:** Удаление ошибочно созданных или неактуальных записей | `issueId`, `workItemId`, `confirmation` — обязательно булев литерал `true` |
 | `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` — включить всех пользователей; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
 | `workitems_report_invalid` | Список дней с отклонением от нормы времени. **Использование:** Поиск дней с недостатком или избытком учтенного времени, контроль соблюдения нормы. **Возвращает:** массив дней, где факт отличается от нормы, с детализацией по записям | Те же параметры, что и для `workitems_report_summary`; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
@@ -366,10 +381,10 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
-| `users_list` | Список всех пользователей YouTrack. **Использование:** Просмотр доступных пользователей, поиск логинов для назначения задач. **Возвращает:** предопределенные поля - id, login, name, fullName, email | `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
+| `users_list` | Список пользователей YouTrack с серверной пагинацией. **Использование:** Просмотр доступных пользователей, поиск логинов для назначения задач. **Возвращает:** предопределенные поля - id, login, name, fullName, email | `limit` (по умолчанию 100, макс 200), `skip` для пагинации; `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 | — |
+| `projects_list` | Список проектов YouTrack (по умолчанию авто-пагинация; для явной пагинации передайте `limit`/`skip`). **Возвращает:** предопределенные поля - id, shortName, name | Опционально `limit` (макс 200), `skip` |
 | `project_get` | Получение проекта по короткому имени. **Использование:** Получение внутреннего ID проекта по короткому имени (например, `PROJ` → внутренний ID) для создания задач. **Возвращает:** предопределенные поля - id, shortName, name | `shortName` — короткое имя проекта (например, `PROJ`, `BC`) |
 
 ### Статьи
@@ -377,7 +392,7 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | Tool | Описание | Основные параметры |
 | --- | --- | --- |
 | `article_get` | Получение статьи по ID. **Использование:** Чтение полного содержимого статьи базы знаний. **Возвращает:** предопределенные поля - id, idReadable, summary, content, contentPreview, usesMarkdown, parentArticle (id, idReadable), project (id, shortName, name) | `articleId` — ID статьи |
-| `article_list` | Список статей с фильтрами. **Использование:** Просмотр структуры базы знаний, навигация по статьям. **Возвращает:** предопределенные поля - id, idReadable, summary, usesMarkdown, parentArticle (id, idReadable), project (id, shortName, name). Поле content не включено для производительности | Опционально `parentArticleId` — фильтр по родительской статье, `projectId` — фильтр по проекту |
+| `article_list` | Список статей с фильтрами и серверной пагинацией. **Возвращает:** предопределенные поля - id, idReadable, summary, usesMarkdown, parentArticle (id, idReadable), project (id, shortName, name). Поле content не включено для производительности | Опционально `parentArticleId` — фильтр по родительской статье, `projectId` — фильтр по проекту; `limit` (по умолчанию 100, макс 200), `skip` для пагинации |
 | `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 содержимого; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
@@ -400,4 +415,4 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | `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` для подтверждения удаления (обязательный параметр безопасности) |
+| `issue_attachment_delete` | Удаление вложения из задачи YouTrack (требует `confirmation: true`). **Использование:** Удаление устаревших или ошибочно загруженных файлов. Это деструктивная операция, которую нельзя отменить. | `issueId`, `attachmentId`, `confirmation` — обязательно булев литерал `true` |

package/README.md

@@ -36,12 +36,15 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
     - [Setting up NPM\_TOKEN](#setting-up-npm_token)
     - [Release Process](#release-process)
     - [Manual Build \& Test](#manual-build--test)
+  - [Project Structure](#project-structure)
   - [Running the server (stdio)](#running-the-server-stdio)
   - [Configuration for Code (Recommended)](#configuration-for-code-recommended)
   - [Configuration for Claude Code CLI](#configuration-for-claude-code-cli)
   - [Configuration for VS Code Cline](#configuration-for-vs-code-cline)
   - [MCP Tools](#mcp-tools)
     - [File Storage Parameters](#file-storage-parameters)
+    - [Pagination](#pagination)
+    - [Destructive Operation Confirmation](#destructive-operation-confirmation)
     - [Service](#service)
     - [Issues](#issues)
     - [Issue Links](#issue-links)
@@ -58,7 +61,7 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
 
 ## Requirements
 
-- Node.js ≥ 20
+- Node.js ≥ 22
 - Environment variables:
   - `YOUTRACK_URL` — base URL of YouTrack instance
   - `YOUTRACK_TOKEN` — permanent token with read permissions for issues and work items
@@ -67,6 +70,8 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
 - `YOUTRACK_PRE_HOLIDAYS` — optional comma-separated list of pre-holiday dates with reduced working hours
 - `YOUTRACK_USER_ALIASES` — optional comma-separated list of `alias:login` mappings (e.g., `me:vyt,petya:p.petrov`), used for automatic assignee selection
 - `YOUTRACK_DEFAULT_PROJECT` — optional project code used for manual verification tasks and default parent issues in docs/examples (use `PROJ` in documentation examples)
+- `YOUTRACK_OUTPUT_DIR` — optional root directory for files produced by `saveToFile` and `downloadToFile`. Defaults to the current working directory. Absolute paths and parent-traversal segments (`..`) are rejected for safety
+- `YOUTRACK_UPLOAD_DIR` — optional whitelist root for source files used by `issue_attachment_upload`. Defaults to `YOUTRACK_OUTPUT_DIR`. Paths whose realpath escapes this directory (including via symlinks) are rejected to prevent reading arbitrary files (`/etc/passwd`, `~/.ssh/id_rsa`, etc.)
 
 
 ## Installation
@@ -120,7 +125,7 @@ This project uses GitHub Actions for continuous integration and automated releas
 
 Runs automatically on every push and pull request:
 - **Triggers**: All branches, all pull requests
-- **Node.js versions**: 20.x, 22.x (matrix testing)
+- **Node.js versions**: 22.x, 24.x (matrix testing)
 - **Steps**:
   1. Install dependencies (`npm ci`)
   2. Run linter (`npm run lint`)
@@ -131,7 +136,7 @@ Runs automatically on every push and pull request:
 
 Runs automatically when you create a new version tag:
 - **Trigger**: Git tags matching `v*` pattern (e.g., `v0.1.0`, `v1.2.3`)
-- **Node.js version**: 20.x
+- **Node.js version**: 24.x
 - **Steps**:
   1. Install dependencies
   2. Build project
@@ -199,6 +204,29 @@ npm run lint
 npm run dev:watch
 ```
 
+## Project Structure
+
+```
+src/
+  index.ts                MCP server entry point (stdio transport)
+  server.ts               MCP server bootstrap, tool registration
+  config.ts               YOUTRACK_* environment variable parsing
+  constants.ts            HTTP timeouts, body limits, PRE_HOLIDAY_RATIO
+  types.ts                Shared TypeScript interfaces and YouTrack entity discriminators
+  youtrack-client.ts      YouTrack REST client with caching and pagination helpers
+  tools/                  MCP tool registrations (one file per domain: issues, articles, ...)
+  utils/                  Reusable helpers (date, file-storage, mappers, validators, tool-args, ...)
+  __tests__/              Vitest tests against a nock-mocked HTTP layer
+docs/
+  reviews/                Project-check review reports
+.github/
+  workflows/              CI and publish workflows
+  dependabot.yml          Weekly npm + github-actions update PRs
+dist/                     Build output (generated by `npm run build`, gitignored)
+```
+
+The authoritative agent-oriented project layout lives in [AGENTS.md](AGENTS.md).
+
 ## Running the server (stdio)
 
 ```bash
@@ -283,11 +311,23 @@ To use this MCP server with [Cline](https://github.com/cline/cline) extension in
 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)
+- `filePath` — string, custom file path relative to `YOUTRACK_OUTPUT_DIR` (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.
+When `saveToFile` is `true`, tools return metadata about the saved file instead of the full data. All paths are resolved against `YOUTRACK_OUTPUT_DIR`; absolute paths and `..` traversal segments are rejected.
+
+### Pagination
+
+Most read tools accept `limit` (default 100, max 200) and `skip` (default 0); both are forwarded to YouTrack as `$top`/`$skip`. Tools that return aggregated counts use `returned` (count of items in the current page) rather than `total`. Use successive `skip` values to walk through large result sets.
+
+### Destructive Operation Confirmation
+
+Tools that delete data require an explicit `confirmation: true` literal in their input:
+
+- `issue_attachment_delete`
+- `issue_link_delete`
+- `workitem_delete`
 
 ### Service
 
@@ -303,7 +343,7 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 | `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 |
+| `issue_comments` | Issue comments with server-side pagination | `issueId` — issue code; `limit` (default 100, max 200), `skip` for pagination; `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` |
@@ -316,16 +356,16 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 | `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`) |
+| `issue_attachment_delete` | Delete attachment (requires `confirmation: true`) | `issueId`, `attachmentId`, `confirmation` (must be the boolean literal `true`) |
 
 ### Issue Links
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `issue_links` | List links for an issue (relates to, duplicate, parent/child). Returns link id, direction, linkType, and counterpart issue brief | `issueId` — issue code |
-| `issue_link_types` | List available link types | — |
+| `issue_links` | List links for an issue with server-side pagination. Returns link id, direction, linkType, and counterpart issue brief | `issueId` — issue code; `limit` (default 100, max 200), `skip` for pagination |
+| `issue_link_types` | List available link types (cached single-flight) | — |
 | `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 |
+| `issue_link_delete` | Delete a link by id for a specific issue (requires `confirmation: true`) | `issueId`, `linkId`, optionally `targetId`, `confirmation` (must be the boolean literal `true`) |
 
 ### Issues Status
 
@@ -348,14 +388,14 @@ 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`; `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_list` | Get work items for current or specified user with server-side pagination | Optionally `issueId`, `author`, `startDate`, `endDate`, `allUsers`; `limit` (default 100, max 200), `skip` for pagination; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_all_users` | Get work items for all users with server-side pagination | Optionally `issueId`, `startDate`, `endDate`; `limit` (default 100, max 200), `skip` for pagination; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `workitems_for_users` | Get work items for selected users with per-user pagination | `users[]`, optionally `issueId`, `startDate`, `endDate`; `limit` (default 100, max 200), `skip` applied per user; `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` |
+| `workitem_delete` | Delete work item (requires `confirmation: true`) | `issueId`, `workItemId`, `confirmation` (must be the boolean literal `true`) |
 | `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`; `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 |
@@ -366,10 +406,10 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
-| `users_list` | List all YouTrack users | `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
+| `users_list` | List all YouTrack users with server-side pagination | `limit` (default 100, max 200), `skip` for pagination; `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 | — |
+| `projects_list` | List all YouTrack projects (auto-paginated by default; pass `limit`/`skip` for explicit paging) | Optional `limit` (max 200), `skip` |
 | `project_get` | Get project by short name | `shortName` — project short name |
 
 ### Articles
@@ -377,7 +417,7 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
 | `article_get` | Get article by ID | `articleId` |
-| `article_list` | List articles with filters | Optionally `parentArticleId`, `projectId` |
+| `article_list` | List articles with filters and server-side pagination | Optionally `parentArticleId`, `projectId`; `limit` (default 100, max 200), `skip` for pagination |
 | `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`; `saveToFile`, `filePath`, `format`, `overwrite` — file storage options |
@@ -403,9 +443,11 @@ When `saveToFile` is `true`, tools return metadata about the saved file instead
 
 ### Destructive Operations
 
-Some operations cannot be undone and require explicit confirmation:
+Some operations cannot be undone and require an explicit `confirmation: true` literal in their input:
 
-- **`issue_attachment_delete`** - Requires `confirmation: true` parameter. Deleted attachments cannot be recovered.
+- **`issue_attachment_delete`** — deleted attachments cannot be recovered.
+- **`issue_link_delete`** — re-fetch `issue_links` afterwards to verify the relationship was removed.
+- **`workitem_delete`** — work item entries are permanently lost; re-fetch `workitems_list` to confirm.
 **issue_create parameters:**
 
 - `parentIssueId` — resolves against `YOUTRACK_DEFAULT_PROJECT` when no project prefix is provided (e.g., `123` → `BC-123` if default project is `BC`).

package/dist/package.json

@@ -1,15 +1,20 @@
 {
     "name": "@vitalyostanin/youtrack-mcp",
-    "version": "0.10.2",
+    "version": "0.12.0",
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "postbuild": "chmod +x dist/index.js",
         "dev": "tsc -p tsconfig.json --watch",
         "start": "node dist/index.js",
         "dev:watch": "tsc -p tsconfig.json --watch",
-        "lint": "eslint .",
-        "lint:fix": "eslint . --fix",
-        "prepublishOnly": "npm run build"
+        "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
+        "lint:fix": "eslint . --fix --cache --cache-location node_modules/.cache/eslint/",
+        "format": "eslint . --fix --cache --cache-location node_modules/.cache/eslint/",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "prepublishOnly": "npm run lint && npm test && npm run build"
     },
     "keywords": [
         "mcp",
@@ -26,7 +31,7 @@
     "description": "MCP server for comprehensive YouTrack integration: issues, work items with reports, user activity search, knowledge base, projects and users",
     "type": "module",
     "engines": {
-        "node": ">=20.0.0"
+        "node": ">=22.0.0"
     },
     "bin": {
         "youtrack-mcp": "dist/index.js"
@@ -50,21 +55,25 @@
         "access": "public"
     },
     "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.20.0",
+        "@modelcontextprotocol/sdk": "^1.29.0",
         "@vitalyostanin/mutex-pool": "^0.0.3",
-        "axios": "^1.12.2",
+        "axios": "^1.16.0",
         "form-data": "^4.0.1",
         "luxon": "^3.5.0",
+        "stream-json": "^2.1.0",
         "zod": "^3.25.76"
     },
     "devDependencies": {
         "@eslint/js": "^9.37.0",
         "@types/luxon": "^3.7.1",
-        "@types/node": "^22.18.10",
+        "@types/node": "^22.19.17",
         "@vitalyostanin/eslint-prefer-de-morgan-law": "^1.0.2",
+        "@vitest/coverage-v8": "^4.1.5",
         "eslint": "^9.37.0",
+        "nock": "^14.0.14",
         "typescript": "^5.6.2",
         "typescript-eslint": "^8.46.0",
+        "vitest": "^4.1.5",
         "zod-to-json-schema": "^3.24.6"
     }
 }

package/dist/src/__tests__/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/src/__tests__/config.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { loadConfig, enrichConfigWithRedaction } from "../config.js";
+describe("loadConfig", () => {
+    let tmp;
+    const oldEnv = { ...process.env };
+    beforeEach(() => {
+        tmp = mkdtempSync(join(tmpdir(), "yt-cfg-"));
+        process.env = {
+            YOUTRACK_URL: "https://yt.example.com",
+            YOUTRACK_TOKEN: "perm:test-token",
+        };
+    });
+    afterEach(() => {
+        rmSync(tmp, { recursive: true, force: true });
+        process.env = { ...oldEnv };
+    });
+    it("uses cwd by default for outputDir", () => {
+        const cfg = loadConfig();
+        expect(cfg.outputDir).toBe(resolve(process.cwd()));
+    });
+    it("honors YOUTRACK_OUTPUT_DIR", () => {
+        process.env.YOUTRACK_OUTPUT_DIR = tmp;
+        const cfg = loadConfig();
+        expect(cfg.outputDir).toBe(resolve(tmp));
+    });
+    it("creates outputDir if missing", () => {
+        const sub = join(tmp, "missing-subdir");
+        process.env.YOUTRACK_OUTPUT_DIR = sub;
+        loadConfig();
+        expect(existsSync(sub)).toBe(true);
+    });
+    it("throws when YOUTRACK_TOKEN is missing", () => {
+        delete process.env.YOUTRACK_TOKEN;
+        expect(() => loadConfig()).toThrow();
+    });
+    it("redacts token via enrichConfigWithRedaction", () => {
+        const cfg = loadConfig();
+        const redacted = enrichConfigWithRedaction(cfg);
+        expect(redacted.hasToken).toBe(true);
+        expect(redacted.token).toBeUndefined();
+        expect(redacted.outputDir).toBe(cfg.outputDir);
+    });
+});
+//# sourceMappingURL=config.test.js.map

package/dist/src/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/src/__tests__/setup.js

@@ -0,0 +1,12 @@
+import { afterAll, afterEach, beforeAll } from "vitest";
+import nock from "nock";
+beforeAll(() => {
+    nock.disableNetConnect();
+});
+afterEach(() => {
+    nock.cleanAll();
+});
+afterAll(() => {
+    nock.enableNetConnect();
+});
+//# sourceMappingURL=setup.js.map

package/dist/src/__tests__/smoke.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=smoke.test.d.ts.map

package/dist/src/__tests__/smoke.test.js

@@ -0,0 +1,7 @@
+import { describe, it, expect } from "vitest";
+describe("smoke", () => {
+    it("vitest is wired", () => {
+        expect(1 + 1).toBe(2);
+    });
+});
+//# sourceMappingURL=smoke.test.js.map

package/dist/src/__tests__/youtrack-client.delete-link.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=youtrack-client.delete-link.test.d.ts.map

package/dist/src/__tests__/youtrack-client.delete-link.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from "vitest";
+import { YoutrackClient } from "../youtrack-client.js";
+const config = {
+    baseUrl: "https://yt.test",
+    token: "perm:test",
+    defaultProject: "BC",
+    outputDir: "/tmp",
+    timezone: "UTC",
+};
+function getHttp(client) {
+    return client.http;
+}
+function methodNotAllowed() {
+    return {
+        isAxiosError: true,
+        message: "Request failed with status code 405",
+        response: { status: 405, data: { error: "method_not_allowed" } },
+    };
+}
+describe("deleteIssueLink subtask fallback", () => {
+    it("uses linkToDelete.issue.idReadable when targetId is missing", async () => {
+        const client = new YoutrackClient(config);
+        const http = getHttp(client);
+        vi.spyOn(http, "delete").mockRejectedValue(methodNotAllowed());
+        vi.spyOn(client, "getIssueLinks").mockResolvedValue({
+            issueId: "BC-1",
+            links: [
+                {
+                    id: "L1",
+                    direction: "OUTWARD",
+                    linkType: { name: "Subtask", id: "lt-sub" },
+                    issue: { idReadable: "BC-99", id: "1-99", summary: "s" },
+                },
+            ],
+        });
+        let captured;
+        vi.spyOn(http, "post").mockImplementation((...args) => {
+            captured = { url: String(args[0]), body: args[1] };
+            return Promise.resolve({ data: {} });
+        });
+        await client.deleteIssueLink({ issueId: "BC-1", linkId: "L1" });
+        expect(captured?.url).toBe("/api/commands");
+        expect(captured?.body.query).toBe("remove subtask of BC-99");
+        const issues = captured?.body.issues;
+        expect(issues[0].idReadable).toBe("BC-1");
+    });
+    it("uses provided targetId when given (regular link)", async () => {
+        const client = new YoutrackClient(config);
+        const http = getHttp(client);
+        vi.spyOn(http, "delete").mockRejectedValue(methodNotAllowed());
+        vi.spyOn(client, "getIssueLinks").mockResolvedValue({
+            issueId: "BC-1",
+            links: [
+                {
+                    id: "L1",
+                    direction: "OUTWARD",
+                    linkType: {
+                        name: "Relates",
+                        id: "lt-rel",
+                        outwardName: "relates to",
+                        inwardName: "relates to",
+                    },
+                    issue: { idReadable: "BC-99", id: "1-99", summary: "s" },
+                },
+            ],
+        });
+        let captured;
+        vi.spyOn(http, "post").mockImplementation((...args) => {
+            captured = { body: args[1] };
+            return Promise.resolve({ data: {} });
+        });
+        await client.deleteIssueLink({ issueId: "BC-1", linkId: "L1", targetId: "BC-7" });
+        expect(String(captured?.body.query)).toContain("BC-7");
+    });
+    it("throws when neither input.targetId nor link payload provide a target", async () => {
+        const client = new YoutrackClient(config);
+        const http = getHttp(client);
+        vi.spyOn(http, "delete").mockRejectedValue(methodNotAllowed());
+        vi.spyOn(client, "getIssueLinks").mockResolvedValue({
+            issueId: "BC-1",
+            links: [
+                {
+                    id: "L1",
+                    direction: "OUTWARD",
+                    linkType: { name: "Subtask", id: "lt-sub" },
+                    issue: { idReadable: "", id: "1-99", summary: "s" },
+                },
+            ],
+        });
+        await expect(client.deleteIssueLink({ issueId: "BC-1", linkId: "L1" })).rejects.toThrow(/Cannot determine target issue id/);
+    });
+});
+//# sourceMappingURL=youtrack-client.delete-link.test.js.map

package/dist/src/__tests__/youtrack-client.normalize-error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=youtrack-client.normalize-error.test.d.ts.map