@vitalyostanin/youtrack-mcp 0.7.4 → 0.9.0

package/README-ru.md

@@ -15,6 +15,7 @@ MCP сервер для полноценной интеграции с YouTrack
 - **База знаний** - создание, обновление, поиск статей с иерархической структурой
 - **Доступ к пользователям и проектам** - получение информации о пользователях и проектах
 - **Пакетные операции** - эффективная обработка до 50 задач одновременно
+- **Сохранение в файлы** - сохранение больших результатов инструментов в JSON файлы вместо прямого возврата
 - **Дополнительные возможности** - поддержка Markdown, сворачиваемые секции, конфигурация праздников, алиасы пользователей
 
 ## Содержание
@@ -38,6 +39,7 @@ MCP сервер для полноценной интеграции с YouTrack
   - [Конфигурация для Claude Code CLI](#конфигурация-для-claude-code-cli)
   - [Конфигурация для VS Code Cline](#конфигурация-для-vs-code-cline)
   - [Инструменты MCP](#инструменты-mcp)
+    - [Параметры сохранения файлов](#параметры-сохранения-файлов)
     - [Сервис](#сервис)
     - [Задачи](#задачи)
     - [Связи задач](#связи-задач)
@@ -45,6 +47,7 @@ MCP сервер для полноценной интеграции с YouTrack
     - [Трудозатраты](#трудозатраты)
     - [Пользователи и проекты](#пользователи-и-проекты)
     - [Статьи](#статьи)
+    - [Лента активности](#лента-активности)
     - [Вложения](#вложения)
 
 ## Требования
@@ -271,6 +274,15 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 Инструменты возвращают либо `structuredContent` (по умолчанию), либо текстовый элемент `content` — в зависимости от `YOUTRACK_USE_STRUCTURED_CONTENT`.
 
+### Параметры сохранения файлов
+
+Многие инструменты поддерживают опциональные параметры `saveToFile` и `filePath` для работы с большими датасетами:
+
+- `saveToFile` — boolean, сохраняет результаты в JSON файл вместо возврата напрямую (полезно для больших датасетов)
+- `filePath` — string, пользовательский путь к файлу (опционально, генерируется автоматически если не указан, директория создается при необходимости)
+
+Когда `saveToFile` установлено в `true`, инструменты возвращают метаданные о сохраненном файле вместо полных данных.
+
 ### Сервис
 
 | Tool | Описание | Основные параметры |
@@ -294,7 +306,6 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | `issue_comment_update` | Обновление существующего комментария. **Использование:** Редактирование текста комментария, изменение режима форматирования, исправление опечаток. Поддерживает Markdown. **Возвращает:** поля комментария - id, text, textPreview, usesMarkdown, author, created, updated, commentUrl | `issueId` — ID или код задачи, `commentId` — ID комментария, опционально `text`, `usesMarkdown`, `muteUpdateNotifications` |
 | `issue_activities` | Получение истории изменений задачи (активности). **Использование:** Просмотр полной истории задачи, отслеживание изменений полей во времени, мониторинг кто и когда что изменил, анализ эволюции задачи, аудит модификаций. **Возвращает:** Элементы активности с временными метками (ISO datetime), авторами, категориями, типами изменений и деталями изменений (добавленные/удалённые значения). Поддерживает фильтрацию по автору, диапазону дат и категориям активности. **Примечание:** Возвращает предопределённые поля - id, timestamp, author (id, login, name), category (id), target (text), добавленные значения, удалённые значения, тип активности. Полезно для понимания жизненного цикла задачи, отслеживания модификаций полей, просмотра истории комментариев и анализа паттернов совместной работы. | `issueId` — код задачи, опционально `author` (логин пользователя), `startDate` (формат YYYY-MM-DD, timestamp или Date), `endDate`, `categories` (через запятую: `CustomFieldCategory` для изменений полей, `CommentsCategory` для комментариев, `AttachmentsCategory` для вложений, `LinksCategory` для связей, `VcsChangeActivityCategory` для VCS изменений, `WorkItemsActivityCategory` для трудозатрат), `limit` (макс 200), `skip` для пагинации |
 | `issue_change_state` | Изменение состояния/статуса задачи через переходы workflow. **Использование:** Перемещение задач через состояния рабочего процесса (например, 'Открыта' → 'В работе'). Автоматически определяет доступные переходы и валидирует запрошенное изменение состояния. Регистронезависимое сопоставление имён состояний. **Возвращает:** информацию о предыдущем состоянии, новом состоянии и использованном переходе | `issueId` — код задачи, `stateName` — имя целевого состояния (например, 'В работе', 'Открыта', 'Исправлена', 'Проверена'). Регистронезависимое |
-| `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` для пагинации |
 
 ### Связи задач
 
@@ -367,6 +378,12 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | `issues_list` | Список задач по фильтрам с поддержкой сортировки. **Использование:** Дашборды, аудит командной загрузки, подготовка батч-операций. Поддерживает фильтрацию по проектам, датам создания/обновления, статусам, типам, исполнителю. **Возвращает:** краткие или полные данные задачи в зависимости от `briefOutput`, а также информацию о сортировке и пагинации. | Фильтры: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; сортировка: `sortField` (`created`/`updated`), `sortDirection` (`asc`/`desc`); пагинация: `limit`, `skip`; формат: `briefOutput` |
 | `issues_count` | Подсчёт задач с теми же фильтрами, что у `issues_list`, с разбивкой по проектам. **Использование:** Быстрая оценка объёмов работ перед загрузкой полного списка, подготовка аналитических отчётов. При запросе одного проекта обращается к `/api/issuesGetter/count`, иначе считает постранично. | Те же фильтры, что и `issues_list`; опциональный `top` ограничивает объём ручной агрегации (при необходимости частичной выборки) |
 
+### Лента активности
+
+| 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` (расширенный перегруз возвращаемых полей). |
+
 ### Вложения
 
 | Tool | Описание | Основные параметры |

package/README.md

@@ -17,6 +17,7 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
 - **Knowledge base** - create, update, search articles with hierarchical structure
 - **User and project access** - retrieve information about users and projects
 - **Batch operations** - efficient processing of up to 50 issues simultaneously
+- **File storage** - save large tool results to JSON files instead of returning directly
 - **Additional features** - Markdown support, folded sections, holiday configuration, user aliases
 
 ## Table of Contents
@@ -40,6 +41,7 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
   - [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)
     - [Service](#service)
     - [Issues](#issues)
     - [Issue Links](#issue-links)
@@ -48,6 +50,7 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
     - [Users and Projects](#users-and-projects)
     - [Articles](#articles)
     - [Search](#search)
+    - [Activity Feed](#activity-feed)
   - [Important Notes](#important-notes)
     - [Destructive Operations](#destructive-operations)
 
@@ -275,6 +278,15 @@ To use this MCP server with [Cline](https://github.com/cline/cline) extension in
 
 Tools return either `structuredContent` (default) or a text `content` item, depending on `YOUTRACK_USE_STRUCTURED_CONTENT`.
 
+### File Storage Parameters
+
+Many tools support optional `saveToFile` and `filePath` 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)
+
+When `saveToFile` is `true`, tools return metadata about the saved file instead of the full data.
+
 ### Service
 
 | Tool | Description | Main Parameters |
@@ -298,7 +310,6 @@ Tools return either `structuredContent` (default) or a text `content` item, depe
 | `issue_comment_update` | Update existing comment | `issueId`, `commentId`, optionally `text`, `usesMarkdown`, `muteUpdateNotifications` |
 | `issue_activities` | Get issue change history | `issueId` — issue code, optionally `author` (login), `startDate` (YYYY-MM-DD, timestamp, or Date), `endDate`, `categories` (comma-separated: `CustomFieldCategory` for field changes, `CommentsCategory` for comments, `AttachmentsCategory` for attachments, `LinksCategory` for links, `VcsChangeActivityCategory` for VCS changes, `WorkItemsActivityCategory` for work items), `limit` (max 200), `skip` for pagination. Returns activity items with timestamps (ISO datetime), authors, categories, and change details (added/removed values). Useful for tracking field modifications, reviewing comment history, and analyzing collaboration patterns |
 | `issue_change_state` | Change issue state/status through workflow transitions | `issueId` — issue code, `stateName` — target state name (e.g., 'In Progress', 'Open', 'Fixed', 'Verified'). Case-insensitive. Automatically discovers available transitions and validates requested state change. Returns information about previous state, new state, and transition used. Use for moving issues through workflow states |
-| `issue_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 |
@@ -370,6 +381,12 @@ Tools return either `structuredContent` (default) or a text `content` item, depe
 | --- | --- | --- |
 | `articles_search` | Full-text search across YouTrack knowledge base articles by title and content. Returns `webUrl` for direct access | `query` (min 2 chars), `limit` (default 50, max 200), `skip`, optionally `projectId`, `parentArticleId` |
 | `issues_search` | Full-text search across YouTrack issues by summary, description, and comments. If `query` is not provided or empty, all issues will be returned. Supports filtering by projects, assignee, reporter, state, and type | `query` (optional), `limit` (default 50, max 200), `skip`, `countOnly` (optional), `projects` (optional), `assignee` (optional), `reporter` (optional), `state` (optional), `type` (optional) |
+
+### Activity Feed
+
+| Tool | Description | Main Parameters |
+| --- | --- | --- |
+| `users_activity` | Author-centric activity feed backed by `/api/activities`. **Use for:** auditing a teammate's updates, gathering comment/state changes across many issues, and reviewing deployment timelines. Returns normalized entries with ISO timestamps, optional issue references, and `added`/`removed` payloads. Always follow up by re-fetching the affected issue or work-item to confirm the latest state. Supported categories: `CustomFieldCategory` (field changes), `CommentsCategory` (comments), `AttachmentsCategory` (file events), `LinksCategory` (issue links), `VcsChangeActivityCategory` (VCS changes), `WorkItemsActivityCategory` (work items). | `author` *(required)* — login such as `vyt`; `categories` *(required)* — comma-separated list built from the supported categories above; optional `start` / `end` (ISO string, timestamp in ms, or `Date`) to bound the range, `reverse` (boolean) to switch to chronological order, `limit` (default 100, max 200), `skip` (pagination offset), `fields` (advanced override of response fields). |
 | `issues_list` | List issues across projects with filtering and sorting | Filters: `projectIds`, `createdAfter/Before`, `updatedAfter/Before`, `statuses`, `assigneeLogin`, `types`; Sorting: `sortField`, `sortDirection`; Pagination: `limit`, `skip`; Output mode: `briefOutput` |
 | `issues_count` | Count issues using same filters as `issues_list`, returns per-project breakdown | Same filters as above, optional `top` to cap manual aggregation when many projects are involved |
 

package/dist/package.json

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

package/dist/src/server.js

@@ -12,6 +12,7 @@ import { registerProjectTools } from "./tools/project-tools.js";
 import { registerAttachmentTools } from "./tools/attachment-tools.js";
 import { registerIssueStarTools } from "./tools/issue-star-tools.js";
 import { registerIssueLinkTools } from "./tools/issue-link-tools.js";
+import { usersActivityArgs, usersActivityHandler } from "./tools/users-activity-tools.js";
 import { YoutrackClient } from "./youtrack-client.js";
 import { loadConfig } from "./config.js";
 import { initializeTimezone } from "./utils/date.js";
@@ -46,6 +47,7 @@ export class YoutrackServer {
         registerArticleTools(this.server, this.client);
         // Removed redundant registerArticleSearchTools call (articles_search tool registered manually above)
         registerUserTools(this.server, this.client);
+        this.server.tool("users_activity", "Author-centric activity feed backed by /api/activities. Use for: auditing a teammate's updates, gathering comment/state changes across many issues, and reviewing deployment timelines. Always re-fetch affected entities to confirm final state.", usersActivityArgs, async (args) => usersActivityHandler(this.client, args));
         registerProjectTools(this.server, this.client);
         registerAttachmentTools(this.server, this.client);
         registerIssueStarTools(this.server, this.client);

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

@@ -6,6 +6,8 @@ export declare const articlesSearchArgs: {
     skip: z.ZodDefault<z.ZodNumber>;
     projectId: z.ZodOptional<z.ZodString>;
     parentArticleId: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
 };
 export declare const articlesSearchSchema: z.ZodObject<{
     query: z.ZodString;
@@ -13,16 +15,22 @@ export declare const articlesSearchSchema: z.ZodObject<{
     skip: z.ZodDefault<z.ZodNumber>;
     projectId: z.ZodOptional<z.ZodString>;
     parentArticleId: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     query: string;
     skip: number;
     limit: number;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
     projectId?: string | undefined;
     parentArticleId?: string | undefined;
 }, {
     query: string;
     skip?: number | undefined;
     limit?: number | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
     projectId?: string | undefined;
     parentArticleId?: string | undefined;
 }>;

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

@@ -1,11 +1,14 @@
 import { z } from "zod";
 import { toolSuccess, toolError } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 export const articlesSearchArgs = {
     query: z.string().min(2).describe("Search string for articles (e.g., 'API token')"),
     limit: z.number().int().positive().max(200).default(50).describe("Max results per page"),
     skip: z.number().int().nonnegative().default(0).describe("Offset for pagination"),
     projectId: z.string().optional().describe("Filter by project ID"),
     parentArticleId: z.string().optional().describe("Filter by parent article ID"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 export const articlesSearchSchema = z.object(articlesSearchArgs);
 export async function articlesSearchHandler(client, rawInput) {
@@ -31,6 +34,14 @@ export async function articlesSearchHandler(client, rawInput) {
                 webUrl: `${baseUrl}/articles/${article.idReadable}`,
             }))
             : data;
+        const processedResult = processWithFileStorage(articlesWithLinks, input.saveToFile, input.filePath);
+        if (processedResult.savedToFile) {
+            return toolSuccess({
+                savedToFile: true,
+                filePath: processedResult.filePath,
+                articleCount: Array.isArray(articlesWithLinks) ? articlesWithLinks.length : 0,
+            });
+        }
         return toolSuccess(articlesWithLinks);
     }
     catch (error) {

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

@@ -1,7 +1,10 @@
 import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 const issueIdArgs = {
     issueId: z.string().min(1).describe("Issue code (e.g., PROJ-123)"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const issueIdSchema = z.object(issueIdArgs);
 const attachmentGetArgs = {
@@ -32,8 +35,15 @@ export function registerAttachmentTools(server, client) {
         try {
             const payload = issueIdSchema.parse(rawInput);
             const result = await client.listAttachments(payload.issueId);
-            const response = toolSuccess(result);
-            return response;
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    attachmentsCount: result.attachments.length,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
 import { mapActivityItems } from "../utils/mappers.js";
 import { toIsoDateString } from "../utils/date.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 // Zod args definition
 const issueActivitiesArgs = {
     issueId: z.string().min(1).describe("Issue code (e.g., PROJ-123)"),
@@ -26,6 +27,8 @@ const issueActivitiesArgs = {
         .optional()
         .describe("Maximum number of activities to return (default: no limit, max: 200)"),
     skip: z.number().int().min(0).optional().describe("Number of activities to skip for pagination (default: 0)"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const issueActivitiesSchema = z.object(issueActivitiesArgs);
 export function registerIssueActivityTools(server, client) {
@@ -68,6 +71,14 @@ export function registerIssueActivityTools(server, client) {
                     skip: input.skip ?? 0,
                 },
             };
+            const processedResult = processWithFileStorage(payload, input.saveToFile, input.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    activityCount: paginatedActivities.length,
+                });
+            }
             return toolSuccess(payload);
         }
         catch (error) {

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

@@ -9,6 +9,8 @@ export declare const issuesSearchArgs: {
     reporter: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
 };
 export declare const issuesSearchSchema: z.ZodDefault<z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
@@ -19,6 +21,8 @@ export declare const issuesSearchSchema: z.ZodDefault<z.ZodObject<{
     reporter: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     skip: number;
     limit: number;
@@ -27,6 +31,8 @@ export declare const issuesSearchSchema: z.ZodDefault<z.ZodObject<{
     type?: string | undefined;
     query?: string | undefined;
     projects?: string[] | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
     state?: string | undefined;
 }, {
     reporter?: string | undefined;
@@ -36,6 +42,8 @@ export declare const issuesSearchSchema: z.ZodDefault<z.ZodObject<{
     skip?: number | undefined;
     projects?: string[] | undefined;
     limit?: number | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
     state?: string | undefined;
 }>>;
 export declare function issuesSearchHandler(client: YoutrackClient, rawInput: unknown): Promise<{

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { toolSuccess, toolError } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 export const issuesSearchArgs = {
     query: z
         .string()
@@ -12,6 +13,8 @@ export const issuesSearchArgs = {
     reporter: z.string().optional().describe("Filter by reporter/author login (e.g., 'john.doe' or 'me')"),
     state: z.string().optional().describe("Filter by state/status (e.g., 'Open', 'In Progress', 'Fixed')"),
     type: z.string().optional().describe("Filter by issue type (e.g., 'Bug', 'Feature', 'Task')"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 export const issuesSearchSchema = z
     .object({
@@ -26,6 +29,8 @@ export const issuesSearchSchema = z
     reporter: z.string().optional().describe("Filter by reporter/author login (e.g., 'john.doe' or 'me')"),
     state: z.string().optional().describe("Filter by state/status (e.g., 'Open', 'In Progress', 'Fixed')"),
     type: z.string().optional().describe("Filter by issue type (e.g., 'Bug', 'Feature', 'Task')"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 })
     .default({});
 export async function issuesSearchHandler(client, rawInput) {
@@ -82,6 +87,16 @@ export async function issuesSearchHandler(client, rawInput) {
             byProject: Object.entries(byProject).map(([project, count]) => ({ project, count })),
             items: allIssues,
         };
+        const processedResult = processWithFileStorage(result, input.saveToFile, input.filePath);
+        if (processedResult.savedToFile) {
+            return toolSuccess({
+                savedToFile: true,
+                filePath: processedResult.filePath,
+                total,
+                byProject: Object.entries(byProject).map(([project, count]) => ({ project, count })),
+                itemCount: allIssues.length,
+            });
+        }
         return toolSuccess(result);
     }
     catch (error) {

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

@@ -1,11 +1,14 @@
 import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 const issueIdArgs = {
     issueId: z.string().min(1).describe("Issue code (e.g., PROJ-123)"),
     briefOutput: z
         .boolean()
         .optional()
         .describe("Brief mode (default: true). When false, include all available customFields including State."),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const issueIdSchema = z.object(issueIdArgs);
 const issueIdsArgs = {
@@ -18,6 +21,8 @@ const issueIdsArgs = {
         .boolean()
         .optional()
         .describe("Brief mode (default: true). When false, include all available customFields for each issue."),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const issueIdsSchema = z.object(issueIdsArgs);
 const issueCreateArgs = {
@@ -134,8 +139,15 @@ export function registerIssueTools(server, client) {
         try {
             const payload = issueIdSchema.parse(rawInput);
             const comments = await client.getIssueComments(payload.issueId);
-            const response = toolSuccess(comments);
-            return response;
+            const processedResult = processWithFileStorage(comments, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    commentCount: comments.comments.length,
+                });
+            }
+            return toolSuccess(comments);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -242,8 +254,16 @@ export function registerIssueTools(server, client) {
         try {
             const payload = issueIdsSchema.parse(rawInput);
             const result = await client.getIssues(payload.issueIds);
-            const response = toolSuccess(result);
-            return response;
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    issueCount: result.issues.length,
+                    errorsCount: result.errors?.length ?? 0,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -255,8 +275,16 @@ export function registerIssueTools(server, client) {
             const payload = issueIdsSchema.parse(rawInput);
             const brief = payload.briefOutput ?? true;
             const result = await client.getIssuesDetails(payload.issueIds, !brief);
-            const response = toolSuccess(result);
-            return response;
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    issueCount: result.issues.length,
+                    errorsCount: result.errors?.length ?? 0,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -267,8 +295,15 @@ export function registerIssueTools(server, client) {
         try {
             const payload = issueIdsSchema.parse(rawInput);
             const result = await client.getMultipleIssuesComments(payload.issueIds);
-            const response = toolSuccess(result);
-            return response;
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    totalComments: Object.values(result.commentsByIssue).flat().length,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);

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

@@ -1,15 +1,27 @@
 import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 const userLookupArgs = {
     login: z.string().min(1).describe("User login"),
 };
 const userLookupSchema = z.object(userLookupArgs);
 export function registerUserTools(server, client) {
-    server.tool("users_list", "List all YouTrack users. Note: Returns predefined fields only - id, login, name, fullName, email.", {}, async () => {
+    server.tool("users_list", "List all YouTrack users. Note: Returns predefined fields only - id, login, name, fullName, email.", {
+        saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+        filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+    }, async (rawInput) => {
         try {
+            const payload = rawInput;
             const users = await client.listUsers();
-            const response = toolSuccess(users);
-            return response;
+            const processedResult = processWithFileStorage(users, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    usersCount: users.users.length,
+                });
+            }
+            return toolSuccess(users);
         }
         catch (error) {
             const errorResponse = toolError(error);

package/dist/src/tools/users-activity-tools.d.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import type { YoutrackClient } from "../youtrack-client.js";
+export declare const usersActivityArgs: {
+    author: z.ZodString;
+    start: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodDate]>>;
+    end: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodDate]>>;
+    categories: z.ZodString;
+    reverse: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    skip: z.ZodDefault<z.ZodNumber>;
+    fields: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
+};
+export declare const usersActivitySchema: z.ZodObject<{
+    author: z.ZodString;
+    start: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodDate]>>;
+    end: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodDate]>>;
+    categories: z.ZodString;
+    reverse: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    skip: z.ZodDefault<z.ZodNumber>;
+    fields: z.ZodOptional<z.ZodString>;
+    saveToFile: z.ZodOptional<z.ZodBoolean>;
+    filePath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    author: string;
+    skip: number;
+    categories: string;
+    limit: number;
+    reverse?: boolean | undefined;
+    fields?: string | undefined;
+    start?: string | number | Date | undefined;
+    end?: string | number | Date | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
+}, {
+    author: string;
+    categories: string;
+    reverse?: boolean | undefined;
+    skip?: number | undefined;
+    fields?: string | undefined;
+    start?: string | number | Date | undefined;
+    end?: string | number | Date | undefined;
+    limit?: number | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
+}>;
+export declare function usersActivityHandler(client: YoutrackClient, rawInput: unknown): Promise<{
+    [x: string]: unknown;
+    content: ({
+        [x: string]: unknown;
+        text: string;
+        type: "text";
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "image";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "audio";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        [x: string]: unknown;
+        name: string;
+        type: "resource_link";
+        uri: string;
+        description?: string | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        mimeType?: string | undefined;
+        title?: string | undefined;
+        icons?: {
+            [x: string]: unknown;
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+        }[] | undefined;
+    } | {
+        [x: string]: unknown;
+        type: "resource";
+        resource: {
+            [x: string]: unknown;
+            text: string;
+            uri: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        } | {
+            [x: string]: unknown;
+            uri: string;
+            blob: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined;
+        };
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+}>;
+//# sourceMappingURL=users-activity-tools.d.ts.map

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

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { parseDateInput, toIsoDateString, unixMsToDate, getCurrentDate } from "../utils/date.js";
+import { mapActivityItems } from "../utils/mappers.js";
+import { toolSuccess, toolError } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
+export const usersActivityArgs = {
+    author: z
+        .string()
+        .min(1)
+        .describe("Filter by author login (required, e.g., 'vyt'). Matches activities created by this user."),
+    start: z
+        .union([z.string(), z.number(), z.date()])
+        .optional()
+        .describe("Inclusive start of the interval. Accepts ISO string, unix timestamp (ms), or Date object. Converted to unix ms for /api/activities (default: no lower bound)."),
+    end: z
+        .union([z.string(), z.number(), z.date()])
+        .optional()
+        .describe("Inclusive end of the interval. Accepts ISO string, unix timestamp (ms), or Date object. Converted to unix ms for /api/activities (default: now)."),
+    categories: z
+        .string()
+        .describe("Comma-separated list of activity categories. Supported values: 'CustomFieldCategory', 'CommentsCategory', 'AttachmentsCategory', 'LinksCategory', 'VcsChangeActivityCategory', 'WorkItemsActivityCategory'."),
+    reverse: z
+        .boolean()
+        .optional()
+        .describe("When true, return activities in ascending order (oldest first). Default is false (newest first)."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .default(100)
+        .describe("Maximum number of activities to return (default 100, max 200)."),
+    skip: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Number of activities to skip for pagination (default 0)."),
+    fields: z
+        .string()
+        .optional()
+        .describe("Override fields parameter passed to /api/activities (advanced). Defaults to issue idReadable, author, added/removed, category, timestamps."),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
+};
+export const usersActivitySchema = z.object(usersActivityArgs);
+export async function usersActivityHandler(client, rawInput) {
+    try {
+        const input = usersActivitySchema.parse(rawInput);
+        const startMs = parseDateInput(input.start ?? unixMsToDate(0));
+        const endMs = parseDateInput(input.end ?? getCurrentDate());
+        if (startMs > endMs) {
+            throw new Error("'start' must be earlier than or equal to 'end'.");
+        }
+        const activities = await client.listActivities({
+            author: input.author,
+            categories: input.categories,
+            start: startMs,
+            end: endMs,
+            limit: input.limit,
+            skip: input.skip,
+            fields: input.fields,
+            reverse: input.reverse,
+        });
+        const mappedActivities = mapActivityItems(activities);
+        const payload = {
+            activities: mappedActivities,
+            filters: {
+                author: input.author,
+                start: toIsoDateString(input.start ?? unixMsToDate(startMs)),
+                end: toIsoDateString(input.end ?? unixMsToDate(endMs)),
+                categories: input.categories,
+                reverse: input.reverse,
+            },
+            pagination: {
+                returned: mappedActivities.length,
+                limit: input.limit,
+                skip: input.skip,
+            },
+        };
+        const processedResult = processWithFileStorage(payload, input.saveToFile, input.filePath);
+        if (processedResult.savedToFile) {
+            return toolSuccess({
+                savedToFile: true,
+                filePath: processedResult.filePath,
+                activityCount: mappedActivities.length,
+                filters: payload.filters,
+                pagination: payload.pagination,
+            });
+        }
+        return toolSuccess(payload);
+    }
+    catch (error) {
+        return toolError(error);
+    }
+}
+//# sourceMappingURL=users-activity-tools.js.map

package/dist/src/tools/workitem-report-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 const sharedDate = z.union([z.string().regex(/\d{4}-\d{2}-\d{2}/), z.number(), z.date()]);
 const reportBaseArgs = {
     author: z.string().optional().describe("Work item author login"),
@@ -12,6 +13,8 @@ const reportBaseArgs = {
     holidays: z.array(sharedDate).optional().describe("List of holiday dates"),
     preHolidays: z.array(sharedDate).optional().describe("List of pre-holiday dates"),
     allUsers: z.boolean().optional().describe("Include work items for all users"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const reportArgsSchema = z.object(reportBaseArgs);
 const reportUsersArgsSchema = z.object({
@@ -23,8 +26,18 @@ export function registerWorkitemReportTools(server, client) {
         try {
             const payload = reportArgsSchema.parse(rawInput);
             const report = await client.generateWorkItemReport(payload);
-            const response = toolSuccess({ report });
-            return response;
+            const processedResult = processWithFileStorage({ report }, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    reportSummary: {
+                        totalMinutes: report.summary.totalMinutes,
+                        workDays: report.summary.workDays,
+                    },
+                });
+            }
+            return toolSuccess({ report });
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -35,8 +48,15 @@ export function registerWorkitemReportTools(server, client) {
         try {
             const payload = reportArgsSchema.parse(rawInput);
             const invalidDays = await client.generateInvalidWorkItemReport(payload);
-            const response = toolSuccess({ invalidDays });
-            return response;
+            const processedResult = processWithFileStorage({ invalidDays }, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    invalidDaysCount: invalidDays.length,
+                });
+            }
+            return toolSuccess({ invalidDays });
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -50,8 +70,15 @@ export function registerWorkitemReportTools(server, client) {
         try {
             const payload = reportUsersArgsSchema.parse(rawInput);
             const report = await client.generateUsersWorkItemReports(payload.users, payload);
-            const response = toolSuccess(report);
-            return response;
+            const processedResult = processWithFileStorage(report, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    usersCount: report.reports.length,
+                });
+            }
+            return toolSuccess(report);
         }
         catch (error) {
             const errorResponse = toolError(error);

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { mapWorkItem, mapWorkItems } from "../utils/mappers.js";
 import { toolError, toolSuccess } from "../utils/tool-response.js";
+import { processWithFileStorage } from "../utils/file-storage.js";
 const isoDate = z
     .string()
     .regex(/\d{4}-\d{2}-\d{2}/)
@@ -12,6 +13,8 @@ const baseFilterArgs = {
     startDate: dateInput.optional().describe("Period start date"),
     endDate: dateInput.optional().describe("Period end date"),
     allUsers: z.boolean().optional().describe("Get work items for all users"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const workItemsListSchema = z.object(baseFilterArgs);
 const workItemsForUsersArgs = {
@@ -93,6 +96,8 @@ const workItemsReportSchema = z.object(workItemsReportArgs);
 const workItemsRecentArgs = {
     users: z.array(z.string().min(1)).optional().describe("User logins (defaults to current user)"),
     limit: z.number().int().positive().max(200).optional().describe("Maximum number of items (default 50)"),
+    saveToFile: z.boolean().optional().describe("Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts."),
+    filePath: z.string().optional().describe("Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist."),
 };
 const workItemsRecentSchema = z.object(workItemsRecentArgs);
 export function registerWorkitemTools(server, client) {
@@ -100,8 +105,16 @@ export function registerWorkitemTools(server, client) {
         try {
             const payload = workItemsListSchema.parse(rawInput);
             const items = await client.listWorkItems(payload);
-            const response = toolSuccess({ items: mapWorkItems(items) });
-            return response;
+            const result = { items: mapWorkItems(items) };
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    itemCount: items.length,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -112,8 +125,16 @@ export function registerWorkitemTools(server, client) {
         try {
             const payload = workItemsListSchema.parse(rawInput);
             const items = await client.listAllUsersWorkItems(payload);
-            const response = toolSuccess({ items: mapWorkItems(items) });
-            return response;
+            const result = { items: mapWorkItems(items) };
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    itemCount: items.length,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -124,8 +145,17 @@ export function registerWorkitemTools(server, client) {
         try {
             const payload = workItemsUsersSchema.parse(rawInput);
             const items = await client.getWorkItemsForUsers(payload.users, payload);
-            const response = toolSuccess({ items: mapWorkItems(items), users: payload.users });
-            return response;
+            const result = { items: mapWorkItems(items), users: payload.users };
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    itemCount: items.length,
+                    users: payload.users,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);
@@ -247,8 +277,16 @@ export function registerWorkitemTools(server, client) {
         try {
             const payload = workItemsRecentSchema.parse(rawInput);
             const items = await client.listRecentWorkItems(payload);
-            const response = toolSuccess({ items: mapWorkItems(items), count: items.length });
-            return response;
+            const result = { items: mapWorkItems(items), count: items.length };
+            const processedResult = processWithFileStorage(result, payload.saveToFile, payload.filePath);
+            if (processedResult.savedToFile) {
+                return toolSuccess({
+                    savedToFile: true,
+                    filePath: processedResult.filePath,
+                    itemCount: items.length,
+                });
+            }
+            return toolSuccess(result);
         }
         catch (error) {
             const errorResponse = toolError(error);

package/dist/src/utils/date.d.ts

@@ -1,3 +1,4 @@
+import { DateTime } from "luxon";
 export declare function initializeTimezone(timezone: string): void;
 export declare function getTimezone(): string;
 export declare function parseDateInput(value: string | number | Date): number;
@@ -31,4 +32,5 @@ export declare function filterWorkingDates(dates: Date[], excludeWeekends?: bool
 export declare function isSameDay(left: string | number | Date, right: string | number | Date): boolean;
 export declare function getCurrentTimestamp(): number;
 export declare function getCurrentDate(timezone?: string): Date;
+export declare function getCurrentDateTime(timezone?: string): DateTime;
 //# sourceMappingURL=date.d.ts.map

package/dist/src/utils/date.js

@@ -144,4 +144,7 @@ export function getCurrentTimestamp() {
 export function getCurrentDate(timezone = currentTimezone) {
     return DateTime.now().setZone(timezone).toJSDate();
 }
+export function getCurrentDateTime(timezone = currentTimezone) {
+    return DateTime.now().setZone(timezone);
+}
 //# sourceMappingURL=date.js.map

package/dist/src/utils/file-storage.d.ts

@@ -0,0 +1,37 @@
+export interface FileStorageOptions {
+    data: unknown;
+    filePath?: string;
+    baseDir?: string;
+}
+/**
+ * Saves data to a JSON file and returns the file path
+ */
+export declare function saveDataToFile(options: FileStorageOptions): string;
+/**
+ * Common file storage arguments for tools
+ */
+export declare const fileStorageArgs: {
+    saveToFile: {
+        type: "boolean";
+        optional: boolean;
+        describe: string;
+    };
+    filePath: {
+        type: "string";
+        optional: boolean;
+        describe: string;
+    };
+};
+/**
+ * Result of file storage operation
+ */
+export interface FileStorageResult<T> {
+    data: T;
+    savedToFile?: boolean;
+    filePath?: string;
+}
+/**
+ * Processes tool result with optional file storage
+ */
+export declare function processWithFileStorage<T>(data: T, saveToFile?: boolean, filePath?: string): FileStorageResult<T>;
+//# sourceMappingURL=file-storage.d.ts.map

package/dist/src/utils/file-storage.js

@@ -0,0 +1,64 @@
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+/**
+ * Saves data to a JSON file and returns the file path
+ */
+export function saveDataToFile(options) {
+    const { data, filePath, baseDir = "data" } = options;
+    let finalPath;
+    if (filePath) {
+        // Use explicit file path
+        finalPath = filePath;
+    }
+    else {
+        // Generate unique file path
+        const timestamp = Date.now();
+        const randomId = Math.random().toString(36).substring(2, 8);
+        const fileName = `youtrack-data-${timestamp}-${randomId}.json`;
+        finalPath = join(baseDir, fileName);
+    }
+    // Ensure directory exists
+    const dir = dirname(finalPath);
+    mkdirSync(dir, { recursive: true });
+    // Check if file already exists
+    if (existsSync(finalPath)) {
+        throw new Error(`File already exists: ${finalPath}. Choose a different file path or remove the existing file.`);
+    }
+    // Write data to file
+    const jsonData = JSON.stringify(data, null, 2);
+    writeFileSync(finalPath, jsonData, "utf-8");
+    return finalPath;
+}
+/**
+ * Common file storage arguments for tools
+ */
+export const fileStorageArgs = {
+    saveToFile: {
+        type: "boolean",
+        optional: true,
+        describe: "Save results to a file instead of returning them directly. Useful for large datasets that can be analyzed by scripts.",
+    },
+    filePath: {
+        type: "string",
+        optional: true,
+        describe: "Explicit path to save the file (optional, auto-generated if not provided). Directory will be created if it doesn't exist.",
+    },
+};
+/**
+ * Processes tool result with optional file storage
+ */
+export function processWithFileStorage(data, saveToFile, filePath) {
+    if (saveToFile) {
+        const savedPath = saveDataToFile({
+            data,
+            filePath,
+        });
+        return {
+            data,
+            savedToFile: true,
+            filePath: savedPath,
+        };
+    }
+    return { data };
+}
+//# sourceMappingURL=file-storage.js.map

package/dist/src/utils/mappers.d.ts

@@ -48,7 +48,6 @@ export declare function mapIssue(issue: YoutrackIssue): MappedYoutrackIssue;
 export declare function mapIssueDetails(issue: YoutrackIssueDetails): MappedYoutrackIssueDetails;
 /**
  * Map YoutrackIssue to brief version (without description fields)
- * Used for reducing payload size in issue_search_by_user_activity tool
  */
 export declare function mapIssueBrief(issue: YoutrackIssue): MappedYoutrackIssue;
 /**

package/dist/src/utils/mappers.js

@@ -50,7 +50,6 @@ export function mapIssueDetails(issue) {
 }
 /**
  * Map YoutrackIssue to brief version (without description fields)
- * Used for reducing payload size in issue_search_by_user_activity tool
  */
 export function mapIssueBrief(issue) {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/dist/src/youtrack-client.d.ts

@@ -53,6 +53,16 @@ export declare class YoutrackClient {
         startDate?: number;
         endDate?: number;
     }): Promise<YoutrackActivityItem[]>;
+    listActivities({ author, categories, start, end, limit, skip, fields, reverse, }: {
+        author: string;
+        categories?: string;
+        start?: number;
+        end?: number;
+        limit?: number;
+        skip?: number;
+        fields?: string;
+        reverse?: boolean;
+    }): Promise<YoutrackActivityItem[]>;
     createIssue(input: YoutrackIssueCreateInput): Promise<IssueLookupPayload>;
     updateIssue(input: YoutrackIssueUpdateInput): Promise<IssueLookupPayload>;
     assignIssue(input: YoutrackIssueAssignInput): Promise<IssueLookupPayload>;

package/dist/src/youtrack-client.js

@@ -1,8 +1,9 @@
 import axios from "axios";
 import FormData from "form-data";
 import fs from "fs";
+import { DateTime } from "luxon";
 import { MutexPool } from "@vitalyostanin/mutex-pool";
-import { calculateTotalMinutes, enumerateDateRange, filterWorkingDays, getDayBounds, groupWorkItemsByDate, isWeekend, minutesToHours, parseDateInput, toIsoDateString, validateDateRange, } from "./utils/date.js";
+import { calculateTotalMinutes, enumerateDateRange, filterWorkingDays, getCurrentDateTime, getCurrentTimestamp, getDayBounds, groupWorkItemsByDate, isWeekend, minutesToHours, parseDateInput, toIsoDateString, validateDateRange, } from "./utils/date.js";
 import { mapAttachment, mapAttachments, mapComment, mapComments, mapIssue, mapIssueBrief, mapIssueDetails, mapWorkItem, mapWorkItems, } from "./utils/mappers.js";
 import { buildIssueQuery } from "./utils/issue-query.js";
 const DEFAULT_PAGE_SIZE = 200;
@@ -120,13 +121,15 @@ export class YoutrackClient {
             Object.prototype.hasOwnProperty.call(params, "skip");
         // First attempt: prefer $top/$skip
         const dollarParams = { ...params };
-        if (Object.prototype.hasOwnProperty.call(dollarParams, "top") && !Object.prototype.hasOwnProperty.call(dollarParams, "$top")) {
-            (dollarParams).$top = (dollarParams).top;
-            delete (dollarParams).top;
+        if (Object.prototype.hasOwnProperty.call(dollarParams, "top") &&
+            !Object.prototype.hasOwnProperty.call(dollarParams, "$top")) {
+            dollarParams.$top = dollarParams.top;
+            delete dollarParams.top;
         }
-        if (Object.prototype.hasOwnProperty.call(dollarParams, "skip") && !Object.prototype.hasOwnProperty.call(dollarParams, "$skip")) {
-            (dollarParams).$skip = (dollarParams).skip;
-            delete (dollarParams).skip;
+        if (Object.prototype.hasOwnProperty.call(dollarParams, "skip") &&
+            !Object.prototype.hasOwnProperty.call(dollarParams, "$skip")) {
+            dollarParams.$skip = dollarParams.skip;
+            delete dollarParams.skip;
         }
         try {
             const res = await this.http.get(url, { params: dollarParams });
@@ -137,12 +140,12 @@ export class YoutrackClient {
                 // Retry with plain top/skip
                 const plainParams = { ...params };
                 if (Object.prototype.hasOwnProperty.call(plainParams, "$top")) {
-                    (plainParams).top = (plainParams).$top;
-                    delete (plainParams).$top;
+                    plainParams.top = plainParams.$top;
+                    delete plainParams.$top;
                 }
                 if (Object.prototype.hasOwnProperty.call(plainParams, "$skip")) {
-                    (plainParams).skip = (plainParams).$skip;
-                    delete (plainParams).$skip;
+                    plainParams.skip = plainParams.$skip;
+                    delete plainParams.$skip;
                 }
                 const res2 = await this.http.get(url, { params: plainParams });
                 return res2.data;
@@ -608,6 +611,34 @@ export class YoutrackClient {
             throw this.normalizeError(error);
         }
     }
+    async listActivities({ author, categories, start, end, limit, skip, fields, reverse, }) {
+        const params = {
+            author,
+            fields: fields ??
+                "id,timestamp,author(id,login,name),category(id),target(issue(idReadable,summary),text),added(name,id,login),removed(name,id,login),$type",
+        };
+        if (categories) {
+            params.categories = categories;
+        }
+        if (typeof start === "number") {
+            params.start = start;
+        }
+        if (typeof end === "number") {
+            params.end = end;
+        }
+        params.$top = Math.min(limit ?? DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE);
+        params.$skip = skip ?? 0;
+        if (reverse !== undefined) {
+            params.reverse = reverse;
+        }
+        try {
+            const response = await this.http.get("/api/activities", { params });
+            return response.data;
+        }
+        catch (error) {
+            throw this.normalizeError(error);
+        }
+    }
     async createIssue(input) {
         const projectIdentifier = input.projectId ?? this.defaultProject;
         if (!projectIdentifier) {
@@ -909,7 +940,7 @@ export class YoutrackClient {
         // Add date range filter if provided
         if (input.startDate || input.endDate) {
             const startDateStr = input.startDate ? toIsoDateString(input.startDate) : "1970-01-01";
-            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : toIsoDateString(new Date());
+            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : getCurrentDateTime().toISO();
             filters.push(`updated: ${startDateStr} .. ${endDateStr}`);
         }
         // Add sorting by updated time descending
@@ -952,7 +983,7 @@ export class YoutrackClient {
         // and to reduce candidate set before precise post-filtering.
         if (input.startDate || input.endDate) {
             const startDateStr = input.startDate ? toIsoDateString(input.startDate) : "1970-01-01";
-            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : toIsoDateString(new Date());
+            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : getCurrentDateTime().toISO();
             filters.push(`updated: ${startDateStr} .. ${endDateStr}`);
         }
         const sortPart = "sort by: updated desc";
@@ -1057,7 +1088,10 @@ export class YoutrackClient {
                     const limit = input.limit ?? 100;
                     const paginatedIssues = issuesWithActivity.slice(skip, skip + limit);
                     const mapperFn = briefOutput ? mapIssueBrief : mapIssue;
-                    const resultIssues = paginatedIssues.map(({ issue, lastActivityDate }) => ({ ...mapperFn(issue), lastActivityDate }));
+                    const resultIssues = paginatedIssues.map(({ issue, lastActivityDate }) => ({
+                        ...mapperFn(issue),
+                        lastActivityDate,
+                    }));
                     return {
                         issues: resultIssues,
                         userLogins: input.userLogins,
@@ -1085,8 +1119,8 @@ export class YoutrackClient {
      * Used in user_activity mode to determine which issues had activity from specified users
      */
     filterIssuesByUserActivity(candidateIssues, detailsLight, commentsLight, activitiesResults, input) {
-        const startTimestamp = input.startDate ? new Date(input.startDate).getTime() : 0;
-        const endTimestamp = input.endDate ? new Date(input.endDate).getTime() : Date.now();
+        const startTimestamp = input.startDate ? parseDateInput(input.startDate) : 0;
+        const endTimestamp = input.endDate ? parseDateInput(input.endDate) : getCurrentTimestamp();
         const issuesWithActivity = [];
         for (let i = 0; i < candidateIssues.length; i++) {
             const issue = candidateIssues[i];
@@ -1137,7 +1171,7 @@ export class YoutrackClient {
             }
             if (dates.length > 0) {
                 const lastActivityTimestamp = Math.max(...dates);
-                const lastActivityDate = new Date(lastActivityTimestamp).toISOString();
+                const lastActivityDate = DateTime.fromMillis(lastActivityTimestamp).toISO() ?? "";
                 issuesWithActivity.push({
                     issue,
                     lastActivityDate,
@@ -1145,7 +1179,7 @@ export class YoutrackClient {
             }
         }
         // Sort by lastActivityDate descending
-        issuesWithActivity.sort((a, b) => new Date(b.lastActivityDate).getTime() - new Date(a.lastActivityDate).getTime());
+        issuesWithActivity.sort((a, b) => (a.lastActivityDate < b.lastActivityDate ? 1 : -1));
         return issuesWithActivity;
     }
     // Helper to perform fallback request without braces in user filters
@@ -1157,7 +1191,7 @@ export class YoutrackClient {
         }
         if (input.startDate || input.endDate) {
             const startDateStr = input.startDate ? toIsoDateString(input.startDate) : "1970-01-01";
-            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : toIsoDateString(new Date());
+            const endDateStr = input.endDate ? toIsoDateString(input.endDate) : getCurrentDateTime().toISO();
             fallbackFilters.push(`updated: ${startDateStr} .. ${endDateStr}`);
         }
         const fallbackQuery = (fallbackFilters.length ? `${fallbackFilters.join(" and ")} ` : "") + sortPart;
@@ -1788,8 +1822,8 @@ export class YoutrackClient {
     }
     resolveReportBoundary(items, mode) {
         if (!items.length) {
-            const todayIso = toIsoDateString(new Date());
-            return todayIso;
+            const todayIso = getCurrentDateTime().toISO();
+            return todayIso ?? "";
         }
         const timestamps = items.map((item) => item.date);
         const target = mode === "min" ? Math.min(...timestamps) : Math.max(...timestamps);
@@ -2095,7 +2129,7 @@ export class YoutrackClient {
         const { briefOutput = true, limit = DEFAULT_PAGE_SIZE, skip = 0, sortField, sortDirection, ...filtersInput } = input;
         const { query } = await buildIssueQuery(filtersInput, (projectId) => this.getProjectById(projectId));
         const fields = briefOutput ? defaultFields.issueSearchBrief : defaultFields.issueSearch;
-        const { field: resolvedField, direction: resolvedDirection, sortParam } = this.resolveSort(sortField, sortDirection);
+        const { field: resolvedField, direction: resolvedDirection, sortParam, } = this.resolveSort(sortField, sortDirection);
         const params = {
             $top: Math.min(limit, DEFAULT_PAGE_SIZE),
             $skip: skip,
@@ -2104,7 +2138,9 @@ export class YoutrackClient {
             ...(query ? { query } : {}),
         };
         const data = await this.getWithFlexibleTop("/api/issues", params);
-        const issues = Array.isArray(data) ? data.map((issue) => (briefOutput ? mapIssueBrief(issue) : mapIssue(issue))) : [];
+        const issues = Array.isArray(data)
+            ? data.map((issue) => (briefOutput ? mapIssueBrief(issue) : mapIssue(issue)))
+            : [];
         return {
             issues,
             filters: {

package/package.json

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