@vitalyostanin/youtrack-mcp 0.2.0

package/README-ru.md

@@ -0,0 +1,283 @@
+# 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)
+[![npm version](https://img.shields.io/npm/v/@vitalyostanin/youtrack-mcp.svg)](https://www.npmjs.com/package/@vitalyostanin/youtrack-mcp)
+
+MCP сервер для полноценной интеграции с YouTrack. Управление задачами, учёт трудозатрат с детальными отчётами, поиск по активности пользователей, работа со статьями базы знаний, доступ к проектам и пользователям. Поддержка учёта времени с конфигурацией праздников/предпраздничных дней, пакетные операции и структурированные ответы для AI-клиентов.
+
+## Содержание
+
+- [YouTrack MCP Server](#youtrack-mcp-server)
+  - [Содержание](#содержание)
+  - [Требования](#требования)
+  - [Установка](#установка)
+  - [Разработка и релиз](#разработка-и-релиз)
+  - [Запуск сервера (stdio)](#запуск-сервера-stdio)
+  - [Конфигурация для Code (Рекомендуется)](#конфигурация-для-code-рекомендуется)
+  - [Конфигурация для Claude Code CLI](#конфигурация-для-claude-code-cli)
+  - [Инструменты 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`), используется при автоматическом выборе исполнителей
+
+## Установка
+
+### Используя npx (Рекомендуется)
+
+Вы можете запустить сервер напрямую через npx без установки:
+
+```bash
+YOUTRACK_URL="https://youtrack.example.com" \
+YOUTRACK_TOKEN="perm:your-token-here" \
+npx -y @vitalyostanin/youtrack-mcp
+```
+
+### Используя Claude MCP CLI
+
+Установка через Claude MCP CLI:
+
+```bash
+claude mcp add --scope user youtrack-mcp npx -y @vitalyostanin/youtrack-mcp
+```
+
+После выполнения команды вас попросят ввести URL YouTrack и токен.
+
+**Опции области видимости:**
+- `--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 (Рекомендуется)
+
+Чтобы использовать этот MCP сервер с [Code](https://github.com/just-every/code), добавьте следующую конфигурацию в `~/.code/config.toml`:
+
+```toml
+[mcp_servers.youtrack-mcp]
+command = "npx"
+args = ["-y", "@vitalyostanin/youtrack-mcp"]
+env = { "YOUTRACK_URL" = "https://youtrack.example.com", "YOUTRACK_TOKEN" = "perm:your-token-here" }
+```
+
+**Примечание:** Эта конфигурация использует npx для запуска опубликованного пакета. Альтернативно, для локальной разработки используйте `command = "node"` с `args = ["/path/to/dist/index.js"]`.
+
+## Конфигурация для 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"],
+      "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` являются опциональными.
+
+## Инструменты MCP
+
+Все инструменты возвращают `structuredContent` с флагом `success` и полезной нагрузкой в формате, ожидаемом клиентами MCP. Каждый инструмент включает подсказки по использованию, примеры параметров и объяснение ключевых полей ответа.
+
+### Сервис
+
+| Tool | Описание | Основные параметры |
+| --- | --- | --- |
+| `service_info` | Проверить доступность YouTrack и текущего пользователя. **Использование:** Проверка подключения, верификация аутентификации, получение информации о текущем пользователе API. **Возвращает:** информацию о YouTrack-сервере и текущем пользователе | — |
+
+### Задачи
+
+| 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']`) |
+| `issue_details` | Полные данные о задаче. **Использование:** Получение детальной информации о задаче, включая даты создания/обновления/решения, автора, обновившего пользователя. **Возвращает:** расширенный набор полей - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project, parent, assignee, reporter, updater. Пользовательские поля не включены. | `issueId` — код задачи |
+| `issues_details` | Детальная информация о нескольких задачах (пакетный режим, макс 50). **Использование:** Эффективное получение детальной информации о множестве задач. **Возвращает:** те же поля, что и `issue_details`. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач |
+| `issue_comments` | Комментарии задачи. **Использование:** Просмотр всех комментариев к задаче. **Возвращает:** предопределенные поля - id, text, textPreview, usesMarkdown, author (id, login, name), created, updated | `issueId` — код задачи |
+| `issues_comments` | Комментарии для нескольких задач (пакетный режим, макс 50). **Использование:** Эффективное получение комментариев для множества задач одновременно. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач |
+| `issue_create` | Создание новой задачи в YouTrack. **Использование:** Создание задач, подзадач (через `parentIssueId`), назначение исполнителя при создании. **Возвращает:** стандартные поля созданной задачи (id, idReadable, summary, description, wikifiedDescription, usesMarkdown, project, parent, assignee). Пользовательские поля не включены. | `projectId` — ID проекта (внутренний YouTrack ID), `summary` — краткое описание задачи, опционально `description`, `parentIssueId`, `assigneeLogin` (логин или `me`), `usesMarkdown` |
+| `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_search_by_user_activity` | Поиск задач по активности пользователей в заданный период. **Использование:** Поиск задач, где пользователи обновляли, были упомянуты, создавали, были назначены или комментировали. Поддерживает два режима фильтрации: `issue_updated` (по умолчанию, быстрый) использует поле issue.updated, `user_activity` (медленный, точный) проверяет фактические даты активности пользователя, включая комментарии, упоминания и историю изменений полей. **Когда использовать точный режим:** когда нужна точная дата участия пользователя (например, когда пользователь был исполнителем, но позже был изменён). **Возвращает:** краткую информацию о задачах (id, idReadable, summary, project, parent, assignee) без description для уменьшения размера ответа. В режиме `user_activity` включает поле `lastActivityDate` с точной датой последней активности пользователя. Результаты отсортированы по времени активности (новые первыми). Поддерживает пагинацию. **Ограничение:** по умолчанию 100 задач, макс 200 | `userLogins[]` — массив логинов пользователей для поиска активности (updater, mentions, reporter, assignee, commenter), опционально `startDate` (формат YYYY-MM-DD или timestamp), `endDate`, `dateFilterMode` (`issue_updated` или `user_activity`), `limit` (по умолчанию 100, макс 200), `skip` для пагинации |
+
+### Трудозатраты
+
+| 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) |
+| `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` |
+
+### Пользователи и проекты
+
+| Tool | Описание | Основные параметры |
+| --- | --- | --- |
+| `users_list` | Список всех пользователей YouTrack. **Использование:** Просмотр доступных пользователей, поиск логинов для назначения задач. **Возвращает:** предопределенные поля - id, login, name, fullName, email | — |
+| `user_get` | Получение пользователя по логину. **Использование:** Проверка существования пользователя, получение деталей профиля. **Возвращает:** предопределенные поля - id, login, name, fullName, email | `login` — логин пользователя |
+| `user_current` | Получение текущего аутентифицированного пользователя. **Использование:** Проверка, под каким пользователем работает API токен, получение собственного ID для операций. **Возвращает:** предопределенные поля - id, login, name, fullName, email | — |
+| `projects_list` | Список всех проектов YouTrack. **Использование:** Просмотр доступных проектов, поиск ID проекта для создания задач. **Возвращает:** предопределенные поля - id, shortName, name | — |
+| `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` — фильтр по проекту |
+| `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 содержимого |
+
+### Вложения
+
+| Tool | Описание | Основные параметры |
+| --- | --- | --- |
+| `issue_attachments_list` | Получение списка вложений задачи. **Использование:** Просмотр всех файлов, прикрепленных к задаче. **Возвращает:** метаданные всех вложений задачи | `issueId` — код задачи (например, `PROJ-123`) |
+| `issue_attachment_get` | Получение детальной информации о конкретном вложении. **Использование:** Проверка метаданных файла (размер, имя, тип, автор, дата). **Возвращает:** подробные метаданные вложения | `issueId` — код задачи, `attachmentId` — ID вложения |
+| `issue_attachment_download` | Получение информации для скачивания вложения. **Использование:** Получение подписанного URL для загрузки файла. **Возвращает:** метаданные вложения и подписанный URL, который можно использовать напрямую без дополнительной аутентификации | `issueId` — код задачи, `attachmentId` — ID вложения |
+| `issue_attachment_upload` | Загрузка файлов к задаче YouTrack. **Использование:** Прикрепление документов, скриншотов, логов к задаче. Файлы должны существовать в локальной файловой системе. **Примечание:** можно прикреплять файлы только к существующим задачам, не при создании. **Ограничение:** максимум 10 файлов за запрос | `issueId` — код задачи, `filePaths[]` — массив абсолютных путей к файлам (макс 10), опционально `muteUpdateNotifications` — не отправлять уведомления об обновлении |
+| `issue_attachment_delete` | Удаление вложения из задачи YouTrack. **ВАЖНО:** Требует явного подтверждения через параметр `confirmation` для предотвращения случайного удаления. **Использование:** Удаление устаревших или ошибочно загруженных файлов. Это деструктивная операция, которую нельзя отменить. | `issueId` — код задачи, `attachmentId` — ID вложения для удаления, `confirmation` — должен быть явно установлен в `true` для подтверждения удаления (обязательный параметр безопасности) |

package/README.md

@@ -0,0 +1,290 @@
+# 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)
+[![npm version](https://img.shields.io/npm/v/@vitalyostanin/youtrack-mcp.svg)](https://www.npmjs.com/package/@vitalyostanin/youtrack-mcp)
+
+MCP server for comprehensive YouTrack integration. Manage issues, track work items with detailed reports, search by user activity, work with knowledge base articles, and access projects and users. Supports time tracking with holiday/pre-holiday configuration, batch operations, and structured responses for AI clients.
+
+## Table of Contents
+
+- [YouTrack MCP Server](#youtrack-mcp-server)
+  - [Table of Contents](#table-of-contents)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+  - [Development & Release](#development--release)
+  - [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)
+  - [MCP Tools](#mcp-tools)
+    - [Service](#service)
+    - [Issues](#issues)
+    - [Work Items](#work-items)
+    - [Users and Projects](#users-and-projects)
+    - [Articles](#articles)
+    - [Search](#search)
+  - [Important Notes](#important-notes)
+
+## Requirements
+
+- Node.js ≥ 20
+- Environment variables:
+  - `YOUTRACK_URL` — base URL of YouTrack instance
+  - `YOUTRACK_TOKEN` — permanent token with read permissions for issues and work items
+  - `YOUTRACK_TIMEZONE` — optional timezone for date operations (default: `Europe/Moscow`), must be a valid IANA timezone identifier (e.g., `Europe/London`, `America/New_York`, `Asia/Tokyo`)
+  - `YOUTRACK_HOLIDAYS` — optional comma-separated list of holiday dates (format `YYYY-MM-DD`), excluded from reports and batch operations
+  - `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
+
+## Installation
+
+### Using npx (Recommended)
+
+You can run the server directly with npx without installation:
+
+```bash
+YOUTRACK_URL="https://youtrack.example.com" \
+YOUTRACK_TOKEN="perm:your-token-here" \
+npx -y @vitalyostanin/youtrack-mcp
+```
+
+### Using Claude MCP CLI
+
+Install using Claude MCP CLI:
+
+```bash
+claude mcp add --scope user youtrack-mcp npx -y @vitalyostanin/youtrack-mcp
+```
+
+After running this command, you'll be prompted to enter your YouTrack URL and token.
+
+**Scope Options:**
+- `--scope user`: Install for current user (all projects)
+- `--scope project`: Install for current project only
+
+**Removal:**
+
+```bash
+claude mcp remove youtrack-mcp --scope user
+```
+
+### Manual Installation (Development)
+
+```bash
+npm install
+npm run build
+```
+
+## Development & Release
+
+### GitHub Actions Workflows
+
+This project uses GitHub Actions for continuous integration and automated releases:
+
+#### CI Workflow (`.github/workflows/ci.yml`)
+
+Runs automatically on every push and pull request:
+- **Triggers**: All branches, all pull requests
+- **Node.js versions**: 20.x, 22.x (matrix testing)
+- **Steps**:
+  1. Install dependencies (`npm ci`)
+  2. Run linter (`npm run lint`)
+  3. Build project (`npm run build`)
+  4. Verify build artifacts (executable check)
+
+#### Publish Workflow (`.github/workflows/publish.yml`)
+
+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
+- **Steps**:
+  1. Install dependencies
+  2. Build project
+  3. Publish to npm registry
+  4. Create GitHub Release
+
+### Setting up NPM_TOKEN
+
+To enable automatic publishing to npm, you need to configure the `NPM_TOKEN` secret:
+
+1. **Generate npm Access Token**:
+   - Go to [npmjs.com](https://www.npmjs.com/) and log in
+   - Navigate to **Access Tokens** in your account settings
+   - Click **Generate New Token** → **Classic Token**
+   - Select **Automation** type (for CI/CD)
+   - Copy the generated token
+
+2. **Add Secret to GitHub**:
+   - Go to your GitHub repository
+   - Navigate to **Settings** → **Secrets and variables** → **Actions**
+   - Click **New repository secret**
+   - Name: `NPM_TOKEN`
+   - Value: Paste your npm token
+   - Click **Add secret**
+
+### Release Process
+
+To create a new release:
+
+```bash
+# 1. Update version in package.json and create git tag
+npm version patch   # for 0.1.0 → 0.1.1
+# or
+npm version minor   # for 0.1.0 → 0.2.0
+# or
+npm version major   # for 0.1.0 → 1.0.0
+
+# 2. Push the tag to GitHub
+git push --follow-tags
+
+# 3. GitHub Actions will automatically:
+#    - Run tests and build
+#    - Publish to npm
+#    - Create GitHub Release
+```
+
+**Note**: The `npm version` command automatically:
+- Updates `package.json` and `package-lock.json`
+- Creates a git commit with message like "0.1.1"
+- Creates a git tag like "v0.1.1"
+
+### Manual Build & Test
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run linter
+npm run lint
+
+# Watch mode for development
+npm run dev:watch
+```
+
+## Running the server (stdio)
+
+```bash
+YOUTRACK_URL="https://youtrack.example.com" \
+YOUTRACK_TOKEN="perm:example-token" \
+node dist/index.js
+```
+
+## Configuration for Code (Recommended)
+
+To use this MCP server with [Code](https://github.com/just-every/code), add the following configuration to your `~/.code/config.toml`:
+
+```toml
+[mcp_servers.youtrack-mcp]
+command = "npx"
+args = ["-y", "@vitalyostanin/youtrack-mcp"]
+env = { "YOUTRACK_URL" = "https://youtrack.example.com", "YOUTRACK_TOKEN" = "perm:your-token-here" }
+```
+
+**Note:** This configuration uses npx to run the published package. Alternatively, for local development, use `command = "node"` with `args = ["/path/to/dist/index.js"]`.
+
+## Configuration for Claude Code CLI
+
+To use this MCP server with [Claude Code CLI](https://github.com/anthropics/claude-code), you can:
+
+1. **Use Claude MCP CLI** - see [Installation](#installation) section above
+2. **Manual configuration** - add to your `~/.claude.json` file:
+
+```json
+{
+  "mcpServers": {
+    "youtrack-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@vitalyostanin/youtrack-mcp"],
+      "env": {
+        "YOUTRACK_URL": "https://youtrack.example.com",
+        "YOUTRACK_TOKEN": "perm:your-token-here"
+      }
+    }
+  }
+}
+```
+
+**Note:** This configuration uses npx to run the published package. For local development, use `"command": "node"` with `"args": ["/absolute/path/to/youtrack-mcp/dist/index.js"]`. The `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HOLIDAYS`, and `YOUTRACK_USER_ALIASES` environment variables are optional.
+
+## MCP Tools
+
+All tools return `structuredContent` with a `success` flag and payload formatted for MCP clients.
+
+### Service
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `service_info` | Check YouTrack availability and current user | — |
+
+### Issues
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `issue_lookup` | Brief issue information | `issueId` — issue code (e.g., PROJ-123) |
+| `issue_details` | Full issue data | `issueId` — issue code |
+| `issue_comments` | Issue comments | `issueId` — issue code |
+| `issue_create` | Create issue | `projectId`, `summary`, optionally `description`, `parentIssueId`, `assigneeLogin`, `usesMarkdown` |
+| `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_search_by_user_activity` | Search issues with user activity | `userLogins[]` — array of user logins, optionally `startDate`, `endDate`, `dateFilterMode` (`issue_updated` fast mode or `user_activity` precise mode), `limit` (default 100, max 200). Finds issues where users updated, mentioned, reported, assigned, or commented. Fast mode filters by issue.updated field; precise mode checks actual user activity dates including comments, mentions, and field changes history (e.g., when user was assignee but later changed). In precise mode, returns `lastActivityDate` field. Sorted by activity time (newest first) |
+| `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_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`) |
+
+### Work Items
+
+| 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) |
+| `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` |
+
+### Users and Projects
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `users_list` | List all YouTrack users | — |
+| `user_get` | Get user by login | `login` — user login |
+| `user_current` | Get current authenticated user | — |
+| `projects_list` | List all YouTrack projects | — |
+| `project_get` | Get project by short name | `shortName` — project short name |
+
+### Articles
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `article_get` | Get article by ID | `articleId` |
+| `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` |
+
+### Search
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `article_search` | Search articles in knowledge base | `query`, optionally `projectId`, `parentArticleId`, `limit`, `returnRendered` |
+
+## Important Notes
+
+### Destructive Operations
+
+Some operations cannot be undone and require explicit confirmation:
+
+- **`issue_attachment_delete`** - Requires `confirmation: true` parameter. Deleted attachments cannot be recovered.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { YoutrackServer } from "./src/server.js";
+async function main() {
+    const transport = new StdioServerTransport();
+    const server = new YoutrackServer();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("YouTrack MCP server crashed", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/src/config.d.ts

@@ -0,0 +1,10 @@
+import type { YoutrackConfig } from "./types.js";
+export declare function loadConfig(env?: NodeJS.ProcessEnv): YoutrackConfig;
+export declare function enrichConfigWithRedaction(config: YoutrackConfig): {
+    baseUrl: string;
+    hasToken: boolean;
+    timezone: string;
+    holidays: string[] | undefined;
+    preHolidays: string[] | undefined;
+};
+//# sourceMappingURL=config.d.ts.map