@vitalyostanin/youtrack-mcp 0.5.1 → 0.6.0

package/README-ru.md

@@ -52,7 +52,7 @@ MCP сервер для полноценной интеграции с YouTrack
   - `YOUTRACK_HOLIDAYS` — опциональный список праздничных дат через запятую (формат `YYYY-MM-DD`), исключаемых из отчётов и массовых операций
   - `YOUTRACK_PRE_HOLIDAYS` — опциональный список предпраздничных дат через запятую, для которых норма времени уменьшается автоматически
   - `YOUTRACK_USER_ALIASES` — опциональный список соответствий `alias:login` через запятую (например, `me:vyt,petya:p.petrov`), используется при автоматическом выборе исполнителей
-  - `YOUTRACK_COMPACT_MODE` — опциональный, управляет минимизацией ответов для оптимизации контекстного окна AI (по умолчанию: `true`). Установите `false` для Claude Code, чтобы получать полный текст ответа в поле MCP content вместо минимальной заглушки. При `true` полные данные доступны в поле `structuredContent`
+  - `YOUTRACK_USE_STRUCTURED_CONTENT` — опциональный, управляет форматом ответа (по умолчанию: `true`). При `true` инструменты возвращают только узел MCP `structuredContent` с полными данными. При `false` инструменты возвращают только узел MCP `content` (один текстовый элемент с JSON-строкой)
 
 ## Установка
 
@@ -220,7 +220,7 @@ YOUTRACK_TOKEN = "perm:your-token-here"
       "env": {
         "YOUTRACK_URL": "https://youtrack.example.com",
         "YOUTRACK_TOKEN": "perm:your-token-here",
-        "YOUTRACK_COMPACT_MODE": "false"
+        "YOUTRACK_USE_STRUCTURED_CONTENT": "false"
       }
     }
   }
@@ -229,7 +229,7 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 
 **Примечание:** Эта конфигурация использует npx для запуска опубликованного пакета. Для локальной разработки используйте `"command": "node"` с `"args": ["/абсолютный/путь/к/youtrack-mcp/dist/index.js"]`. Переменные окружения `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HOLIDAYS` и `YOUTRACK_USER_ALIASES` являются опциональными.
 
-**Для пользователей Claude Code:** Установите `YOUTRACK_COMPACT_MODE` в `"false"`, чтобы включить полные данные ответа в поле MCP content. Это помогает Claude Code легче получать доступ к структурированным данным. При `true` (по умолчанию) в поле content возвращается только минимальная заглушка для оптимизации использования контекстного окна для других AI агентов.
+**Для пользователей Claude Code:** Установите `YOUTRACK_USE_STRUCTURED_CONTENT` в `"false"`, чтобы включить полные данные ответа в поле MCP `content` (в виде JSON-строки). При `true` (по умолчанию) возвращается только `structuredContent`.
 
 ## Конфигурация для VS Code Cline
 
@@ -249,20 +249,20 @@ YOUTRACK_TOKEN = "perm:your-token-here"
       "env": {
         "YOUTRACK_URL": "https://youtrack.example.com",
         "YOUTRACK_TOKEN": "perm:your-token-here",
-        "YOUTRACK_COMPACT_MODE": "false"
+        "YOUTRACK_USE_STRUCTURED_CONTENT": "false"
       }
     }
   }
 }
 ```
 
-**Важно для Cline:** Установите `YOUTRACK_COMPACT_MODE` в `"false"`, чтобы полные ответы инструментов также попадали в поле `content` MCP (в дополнение к `structuredContent`). Это повышает совместимость с клиентами, рассчитывающими на текстовое содержимое.
+**Важно для Cline:** Установите `YOUTRACK_USE_STRUCTURED_CONTENT` в `"false"`, чтобы полные ответы инструментов возвращались в поле MCP `content`. Некоторые клиенты полагаются на текстовое содержимое.
 
 **Примечание:** Эта конфигурация использует npx для запуска опубликованного пакета. Для локальной разработки используйте `"command": "node"` с `"args": ["/абсолютный/путь/к/youtrack-mcp/dist/index.js"]`. Переменные окружения `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HОЛИДAYS` и `YOUTRACK_USER_ALIASES` являются опциональными.
 
 ## Инструменты MCP
 
-Все инструменты возвращают `structuredContent` с флагом `success` и полезной нагрузкой в формате, ожидаемом клиентами MCP. Каждый инструмент включает подсказки по использованию, примеры параметров и объяснение ключевых полей ответа.
+Инструменты возвращают либо `structuredContent` (по умолчанию), либо текстовый элемент `content` — в зависимости от `YOUTRACK_USE_STRUCTURED_CONTENT`.
 
 ### Сервис
 
@@ -276,8 +276,8 @@ YOUTRACK_TOKEN = "perm:your-token-here"
 | --- | --- | --- |
 | `issue_lookup` | Краткая информация о задаче. **Использование:** Быстрый просмотр базовой информации о задаче без полной детализации. **Возвращает:** предопределенные поля - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, project, parent, assignee. Пользовательские поля не включены. | `issueId` — код задачи (например, `PROJ-123`) |
 | `issues_lookup` | Краткая информация о нескольких задачах (пакетный режим, макс 50). **Использование:** Эффективное получение информации о множестве задач одновременно. **Возвращает:** те же поля, что и `issue_lookup`. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач (например, `['PROJ-123', 'PROJ-124']`) |
-| `issue_details` | Полные данные о задаче. **Использование:** Получение детальной информации о задаче, включая даты создания/обновления/решения, автора, обновившего пользователя. **Возвращает:** расширенный набор полей - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project, parent, assignee, reporter, updater. Пользовательские поля не включены. | `issueId` — код задачи |
-| `issues_details` | Детальная информация о нескольких задачах (пакетный режим, макс 50). **Использование:** Эффективное получение детальной информации о множестве задач. **Возвращает:** те же поля, что и `issue_details`. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач |
+| `issue_details` | Режимы краткий/полный для деталей задачи. **Использование:** Просмотр деталей задачи. **Краткий (по умолчанию):** предопределённые поля — id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project, parent, assignee, reporter, updater, watchers(hasStar). **Полный (`briefOutput=false`):** добавляет `customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation))`, включая поле `State`. | `issueId` — код задачи; `briefOutput` — опционально (по умолчанию `true`) |
+| `issues_details` | Режимы краткий/полный для множества задач (макс 50). **Краткий:** предопределённые поля. **Полный (`briefOutput=false`):** добавляет `customFields` для каждой задачи. **Замечание:** объём ответа может быть большим, поэтому по умолчанию используется краткий режим. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач; `briefOutput` — опционально (по умолчанию `true`) |
 | `issue_comments` | Комментарии задачи. **Использование:** Просмотр всех комментариев к задаче. **Возвращает:** предопределенные поля - id, text, textPreview, usesMarkdown, author (id, login, name), created, updated | `issueId` — код задачи |
 | `issues_comments` | Комментарии для нескольких задач (пакетный режим, макс 50). **Использование:** Эффективное получение комментариев для множества задач одновременно. **Ограничение:** максимум 50 задач за запрос | `issueIds[]` — массив кодов задач |
 | `issue_create` | Создание новой задачи в YouTrack. **Использование:** Создание задач, подзадач (через `parentIssueId`), назначение исполнителя при создании. **Возвращает:** стандартные поля созданной задачи (id, idReadable, summary, description, wikifiedDescription, usesMarkdown, project, parent, assignee). Пользовательские поля не включены. | `projectId` — ID проекта (внутренний YouTrack ID), `summary` — краткое описание задачи, опционально `description`, `parentIssueId`, `assigneeLogin` (логин или `me`), `usesMarkdown` |

package/README.md

@@ -56,7 +56,7 @@ MCP server for comprehensive YouTrack integration with the following capabilitie
   - `YOUTRACK_HOLIDAYS` — optional comma-separated list of holiday dates (format `YYYY-MM-DD`), excluded from reports and batch operations
   - `YOUTRACK_PRE_HOLIDAYS` — optional comma-separated list of pre-holiday dates with reduced working hours
   - `YOUTRACK_USER_ALIASES` — optional comma-separated list of `alias:login` mappings (e.g., `me:vyt,petya:p.petrov`), used for automatic assignee selection
-  - `YOUTRACK_COMPACT_MODE` — optional, controls response minimization for AI context window optimization (default: `true`). Set to `false` for Claude Code to get full response text in MCP content field instead of minimal stub. When `true`, full data is available in `structuredContent` field
+  - `YOUTRACK_USE_STRUCTURED_CONTENT` — optional, controls response format (default: `true`). When `true`, tools return only the MCP `structuredContent` node with full data. When `false`, tools return only the MCP `content` node (single text item with JSON string)
 
 ## Installation
 
@@ -224,7 +224,7 @@ To use this MCP server with [Claude Code CLI](https://github.com/anthropics/clau
       "env": {
         "YOUTRACK_URL": "https://youtrack.example.com",
         "YOUTRACK_TOKEN": "perm:your-token-here",
-        "YOUTRACK_COMPACT_MODE": "false"
+        "YOUTRACK_USE_STRUCTURED_CONTENT": "false"
       }
     }
   }
@@ -233,7 +233,7 @@ To use this MCP server with [Claude Code CLI](https://github.com/anthropics/clau
 
 **Note:** This configuration uses npx to run the published package. For local development, use `"command": "node"` with `"args": ["/absolute/path/to/youtrack-mcp/dist/index.js"]`. The `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HOLIDAYS`, and `YOUTRACK_USER_ALIASES` environment variables are optional.
 
-**For Claude Code users:** Set `YOUTRACK_COMPACT_MODE` to `"false"` to include full response data in the MCP content field. This helps Claude Code access structured data more easily. When `true` (default), only a minimal stub is returned in the content field to optimize context window usage for other AI agents.
+**For Claude Code users:** Set `YOUTRACK_USE_STRUCTURED_CONTENT` to `"false"` to include full response data in the MCP `content` field (as a JSON string). When `true` (default), only `structuredContent` is returned.
 
 ## Configuration for VS Code Cline
 
@@ -253,20 +253,20 @@ To use this MCP server with [Cline](https://github.com/cline/cline) extension in
       "env": {
         "YOUTRACK_URL": "https://youtrack.example.com",
         "YOUTRACK_TOKEN": "perm:your-token-here",
-        "YOUTRACK_COMPACT_MODE": "false"
+        "YOUTRACK_USE_STRUCTURED_CONTENT": "false"
       }
     }
   }
 }
 ```
 
-**Important for Cline:** Set `YOUTRACK_COMPACT_MODE` to `"false"` so full tool responses are also included in the MCP `content` field (in addition to `structuredContent`). This improves compatibility with some clients relying on text content.
+**Important for Cline:** Set `YOUTRACK_USE_STRUCTURED_CONTENT` to `"false"` so full tool responses are provided in the MCP `content` field. Some clients rely on text content.
 
 **Note:** This configuration uses npx to run the published package. For local development, use `"command": "node"` with `"args": ["/absolute/path/to/youtrack-mcp/dist/index.js"]`. The `YOUTRACK_TIMEZONE`, `YOUTRACK_HOLIDAYS`, `YOUTRACK_PRE_HOLIDAYS`, and `YOUTRACK_USER_ALIASES` environment variables are optional.
 
 ## MCP Tools
 
-All tools return `structuredContent` with a `success` flag and payload formatted for MCP clients.
+Tools return either `structuredContent` (default) or a text `content` item, depending on `YOUTRACK_USE_STRUCTURED_CONTENT`.
 
 ### Service
 
@@ -279,7 +279,7 @@ All tools return `structuredContent` with a `success` flag and payload formatted
 | Tool | Description | Main Parameters |
 | --- | --- | --- |
 | `issue_lookup` | Brief issue information | `issueId` — issue code (e.g., PROJ-123) |
-| `issue_details` | Full issue data | `issueId` — issue code |
+| `issue_details` | Issue details with brief/full modes | `issueId` — issue code; `briefOutput` — optional boolean (default `true`). Brief: predefined fields only. Full (`false`): adds `customFields` including `State` |
 | `issue_comments` | Issue comments | `issueId` — issue code |
 | `issue_create` | Create issue | `projectId`, `summary`, optionally `description`, `parentIssueId`, `assigneeLogin`, `usesMarkdown` |
 | `issue_update` | Update existing issue | `issueId`, optionally `summary`, `description`, `parentIssueId` (empty string clears parent), `usesMarkdown` |

package/dist/package.json

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

package/dist/src/config.d.ts

@@ -6,6 +6,6 @@ export declare function enrichConfigWithRedaction(config: YoutrackConfig): {
     timezone: string;
     holidays: string[] | undefined;
     preHolidays: string[] | undefined;
-    compactMode: boolean;
+    useStructuredContent: boolean;
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/src/config.js

@@ -6,7 +6,7 @@ const configSchema = z.object({
     YOUTRACK_HOLIDAYS: z.string().optional(),
     YOUTRACK_PRE_HOLIDAYS: z.string().optional(),
     YOUTRACK_USER_ALIASES: z.string().optional(),
-    YOUTRACK_COMPACT_MODE: z
+    YOUTRACK_USE_STRUCTURED_CONTENT: z
         .string()
         .optional()
         .default("true")
@@ -37,7 +37,7 @@ export function loadConfig(env = process.env) {
         userAliases: parsed.data.YOUTRACK_USER_ALIASES
             ? parseAliasMap(parsed.data.YOUTRACK_USER_ALIASES)
             : undefined,
-        compactMode: parsed.data.YOUTRACK_COMPACT_MODE,
+        useStructuredContent: parsed.data.YOUTRACK_USE_STRUCTURED_CONTENT,
     };
 }
 export function enrichConfigWithRedaction(config) {
@@ -47,7 +47,7 @@ export function enrichConfigWithRedaction(config) {
         timezone: config.timezone,
         holidays: config.holidays,
         preHolidays: config.preHolidays,
-        compactMode: config.compactMode,
+        useStructuredContent: config.useStructuredContent,
     };
 }
 function parseCsvList(value) {

package/dist/src/server.js

@@ -15,6 +15,7 @@ import { YoutrackClient } from "./youtrack-client.js";
 import { loadConfig } from "./config.js";
 import { initializeTimezone } from "./utils/date.js";
 import { VERSION } from "./version.js";
+import { setDefaultUseStructuredContent } from "./utils/tool-response.js";
 export class YoutrackServer {
     server;
     client;
@@ -32,14 +33,15 @@ export class YoutrackServer {
         });
         const config = loadConfig();
         initializeTimezone(config.timezone);
+        setDefaultUseStructuredContent(config.useStructuredContent);
         this.client = new YoutrackClient(config);
         registerServiceInfoTool(this.server, this.client);
         registerIssueTools(this.server, this.client);
         registerIssueActivityTools(this.server, this.client);
-        registerIssueSearchTools(this.server, this.client, config);
+        registerIssueSearchTools(this.server, this.client);
         registerWorkitemTools(this.server, this.client);
         registerWorkitemReportTools(this.server, this.client);
-        registerArticleTools(this.server, this.client, config);
+        registerArticleTools(this.server, this.client);
         registerArticleSearchTools(this.server, this.client);
         registerUserTools(this.server, this.client);
         registerProjectTools(this.server, this.client);

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

@@ -1,5 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { YoutrackClient } from "../youtrack-client.js";
-import type { YoutrackConfig } from "../types.js";
-export declare function registerArticleTools(server: McpServer, client: YoutrackClient, config?: YoutrackConfig): void;
+export declare function registerArticleTools(server: McpServer, client: YoutrackClient): void;
 //# sourceMappingURL=article-tools.d.ts.map

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

@@ -32,12 +32,12 @@ const articleLookupSchema = z.object(articleLookupArgs);
 const articleListSchema = z.object(articleListArgs);
 const articleCreateSchema = z.object(articleCreateArgs);
 const articleUpdateSchema = z.object(articleUpdateArgs);
-export function registerArticleTools(server, client, config) {
+export function registerArticleTools(server, client) {
     server.tool("article_get", "Get YouTrack article by ID. Note: Returns predefined fields only - id, idReadable, summary, content, contentPreview, usesMarkdown, parentArticle (id, idReadable), project (id, shortName, name).", articleLookupArgs, async (rawInput) => {
         try {
             const payload = articleLookupSchema.parse(rawInput);
             const article = await client.getArticle(payload.articleId);
-            const response = toolSuccess(article, config?.compactMode);
+            const response = toolSuccess(article);
             return response;
         }
         catch (error) {
@@ -52,7 +52,7 @@ export function registerArticleTools(server, client, config) {
                 parentArticleId: payload.parentArticleId,
                 projectId: payload.projectId,
             });
-            const response = toolSuccess(articles, config?.compactMode);
+            const response = toolSuccess(articles);
             return response;
         }
         catch (error) {
@@ -71,7 +71,7 @@ export function registerArticleTools(server, client, config) {
                 usesMarkdown: payload.usesMarkdown,
                 returnRendered: payload.returnRendered,
             });
-            const response = toolSuccess(article, config?.compactMode);
+            const response = toolSuccess(article);
             return response;
         }
         catch (error) {
@@ -92,7 +92,7 @@ export function registerArticleTools(server, client, config) {
                 usesMarkdown: payload.usesMarkdown,
                 returnRendered: payload.returnRendered,
             });
-            const response = toolSuccess(article, config?.compactMode);
+            const response = toolSuccess(article);
             return response;
         }
         catch (error) {

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

@@ -1,5 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { YoutrackClient } from "../youtrack-client.js";
-import type { YoutrackConfig } from "../types.js";
-export declare function registerIssueSearchTools(server: McpServer, client: YoutrackClient, config: YoutrackConfig): void;
+export declare function registerIssueSearchTools(server: McpServer, client: YoutrackClient): void;
 //# sourceMappingURL=issue-search-tools.d.ts.map

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

@@ -36,7 +36,7 @@ const issueSearchByUserActivityArgs = {
         .describe("Number of results to skip for pagination (default: 0)"),
 };
 const issueSearchByUserActivitySchema = z.object(issueSearchByUserActivityArgs);
-export function registerIssueSearchTools(server, client, config) {
+export function registerIssueSearchTools(server, client) {
     server.tool("issue_search_by_user_activity", "Search for issues where specified users had activity (updated, mentioned, reported, assigned, commented) within a given time period. Supports two filter modes: 'issue_updated' (default, fast) uses issue.updated field, 'user_activity' (slow, precise) checks actual user activity dates including comments, mentions, and field changes history. Results are sorted by activity time (most recent first). When 'user_activity' mode is used, each issue includes 'lastActivityDate' field with exact timestamp of user's last activity. Supports pagination via limit and skip parameters. Note: By default (briefOutput=true), each issue includes minimal fields only - id, idReadable, summary, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name). Description fields are excluded to reduce response size. Set briefOutput=false to include full description and wikifiedDescription fields. Custom fields are not included.", issueSearchByUserActivityArgs, async (rawInput) => {
         try {
             const payload = issueSearchByUserActivitySchema.parse(rawInput);
@@ -49,7 +49,7 @@ export function registerIssueSearchTools(server, client, config) {
                 limit: payload.limit,
                 skip: payload.skip,
             });
-            const response = toolSuccess(results, config.compactMode);
+            const response = toolSuccess(results);
             return response;
         }
         catch (error) {

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

@@ -2,6 +2,10 @@ import { z } from "zod";
 import { toolError, toolSuccess } from "../utils/tool-response.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."),
 };
 const issueIdSchema = z.object(issueIdArgs);
 const issueIdsArgs = {
@@ -10,6 +14,10 @@ const issueIdsArgs = {
         .min(1)
         .max(50)
         .describe("Array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50"),
+    briefOutput: z
+        .boolean()
+        .optional()
+        .describe("Brief mode (default: true). When false, include all available customFields for each issue."),
 };
 const issueIdsSchema = z.object(issueIdsArgs);
 const issueCreateArgs = {
@@ -81,10 +89,11 @@ export function registerIssueTools(server, client) {
             return errorResponse;
         }
     });
-    server.tool("issue_details", "Get detailed information about YouTrack issue. Note: Returns predefined fields only - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). Custom fields are not included.", issueIdArgs, async (rawInput) => {
+    server.tool("issue_details", "Get detailed information about YouTrack issue. Use for: Viewing full issue details.\n- Brief (default): returns predefined fields only — id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project(id,shortName,name), parent(id,idReadable), assignee(id,login,name), reporter(id,login,name), updater(id,login,name), watchers(hasStar).\n- Full (briefOutput=false): adds customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation)) so you can read State and other custom fields.", issueIdArgs, async (rawInput) => {
         try {
             const payload = issueIdSchema.parse(rawInput);
-            const details = await client.getIssueDetails(payload.issueId);
+            const brief = payload.briefOutput ?? true;
+            const details = await client.getIssueDetails(payload.issueId, !brief);
             const response = toolSuccess(details);
             return response;
         }
@@ -211,10 +220,11 @@ export function registerIssueTools(server, client) {
             return errorResponse;
         }
     });
-    server.tool("issues_details", "Get detailed information about multiple YouTrack issues (batch mode, max 50). Note: Returns predefined fields only - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). Custom fields are not included.", issueIdsArgs, async (rawInput) => {
+    server.tool("issues_details", "Get detailed information about multiple YouTrack issues (batch mode, max 50). Use for: Efficiently fetching issue details.\n- Brief (default): returns predefined fields only — id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, resolved, project(id,shortName,name), parent(id,idReadable), assignee(id,login,name), reporter(id,login,name), updater(id,login,name), watchers(hasStar).\n- Full (briefOutput=false): adds customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation)) for each issue. Note: payloads can be large; defaults stay brief.", issueIdsArgs, async (rawInput) => {
         try {
             const payload = issueIdsSchema.parse(rawInput);
-            const result = await client.getIssuesDetails(payload.issueIds);
+            const brief = payload.briefOutput ?? true;
+            const result = await client.getIssuesDetails(payload.issueIds, !brief);
             const response = toolSuccess(result);
             return response;
         }

package/dist/src/tools/service-info.js

@@ -1,61 +1,22 @@
-import { ZodError } from "zod";
 import { loadConfig, enrichConfigWithRedaction } from "../config.js";
 import { VERSION } from "../version.js";
+import { toolError, toolSuccess } from "../utils/tool-response.js";
 export function registerServiceInfoTool(server, client) {
     server.tool("service_info", "Get YouTrack integration status and environment configuration", async () => {
         try {
-            const config = loadConfig();
+            const freshConfig = loadConfig();
             const currentUser = await client.getCurrentUser();
             const payload = {
                 service: {
                     name: "youtrack-mcp",
                     version: VERSION,
                 },
-                configuration: enrichConfigWithRedaction(config),
+                configuration: enrichConfigWithRedaction(freshConfig),
             };
-            const result = {
-                content: [],
-                structuredContent: {
-                    ...payload,
-                    currentUser,
-                },
-            };
-            return result;
+            return toolSuccess({ ...payload, currentUser });
         }
         catch (error) {
-            if (error instanceof ZodError) {
-                const result = {
-                    content: [],
-                    isError: true,
-                    structuredContent: {
-                        name: "ValidationError",
-                        message: "Invalid configuration",
-                        details: error.flatten(),
-                    },
-                };
-                return result;
-            }
-            if (error instanceof Error) {
-                const result = {
-                    content: [],
-                    isError: true,
-                    structuredContent: {
-                        name: error.name,
-                        message: error.message,
-                    },
-                };
-                return result;
-            }
-            const result = {
-                content: [],
-                isError: true,
-                structuredContent: {
-                    name: "UnknownError",
-                    message: "An unknown error occurred",
-                    details: error,
-                },
-            };
-            return result;
+            return toolError(error);
         }
     });
 }

package/dist/src/types.d.ts

@@ -12,7 +12,7 @@ export interface YoutrackConfig {
     holidays?: string[];
     preHolidays?: string[];
     userAliases?: UserAliasMap;
-    compactMode: boolean;
+    useStructuredContent: boolean;
 }
 export interface DurationValue {
     minutes?: number;

package/dist/src/utils/tool-response.d.ts

@@ -1,4 +1,6 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-export declare function toolSuccess<T>(payload: T, compactMode?: boolean): CallToolResult;
-export declare function toolError(error: unknown): CallToolResult;
+export declare function setDefaultUseStructuredContent(value: boolean): void;
+export declare function getDefaultUseStructuredContent(): boolean;
+export declare function toolSuccess<T>(payload: T, useStructuredContent?: boolean): CallToolResult;
+export declare function toolError(error: unknown, useStructuredContent?: boolean): CallToolResult;
 //# sourceMappingURL=tool-response.d.ts.map

package/dist/src/utils/tool-response.js

@@ -1,67 +1,73 @@
 import { ZodError } from "zod";
-export function toolSuccess(payload, compactMode = true) {
-    const structuredContent = {
-        success: true,
-        payload,
-    };
-    // In compact mode, minimize content field to reduce context window usage for AI agents.
-    // Claude Code (when compactMode=false) gets full data in content field for better accessibility.
-    // Other AI agents benefit from minimal content to save context window tokens.
-    const contentText = compactMode
-        ? "Success. Use structuredContent for full data."
-        : JSON.stringify(structuredContent, null, 2);
+let defaultUseStructuredContent = true;
+export function setDefaultUseStructuredContent(value) {
+    defaultUseStructuredContent = value;
+}
+export function getDefaultUseStructuredContent() {
+    return defaultUseStructuredContent;
+}
+export function toolSuccess(payload, useStructuredContent = defaultUseStructuredContent) {
+    const base = { success: true, payload };
+    if (useStructuredContent) {
+        return {
+            content: [],
+            structuredContent: base,
+        };
+    }
     return {
         content: [
             {
                 type: "text",
-                text: contentText,
+                text: JSON.stringify(base),
             },
         ],
-        structuredContent,
     };
 }
-export function toolError(error) {
+export function toolError(error, useStructuredContent = defaultUseStructuredContent) {
     if (error instanceof ZodError) {
-        const structuredContent = {
-            success: false,
-            error: {
-                name: "ValidationError",
-                message: "Invalid input",
-                details: error.flatten(),
-            },
-        };
-        return {
-            content: [],
-            isError: true,
-            structuredContent,
+        const errObj = {
+            name: "ValidationError",
+            message: "Invalid input",
+            details: error.flatten(),
         };
+        return useStructuredContent
+            ? { isError: true, content: [], structuredContent: errObj }
+            : {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(errObj),
+                    },
+                ],
+            };
     }
     if (error instanceof Error) {
-        const structuredContent = {
-            success: false,
-            error: {
-                name: error.name,
-                message: error.message,
-            },
-        };
-        return {
-            content: [],
-            isError: true,
-            structuredContent,
+        const errObj = {
+            name: error.name,
+            message: error.message,
         };
+        return useStructuredContent
+            ? { isError: true, content: [], structuredContent: errObj }
+            : {
+                isError: true,
+                content: [
+                    { type: "text", text: JSON.stringify(errObj) },
+                ],
+            };
     }
-    const structuredContent = {
-        success: false,
-        error: {
-            name: "UnknownError",
-            message: "An unknown error occurred",
-            details: error,
-        },
-    };
-    return {
-        content: [],
-        isError: true,
-        structuredContent,
+    const errObj = {
+        name: "UnknownError",
+        message: "An unknown error occurred",
+        details: error,
     };
+    return useStructuredContent
+        ? { isError: true, content: [], structuredContent: errObj }
+        : {
+            isError: true,
+            content: [
+                { type: "text", text: JSON.stringify(errObj) },
+            ],
+        };
 }
 //# sourceMappingURL=tool-response.js.map

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

@@ -7,6 +7,11 @@ export declare class YoutrackClient {
     private readonly usersByLogin;
     private readonly projectsByShortName;
     constructor(config: YoutrackConfig);
+    /**
+     * GET helper that prefers `$top`/`$skip` and retries with `top`/`skip` on 400.
+     * Returns only `data` for convenience.
+     */
+    private getWithFlexibleTop;
     /**
      * Process items with concurrency limit using MutexPool
      * @param items - Array of items to process
@@ -22,7 +27,7 @@ export declare class YoutrackClient {
     getProjectByShortName(shortName: string): Promise<YoutrackProject | null>;
     private getProjectById;
     getIssue(issueId: string): Promise<IssueLookupPayload>;
-    getIssueDetails(issueId: string): Promise<IssueDetailsPayload>;
+    getIssueDetails(issueId: string, includeCustomFields?: boolean): Promise<IssueDetailsPayload>;
     getIssueComments(issueId: string): Promise<IssueCommentsPayload>;
     createIssueComment(input: IssueCommentCreateInput): Promise<{
         comment: MappedYoutrackIssueComment;
@@ -37,7 +42,7 @@ export declare class YoutrackClient {
     updateIssue(input: YoutrackIssueUpdateInput): Promise<IssueLookupPayload>;
     assignIssue(input: YoutrackIssueAssignInput): Promise<IssueLookupPayload>;
     getIssues(issueIds: string[]): Promise<IssuesLookupPayload>;
-    getIssuesDetails(issueIds: string[]): Promise<IssuesDetailsPayload>;
+    getIssuesDetails(issueIds: string[], includeCustomFields?: boolean): Promise<IssuesDetailsPayload>;
     /**
      * Light version of getIssuesDetails() that fetches only minimal fields (id, idReadable, updated, updater)
      * Used for filtering in user_activity mode to reduce payload size

package/dist/src/youtrack-client.js

@@ -100,6 +100,47 @@ export class YoutrackClient {
             throw normalized;
         });
     }
+    /**
+     * GET helper that prefers `$top`/`$skip` and retries with `top`/`skip` on 400.
+     * Returns only `data` for convenience.
+     */
+    async getWithFlexibleTop(url, params) {
+        const hasTopLike = Object.prototype.hasOwnProperty.call(params, "$top") ||
+            Object.prototype.hasOwnProperty.call(params, "top") ||
+            Object.prototype.hasOwnProperty.call(params, "$skip") ||
+            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, "skip") && !Object.prototype.hasOwnProperty.call(dollarParams, "$skip")) {
+            (dollarParams).$skip = (dollarParams).skip;
+            delete (dollarParams).skip;
+        }
+        try {
+            const res = await this.http.get(url, { params: dollarParams });
+            return res.data;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error) && error.response?.status === 400 && hasTopLike) {
+                // Retry with plain top/skip
+                const plainParams = { ...params };
+                if (Object.prototype.hasOwnProperty.call(plainParams, "$top")) {
+                    (plainParams).top = (plainParams).$top;
+                    delete (plainParams).$top;
+                }
+                if (Object.prototype.hasOwnProperty.call(plainParams, "$skip")) {
+                    (plainParams).skip = (plainParams).$skip;
+                    delete (plainParams).$skip;
+                }
+                const res2 = await this.http.get(url, { params: plainParams });
+                return res2.data;
+            }
+            throw error;
+        }
+    }
     /**
      * Process items with concurrency limit using MutexPool
      * @param items - Array of items to process
@@ -179,18 +220,28 @@ export class YoutrackClient {
     }
     async listProjects() {
         try {
-            const response = await this.http.get("/api/admin/projects", {
-                params: {
-                    fields: defaultFields.projects,
-                    top: DEFAULT_PAGE_SIZE,
-                },
-            });
-            response.data.forEach((project) => {
+            const projects = [];
+            let skip = 0;
+            // Paginate until a page returns less than DEFAULT_PAGE_SIZE
+            while (skip >= 0) {
+                const page = await this.http.get("/api/admin/projects", {
+                    params: {
+                        fields: defaultFields.projects,
+                        top: DEFAULT_PAGE_SIZE,
+                        skip,
+                    },
+                });
+                projects.push(...page.data);
+                if (page.data.length < DEFAULT_PAGE_SIZE)
+                    break;
+                skip += page.data.length;
+            }
+            projects.forEach((project) => {
                 if (project.shortName) {
                     this.projectsByShortName.set(project.shortName, project);
                 }
             });
-            const payload = { projects: response.data };
+            const payload = { projects };
             return payload;
         }
         catch (error) {
@@ -231,10 +282,13 @@ export class YoutrackClient {
             throw this.normalizeError(error);
         }
     }
-    async getIssueDetails(issueId) {
+    async getIssueDetails(issueId, includeCustomFields = false) {
         try {
+            const fields = includeCustomFields
+                ? `${defaultFields.issueDetails},customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation))`
+                : defaultFields.issueDetails;
             const response = await this.http.get(`/api/issues/${issueId}`, {
-                params: { fields: defaultFields.issueDetails },
+                params: { fields },
             });
             const mappedIssue = mapIssueDetails(response.data);
             const payload = { issue: mappedIssue };
@@ -412,14 +466,11 @@ export class YoutrackClient {
         // Build query: "issue id: BC-123 BC-124 BC-125"
         const query = `issue id: ${issueIds.join(" ")}`;
         try {
-            const response = await this.http.get("/api/issues", {
-                params: {
-                    fields: defaultFields.issue,
-                    query,
-                    $top: issueIds.length,
-                },
+            const foundIssues = await this.getWithFlexibleTop("/api/issues", {
+                fields: defaultFields.issue,
+                query,
+                $top: issueIds.length,
             });
-            const foundIssues = response.data;
             const foundIds = new Set(foundIssues.map((issue) => issue.idReadable));
             const errors = [];
             // Find issues that were not returned
@@ -441,21 +492,21 @@ export class YoutrackClient {
             throw this.normalizeError(error);
         }
     }
-    async getIssuesDetails(issueIds) {
+    async getIssuesDetails(issueIds, includeCustomFields = false) {
         if (!issueIds.length) {
             return { issues: [], errors: [] };
         }
         // Build query: "issue id: BC-123 BC-124 BC-125"
         const query = `issue id: ${issueIds.join(" ")}`;
         try {
-            const response = await this.http.get("/api/issues", {
-                params: {
-                    fields: defaultFields.issueDetails,
-                    query,
-                    $top: issueIds.length,
-                },
+            const fields = includeCustomFields
+                ? `${defaultFields.issueDetails},customFields(id,name,value(id,name,presentation),$type,possibleEvents(id,presentation))`
+                : defaultFields.issueDetails;
+            const foundIssues = await this.getWithFlexibleTop("/api/issues", {
+                fields,
+                query,
+                $top: issueIds.length,
             });
-            const foundIssues = response.data;
             const foundIds = new Set(foundIssues.map((issue) => issue.idReadable));
             const errors = [];
             // Find issues that were not returned
@@ -488,14 +539,11 @@ export class YoutrackClient {
         // Build query: "issue id: BC-123 BC-124 BC-125"
         const query = `issue id: ${issueIds.join(" ")}`;
         try {
-            const response = await this.http.get("/api/issues", {
-                params: {
-                    fields: defaultFields.issueDetailsLight,
-                    query,
-                    $top: issueIds.length,
-                },
+            return await this.getWithFlexibleTop("/api/issues", {
+                fields: defaultFields.issueDetailsLight,
+                query,
+                $top: issueIds.length,
             });
-            return response.data;
         }
         catch (error) {
             throw this.normalizeError(error);
@@ -597,23 +645,21 @@ export class YoutrackClient {
         const skip = input.skip ?? 0;
         const briefOutput = input.briefOutput ?? true;
         try {
-            const response = await this.http.get("/api/issues", {
-                params: {
-                    fields: briefOutput ? defaultFields.issueSearchBrief : defaultFields.issueSearch,
-                    query,
-                    $top: Math.min(limit, DEFAULT_PAGE_SIZE),
-                    $skip: skip,
-                },
+            const page = await this.getWithFlexibleTop("/api/issues", {
+                fields: briefOutput ? defaultFields.issueSearchBrief : defaultFields.issueSearch,
+                query,
+                $top: Math.min(limit, DEFAULT_PAGE_SIZE),
+                $skip: skip,
             });
             return {
-                issues: briefOutput ? response.data.map(mapIssueBrief) : response.data.map(mapIssue),
+                issues: briefOutput ? page.map(mapIssueBrief) : page.map(mapIssue),
                 userLogins: input.userLogins,
                 period: {
                     startDate: input.startDate ? toIsoDateString(input.startDate) : undefined,
                     endDate: input.endDate ? toIsoDateString(input.endDate) : undefined,
                 },
                 pagination: {
-                    returned: response.data.length,
+                    returned: page.length,
                     limit,
                     skip,
                 },
@@ -641,16 +687,13 @@ export class YoutrackClient {
         // Get candidate issues (use brief fields to reduce payload)
         try {
             // Fetch candidates by date only (no user filters) to ensure parser compatibility
-            const response = await this.http.get("/api/issues", {
-                params: {
-                    fields: briefOutput ? defaultFields.issueSearchBrief : defaultFields.issueSearch,
-                    query, // use full query with date filter and sorting
-                    $top: DEFAULT_PAGE_SIZE,
-                },
+            const candidateIssues = await this.getWithFlexibleTop("/api/issues", {
+                fields: briefOutput ? defaultFields.issueSearchBrief : defaultFields.issueSearch,
+                query,
+                $top: DEFAULT_PAGE_SIZE,
             });
             // If no data returned, still attempt a fallback without braces
             // No fallback needed here since we purposely avoided user filters in query
-            const candidateIssues = response.data;
             if (candidateIssues.length === 0) {
                 return {
                     issues: [],
@@ -754,9 +797,8 @@ export class YoutrackClient {
                         },
                     };
                 }
-                catch (fallbackError) {
-                    // If fallback also fails, log for debugging and return original error
-                    console.error("Fallback query also failed:", fallbackError);
+                catch {
+                    // If fallback also fails, return original error
                     throw normalized;
                 }
             }

package/package.json

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