# YouTrack MCP Server

[![CI](https://github.com/VitalyOstanin/youtrack-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/VitalyOstanin/youtrack-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/VitalyOstanin/youtrack-mcp/graph/badge.svg?branch=master)](https://codecov.io/gh/VitalyOstanin/youtrack-mcp)
[![npm version](https://img.shields.io/npm/v/@vitalyostanin/youtrack-mcp.svg)](https://www.npmjs.com/package/@vitalyostanin/youtrack-mcp)

MCP сервер для полноценной интеграции с YouTrack со следующими возможностями:

- **Управление задачами** - создание, обновление, комментирование, назначение, изменение статуса, пакетные операции
- **Звездочки для задач** - отметка важных задач звездочками, массовое добавление (до 50), список отмеченных задач
- **Управление вложениями** - загрузка файлов (до 10), скачивание по подписанным URL, удаление
- **Учёт трудозатрат** - создание записей с идемпотентными операциями, массовое создание за период
- **Детальные отчёты по времени** - сводные отчёты, анализ отклонений, статистика по пользователям
- **Расширенный поиск** - поиск задач по активности пользователей с быстрым/точным режимами фильтрации
- **История изменений** - полный журнал активности задач с фильтрацией и пагинацией
- **База знаний** - создание, обновление, поиск статей с иерархической структурой
- **Доступ к пользователям и проектам** - получение информации о пользователях и проектах
- **Пакетные операции** - эффективная обработка до 50 задач одновременно
- **Сохранение в файлы** - сохранение больших результатов инструментов в JSON файлы вместо прямого возврата
- **Дополнительные возможности** - поддержка Markdown, сворачиваемые секции, конфигурация праздников, алиасы пользователей

## Содержание

- [YouTrack MCP Server](#youtrack-mcp-server)
  - [Содержание](#содержание)
  - [Требования](#требования)
  - [Установка](#установка)
    - [Используя npx (Рекомендуется)](#используя-npx-рекомендуется)
    - [Используя Claude MCP CLI](#используя-claude-mcp-cli)
    - [Ручная установка (Для разработки)](#ручная-установка-для-разработки)
  - [Разработка и релиз](#разработка-и-релиз)
    - [GitHub Actions Workflows](#github-actions-workflows)
      - [CI Workflow (`.github/workflows/ci.yml`)](#ci-workflow-githubworkflowsciyml)
      - [Publish Workflow (`.github/workflows/publish.yml`)](#publish-workflow-githubworkflowspublishyml)
    - [Настройка NPM\_TOKEN](#настройка-npm_token)
    - [Процесс релиза](#процесс-релиза)
    - [Ручная сборка и тестирование](#ручная-сборка-и-тестирование)
  - [Запуск сервера (stdio)](#запуск-сервера-stdio)
  - [Конфигурация для Code (Рекомендуется)](#конфигурация-для-code-рекомендуется)
  - [Конфигурация для Claude Code CLI](#конфигурация-для-claude-code-cli)
  - [Конфигурация для VS Code Cline](#конфигурация-для-vs-code-cline)
  - [Инструменты MCP](#инструменты-mcp)
    - [Параметры сохранения файлов](#параметры-сохранения-файлов)
    - [Пагинация](#пагинация)
    - [Подтверждение деструктивных операций](#подтверждение-деструктивных-операций)
    - [Сервис](#сервис)
    - [Задачи](#задачи)
    - [Связи задач](#связи-задач)
    - [Статусы задач](#статусы-задач)
    - [Звездочки задач](#звездочки-задач)
    - [Вложения](#вложения)
    - [Трудозатраты](#трудозатраты)
    - [Пользователи и проекты](#пользователи-и-проекты)
    - [Статьи](#статьи)
    - [Лента активности](#лента-активности)

## Требования

- Node.js ≥ 20
- Переменные окружения:
  - `YOUTRACK_URL` — базовый URL YouTrack
  - `YOUTRACK_TOKEN` — постоянный токен с правами на чтение задач и work items
  - `YOUTRACK_TIMEZONE` — опциональная таймзона для операций с датами (по умолчанию: `Europe/Moscow`), должна быть валидным идентификатором IANA (например, `Europe/London`, `America/New_York`, `Asia/Tokyo`)
  - `YOUTRACK_HOLIDAYS` — опциональный список праздничных дат через запятую (формат `YYYY-MM-DD`), исключаемых из отчётов и массовых операций
  - `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`. По умолчанию используется текущий рабочий каталог. Абсолютные пути и сегменты с `..` (выход за пределы корня) отвергаются ради безопасности


## Установка

### Используя npx (Рекомендуется)

Вы можете запустить сервер напрямую через npx без установки:

```bash
YOUTRACK_URL="https://youtrack.example.com" \
YOUTRACK_TOKEN="perm:your-token-here" \
YOUTRACK_DEFAULT_PROJECT="PROJ" \
npx -y @vitalyostanin/youtrack-mcp@latest
```

### Используя Claude MCP CLI

Установка через Claude MCP CLI:

```bash
claude mcp add --scope user \
--env YOUTRACK_URL='https://youtrack.example.com' \
--env YOUTRACK_TOKEN='perm:my-token' \
youtrack-mcp -- npx -y @vitalyostanin/youtrack-mcp@latest
```

**Опции области видимости:**
- `--scope user`: Установка для текущего пользователя (для всех проектов)
- `--scope project`: Установка только для текущего проекта

**Удаление:**

```bash
claude mcp remove youtrack-mcp --scope user
```

### Ручная установка (Для разработки)

```bash
npm install
npm run build
```

## Разработка и релиз

### GitHub Actions Workflows

Проект использует GitHub Actions для непрерывной интеграции и автоматизированных релизов:

#### CI Workflow (`.github/workflows/ci.yml`)

Запускается автоматически при каждом push и pull request:
- **Триггеры**: Все ветки, все pull request'ы
- **Версии Node.js**: 20.x, 22.x (матричное тестирование)
- **Шаги**:
  1. Установка зависимостей (`npm ci`)
  2. Запуск линтера (`npm run lint`)
  3. Сборка проекта (`npm run build`)
  4. Проверка артефактов сборки (проверка исполняемости)

#### Publish Workflow (`.github/workflows/publish.yml`)

Запускается автоматически при создании нового тега версии:
- **Триггер**: Git теги с паттерном `v*` (например, `v0.1.0`, `v1.2.3`)
- **Версия Node.js**: 20.x
- **Шаги**:
  1. Установка зависимостей
  2. Сборка проекта
  3. Публикация в npm реестр
  4. Создание GitHub Release

### Настройка NPM_TOKEN

Для автоматической публикации в npm необходимо настроить секрет `NPM_TOKEN`:

1. **Создание npm Access Token**:
   - Перейдите на [npmjs.com](https://www.npmjs.com/) и войдите
   - Откройте **Access Tokens** в настройках аккаунта
   - Нажмите **Generate New Token** → **Classic Token**
   - Выберите тип **Automation** (для CI/CD)
   - Скопируйте сгенерированный токен

2. **Добавление секрета в GitHub**:
   - Перейдите в репозиторий на GitHub
   - Откройте **Settings** → **Secrets and variables** → **Actions**
   - Нажмите **New repository secret**
   - Имя: `NPM_TOKEN`
   - Значение: Вставьте ваш npm токен
   - Нажмите **Add secret**

### Процесс релиза

Для создания нового релиза:

```bash
# 1. Обновить версию в package.json и создать git тег
npm version patch   # для 0.1.0 → 0.1.1
# или
npm version minor   # для 0.1.0 → 0.2.0
# или
npm version major   # для 0.1.0 → 1.0.0

# 2. Отправить тег на GitHub
git push --follow-tags

# 3. GitHub Actions автоматически:
#    - Запустит тесты и сборку
#    - Опубликует в npm
#    - Создаст GitHub Release
```

**Примечание**: Команда `npm version` автоматически:
- Обновляет `package.json` и `package-lock.json`
- Создаёт git commit с сообщением типа "0.1.1"
- Создаёт git тег типа "v0.1.1"

### Ручная сборка и тестирование

```bash
# Установка зависимостей
npm install

# Сборка проекта
npm run build

# Запуск линтера
npm run lint

# Режим watch для разработки
npm run dev:watch
```

## Запуск сервера (stdio)

```bash
YOUTRACK_URL="https://youtrack.example.com" \
YOUTRACK_TOKEN="perm:example-token" \
node dist/index.js
```

## Конфигурация для Code (Рекомендуется)
Добавьте в `~/.code/config.toml`:
```toml
[mcp_servers.youtrack-mcp]
command = "npx"
args = ["-y", "@vitalyostanin/youtrack-mcp@latest"]

[mcp_servers.youtrack-mcp.env]
YOUTRACK_URL = "https://youtrack.example.com"
YOUTRACK_TOKEN = "perm:your-token-here"
```

## Конфигурация для Claude Code CLI

Чтобы использовать этот MCP сервер с [Claude Code CLI](https://github.com/anthropics/claude-code), вы можете:

1. **Использовать Claude MCP CLI** - смотрите секцию [Установка](#установка) выше
2. **Ручная конфигурация** - добавьте в файл `~/.claude.json`:

```json
{
  "mcpServers": {
    "youtrack-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vitalyostanin/youtrack-mcp@latest"],
      "env": {
        "YOUTRACK_URL": "https://youtrack.example.com",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}
```

**Примечание:** Эта конфигурация использует npx для запуска опубликованного пакета. Для локальной разработки используйте `"command": "node"` с `"args": ["/абсолютный/путь/к/youtrack-mcp/dist/index.js"]`. Переменные окружения `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HOLIDAYS` и `YOUTRACK_USER_ALIASES` являются опциональными.



## Конфигурация для VS Code Cline

Чтобы использовать этот MCP сервер с расширением [Cline](https://github.com/cline/cline) в VS Code:

1. Откройте VS Code с установленным расширением Cline
2. Нажмите на иконку MCP Servers в верхней навигации Cline
3. Выберите вкладку "Configure" и нажмите "Configure MCP Servers"
4. Добавьте следующую конфигурацию в `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "youtrack-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/youtrack-mcp@latest"],
      "env": {
        "YOUTRACK_URL": "https://youtrack.example.com",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}
```



**Примечание:** Эта конфигурация использует npx для запуска опубликованного пакета. Для локальной разработки используйте `"command": "node"` с `"args": ["/абсолютный/путь/к/youtrack-mcp/dist/index.js"]`. Переменные окружения `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HОЛИДAYS` и `YOUTRACK_USER_ALIASES` являются опциональными.

## Инструменты MCP



### Параметры сохранения файлов

Многие инструменты поддерживают опциональные параметры сохранения файлов для работы с большими датасетами:

- `saveToFile` — boolean, сохраняет результаты в JSON файл вместо возврата напрямую (полезно для больших датасетов)
- `filePath` — string, пользовательский путь к файлу относительно `YOUTRACK_OUTPUT_DIR` (опционально, генерируется автоматически если не указан, директория создается при необходимости)
- `format` — string, формат вывода при сохранении в файл: `jsonl` (JSON Lines) или `json` (JSON массив). По умолчанию `jsonl`
- `overwrite` — boolean, разрешить перезапись существующих файлов при использовании явного пути к файлу. По умолчанию `false`

Когда `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`

### Сервис

| Tool | Описание | Основные параметры |
| --- | --- | --- |
| `service_info` | Проверить доступность YouTrack и текущего пользователя. **Использование:** Проверка подключения, верификация аутентификации, получение информации о текущем пользователе API. **Возвращает:** информацию о YouTrack-сервере и текущем пользователе | — |

### Задачи

| Tool | Описание | Основные параметры |
| --- | --- | --- |
| `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` — код задачи; `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`, `customFields[]`, `inheritCustomFieldsFromParent`, `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` для пагинации; `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов |
| `issue_change_state` | Изменение состояния/статуса задачи через переходы workflow. **Использование:** Перемещение задач через состояния рабочего процесса (например, 'Открыта' → 'В работе'). Автоматически определяет доступные переходы и валидирует запрошенное изменение состояния. Регистронезависимое сопоставление имён состояний. **Возвращает:** информацию о предыдущем состоянии, новом состоянии и использованном переходе | `issueId` — код задачи, `stateName` — имя целевого состояния (например, 'В работе', 'Открыта', 'Исправлена', 'Проверена'). Регистронезависимое |

### Связи задач

| Tool | Описание | Основные параметры |
| --- | --- | --- |
| `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 (требует `confirmation: true`) | `issueId`, `linkId`, опционально `targetId`, `confirmation` — обязательно булев литерал `true` |

**issue_create — дополнительные параметры:**

- `parentIssueId` — если указан только числовой идентификатор (`"123"`), автоматически добавляет префикс проекта по умолчанию (например, `BC-123`).
- `customFields[]` — опциональные кастомные поля при создании. Каждый элемент содержит `name` и `value` (строка или массив строк для мультизначных полей). Типы полей проекта резолвятся через `/api/admin/projects/{projectId}/customFields`.
- `inheritCustomFieldsFromParent` — при `true` (по умолчанию) и указанном `parentIssueId` копирует кастомные поля родителя, кроме `State` и `Assignee`. Явные `customFields` переопределяют унаследованные значения.
- `parentIssueId` — дополнительно создаёт связь `Subtask` с родителем после сохранения задачи (проверяйте через `issue_links`).
- `links[]` — массив объектов для создания связей после сохранения задачи. Каждый объект поддерживает поля:
  - `linkType` — имя или id типа связи (например, `Subtask`, `Relates`).
  - `targetId` — idReadable задачи или числовой идентификатор, который также резолвится через проект по умолчанию.
  - `direction` — опционально (`"outbound"` по умолчанию). Используйте `"inbound"`, чтобы инвертировать направление для несимметричных типов.
  - `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 | Описание | Основные параметры |
| --- | --- | --- |
| `issue_star` | Добавление звездочки к задаче для текущего пользователя. **Использование:** Отметка важных задач, добавление задач в список наблюдения, быстрый доступ к часто используемым задачам. **Возвращает:** подтверждение статуса звездочки с issueId и флагом starred. **Примечание:** Идемпотентная операция - возвращает успех, даже если задача уже отмечена звездочкой | `issueId` — код задачи (например, `PROJ-123`) |
| `issue_unstar` | Удаление звездочки у задачи для текущего пользователя. **Использование:** Удаление задач из списка наблюдения, очистка ненужных звездочек, управление списком отмеченных задач. **Возвращает:** подтверждение операции снятия звездочки с issueId и флагом starred. **Примечание:** Идемпотентная операция - возвращает успех, даже если задача не была отмечена звездочкой | `issueId` — код задачи |
| `issues_star_batch` | Добавление звездочек к нескольким задачам (пакетный режим, макс 50 задач). **Использование:** Массовая отметка важных задач, пакетное добавление в список наблюдения, обработка нескольких задач одновременно, быстрая настройка списка отмеченных задач. **Возвращает:** объект с массивами `successful` (отмеченные задачи) и `failed` (ошибки с ID задач). **Примечание:** Операции обрабатываются с ограничением конкурентности (10 одновременных запросов) для предотвращения перегрузки API. Возможен частичный успех - некоторые задачи могут быть обработаны успешно, а другие - нет | `issueIds[]` — массив кодов задач (например, `['PROJ-123', 'PROJ-124']`), макс 50 |
| `issues_unstar_batch` | Удаление звездочек у нескольких задач (пакетный режим, макс 50 задач). **Использование:** Массовая очистка списка наблюдения, пакетное удаление ненужных звездочек, обработка нескольких задач одновременно, управление списком отмеченных задач. **Возвращает:** объект с массивами `successful` (задачи с удаленными звездочками) и `failed` (ошибки с ID задач). **Примечание:** Операции обрабатываются с ограничением конкурентности (10 одновременных запросов) для предотвращения перегрузки API. Возможен частичный успех - некоторые задачи могут быть обработаны успешно, а другие - нет | `issueIds[]` — массив кодов задач, макс 50 |
| `issues_starred_list` | Получение всех отмеченных звездочками задач для текущего пользователя. **Использование:** Просмотр списка наблюдения, получение часто используемых задач, поиск всех отмеченных важных задач, проверка наличия звездочек у задач. **Возвращает:** массив отмеченных задач (краткий формат без description) и общее количество. **Примечание:** Ограничено 200 задачами за запрос. Результаты включают только базовую информацию (id, idReadable, summary, project, parent, assignee) без description для уменьшения размера ответа. Опциональное поле message в ответах star/unstar предоставляет информацию о статусе операции (например, 'Issue already starred', 'Issue starred successfully') | Опционально `limit` — максимальное количество задач (по умолчанию 50, макс 200), `skip` — количество задач для пропуска при пагинации (по умолчанию 0) |

### Трудозатраты

| Tool | Описание | Основные параметры |
| --- | --- | --- |
| `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` | Удаление записи трудозатрат (требует `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` — параметры сохранения файлов |
| `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 | `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 (по умолчанию авто-пагинация; для явной пагинации передайте `limit`/`skip`). **Возвращает:** предопределенные поля - id, shortName, name | Опционально `limit` (макс 200), `skip` |
| `project_get` | Получение проекта по короткому имени. **Использование:** Получение внутреннего ID проекта по короткому имени (например, `PROJ` → внутренний ID) для создания задач. **Возвращает:** предопределенные поля - id, shortName, name | `shortName` — короткое имя проекта (например, `PROJ`, `BC`) |

### Статьи

| 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` — фильтр по проекту; `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` — параметры сохранения файлов |
| `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` (расширенный перегруз возвращаемых полей); `saveToFile`, `filePath`, `format`, `overwrite` — параметры сохранения файлов. |

### Вложения

| Tool | Описание | Основные параметры |
| --- | --- | --- |
| `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: true`). **Использование:** Удаление устаревших или ошибочно загруженных файлов. Это деструктивная операция, которую нельзя отменить. | `issueId`, `attachmentId`, `confirmation` — обязательно булев литерал `true` |