@vitalyostanin/youtrack-mcp 0.8.0 → 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)
+    - [Параметры сохранения файлов](#параметры-сохранения-файлов)
     - [Сервис](#сервис)
     - [Задачи](#задачи)
     - [Связи задач](#связи-задач)
@@ -272,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 | Описание | Основные параметры |

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)
@@ -276,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 |

package/dist/package.json

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

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

@@ -9,6 +9,8 @@ export declare const usersActivityArgs: {
     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;
@@ -19,6 +21,8 @@ export declare const usersActivitySchema: z.ZodObject<{
     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;
@@ -28,6 +32,8 @@ export declare const usersActivitySchema: z.ZodObject<{
     fields?: string | undefined;
     start?: string | number | Date | undefined;
     end?: string | number | Date | undefined;
+    filePath?: string | undefined;
+    saveToFile?: boolean | undefined;
 }, {
     author: string;
     categories: string;
@@ -37,6 +43,8 @@ export declare const usersActivitySchema: z.ZodObject<{
     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;

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

@@ -2,6 +2,7 @@ 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()
@@ -39,6 +40,8 @@ export const usersActivityArgs = {
         .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) {
@@ -75,6 +78,16 @@ export async function usersActivityHandler(client, rawInput) {
                 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) {

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/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/package.json

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