@levinariy.fedorov/youtrack-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Levinariy Fedorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @levinariy.fedorov/youtrack-mcp
+
+MCP-сервер для YouTrack — и та же самая библиотека для тех, кому протокол не нужен.
+
+Модели инструменты нужны через MCP: другого способа их звать у неё нет. Приложению
+на том же языке протокол только мешает — оно импортирует функции напрямую. Поэтому
+здесь одно ядро и две обёртки над ним, а не сервер, к которому все ходят по stdio.
+
+Написан под YouTrack без встроенного MCP: в 2025.3 и новее JetBrains даёт удалённый
+MCP-сервер прямо в продукте, и если он у вас есть — начните с него.
+
+## Подключение
+
+```json
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "npx",
+      "args": ["-y", "@levinariy.fedorov/youtrack-mcp@0.1.0"]
+    }
+  }
+}
+```
+
+Версию лучше указывать: сервер запускается при каждом старте сессии, и «свежайшая»
+здесь означает «неизвестно какая».
+
+## Вход
+
+Токен — постоянный токен YouTrack из профиля пользователя. Принимается только
+потоком: в аргументе он осел бы в истории оболочки и был бы виден в списке процессов.
+
+```powershell
+"<токен>" | npx @levinariy.fedorov/youtrack-mcp login --base-url https://youtrack.example.com --token-stdin
+npx @levinariy.fedorov/youtrack-mcp status
+npx @levinariy.fedorov/youtrack-mcp profiles
+```
+
+Профилей может быть несколько — например, своя учётка и сервисная. Профиль
+выбирается **параметром вызова**, а не переключателем: запись нового профиля не
+делает его основным, поэтому завести бота, не превратившись в него, безопасно.
+
+Учётки лежат в `%APPDATA%\youtrack-mcp\config.json` (на прочих системах — XDG).
+Путь переопределяется переменной `YOUTRACK_MCP_CONFIG`. Переменные `YOUTRACK_URL`
+и `YOUTRACK_TOKEN` перебивают файл — для CI и разовых запусков.
+
+## Инструменты
+
+| Инструмент | Что делает |
+| --- | --- |
+| `read_issue` | Задача целиком: поля, комментарии, вложения, связи — одним вызовом |
+| `search_issues` | Поиск запросом YouTrack; только идентификатор, тема и поля |
+| `whoami` | Учётная запись, от имени которой идут вызовы |
+
+Ответы структурированные: у каждого инструмента объявлен `outputSchema`, и
+вызывающий получает объект, а не JSON внутри текста.
+
+`read_issue` отдаёт поля плоской картой (`fields["Type"]`), у комментария —
+булево `public` вместо разбора видимости, у вложения — комментарий, к которому оно
+приложено. Даты приходят датами: у YouTrack они лежат миллисекундами эпохи и от
+обычного целого неотличимы, поэтому тип поля запрашивается вместе со значением.
+С `attachments: true` файлы скачиваются на диск и получают `path`: содержимое в
+ответ не попадает, читать файл — отдельный шаг.
+
+Пустые поля не отдаются: «поля нет» и «поле не заполнено» для читающего одно и то
+же, а два десятка пустых строк в каждом ответе — потраченный впустую контекст.
+
+Инструментов чтения конфигурации нет и не будет: токен не должен попадать в
+контекст модели.
+
+## Библиотека
+
+```ts
+import { readIssue, resolveCredentials, YouTrackClient } from "@levinariy.fedorov/youtrack-mcp"
+
+const { credentials } = await resolveCredentials()
+const issue = await readIssue(new YouTrackClient(credentials), "PROJ-1234")
+```
+
+## Разработка
+
+```powershell
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+Собранный `dist` в репозитории не хранится: его делает `prepare` — при публикации
+и при установке пакета из git.
+
+## Лицензия
+
+MIT.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseArgs } from "node:util";
+import { YouTrackClient } from "./client.js";
+import { AuthError, configPath, listProfiles, resolveCredentials, saveProfile, setDefaultProfile } from "./config.js";
+import { me } from "./issues.js";
+import { createServer } from "./server.js";
+const USAGE = `youtrack-mcp — MCP-сервер для YouTrack.
+
+  youtrack-mcp                     запустить сервер (stdio)
+  youtrack-mcp login               сохранить учётку
+  youtrack-mcp status              проверить, кто мы в YouTrack
+  youtrack-mcp profiles            перечислить профили
+
+Ключи login:
+  --base-url <URL>    адрес YouTrack
+  --token-stdin       прочитать токен из stdin
+  --profile <имя>     профиль (по умолчанию default)
+  --set-default       сделать профиль основным
+`;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function login(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            "base-url": { type: "string" },
+            "token-stdin": { type: "boolean", default: false },
+            profile: { type: "string", default: "default" },
+            "set-default": { type: "boolean", default: false }
+        }
+    });
+    const baseUrl = values["base-url"]?.trim();
+    if (!baseUrl)
+        throw new AuthError("Нужен --base-url: адрес YouTrack.");
+    // Токен принимаем только потоком: в аргументе он осядет в истории оболочки и
+    // будет виден в списке процессов.
+    if (!values["token-stdin"])
+        throw new AuthError("Токен передаётся через --token-stdin, аргументом — никогда.");
+    const token = await readStdin();
+    if (token === "")
+        throw new AuthError("Пустой токен.");
+    const profile = values.profile ?? "default";
+    await saveProfile(profile, { baseUrl, token });
+    if (values["set-default"])
+        await setDefaultProfile(profile);
+    const { credentials } = await resolveCredentials(profile);
+    const user = await me(new YouTrackClient(credentials));
+    process.stdout.write(`Профиль «${profile}» сохранён: ${user.name} (${user.login}) на ${baseUrl}\n`);
+}
+async function status() {
+    const { profile, credentials } = await resolveCredentials();
+    const user = await me(new YouTrackClient(credentials));
+    process.stdout.write(`${user.name} (${user.login})\nПрофиль: ${profile}\nURL: ${credentials.baseUrl}\n`);
+}
+async function profiles() {
+    const list = await listProfiles();
+    if (list.length === 0) {
+        process.stdout.write(`Профилей нет. Конфигурация: ${configPath()}\n`);
+        return;
+    }
+    for (const item of list) {
+        process.stdout.write(`${item.isDefault ? "*" : " "} ${item.name}\t${item.baseUrl}\n`);
+    }
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case undefined:
+            // Ни одного аргумента — значит нас запустил MCP-клиент: говорим по stdio
+            // и ничего не печатаем в stdout, там протокол.
+            await createServer().connect(new StdioServerTransport());
+            break;
+        case "login":
+            await login(rest);
+            break;
+        case "status":
+            await status();
+            break;
+        case "profiles":
+            await profiles();
+            break;
+        case "--help":
+        case "-h":
+        case "help":
+            process.stdout.write(USAGE);
+            break;
+        default:
+            process.stderr.write(`Неизвестная команда ${command}.\n\n${USAGE}`);
+            process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { type Credentials } from "./config.js";
+/** Ошибка со стороны YouTrack: несёт код ответа, чтобы вызывающий не разбирал текст. */
+export declare class YouTrackError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+type Query = Record<string, string | number | undefined>;
+export declare class YouTrackClient {
+    private readonly credentials;
+    constructor(credentials: Credentials);
+    get baseUrl(): string;
+    request<T>(method: string, apiPath: string, options?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
+    get<T>(apiPath: string, query?: Query): Promise<T>;
+    post<T>(apiPath: string, body: unknown, query?: Query): Promise<T>;
+    /**
+     * Скачивает вложение по ссылке из поля `url`.
+     *
+     * Ссылка приходит относительной и уже подписанной: собрать её самостоятельно
+     * нельзя, поэтому путь и параметры уходят в запрос как есть.
+     */
+    download(relativeUrl: string, directory: string, fileName: string): Promise<string>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,91 @@
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { AuthError } from "./config.js";
+const REQUEST_TIMEOUT_MS = 30_000;
+/** Вложение может весить десятки мегабайт и в общий лимит не укладывается. */
+const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** Ошибка со стороны YouTrack: несёт код ответа, чтобы вызывающий не разбирал текст. */
+export class YouTrackError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "YouTrackError";
+    }
+}
+function describe(status, body) {
+    try {
+        const parsed = JSON.parse(body);
+        const text = parsed.error_description ?? parsed.error;
+        if (text)
+            return text;
+    }
+    catch {
+        // YouTrack отвечает и просто текстом — тогда берём его как есть.
+    }
+    return body.trim().slice(0, 500) || `HTTP ${status}`;
+}
+export class YouTrackClient {
+    credentials;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    get baseUrl() {
+        return this.credentials.baseUrl;
+    }
+    async request(method, apiPath, options = {}) {
+        const url = new URL(apiPath.replace(/^\//, ""), `${this.credentials.baseUrl}/`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.credentials.token}`,
+                Accept: "application/json",
+                ...(options.body === undefined ? {} : { "Content-Type": "application/json" })
+            },
+            ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new AuthError(`YouTrack не принял токен (${response.status}). Он отозван или истёк — заведите новый и выполните: youtrack-mcp login --base-url ${this.credentials.baseUrl} --token-stdin`);
+        }
+        const text = await response.text();
+        if (!response.ok)
+            throw new YouTrackError(describe(response.status, text), response.status);
+        if (text.trim() === "")
+            return undefined;
+        return JSON.parse(text);
+    }
+    get(apiPath, query) {
+        return this.request("GET", apiPath, query === undefined ? {} : { query });
+    }
+    post(apiPath, body, query) {
+        return this.request("POST", apiPath, query === undefined ? { body } : { body, query });
+    }
+    /**
+     * Скачивает вложение по ссылке из поля `url`.
+     *
+     * Ссылка приходит относительной и уже подписанной: собрать её самостоятельно
+     * нельзя, поэтому путь и параметры уходят в запрос как есть.
+     */
+    async download(relativeUrl, directory, fileName) {
+        const url = new URL(relativeUrl, `${this.credentials.baseUrl}/`);
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.credentials.token}` },
+            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)
+        });
+        if (!response.ok || !response.body) {
+            throw new YouTrackError(`Не удалось скачать вложение ${fileName} (HTTP ${response.status}).`, response.status);
+        }
+        await mkdir(directory, { recursive: true });
+        const target = path.join(directory, fileName);
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(target));
+        return target;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * Учётные данные одного профиля.
+ *
+ * Профилей несколько не ради «мультиаккаунта», а потому что писать в YouTrack
+ * приходится от двух лиц: от себя и от сервисной учётки. Выбор — всегда
+ * параметр вызова, поэтому активный профиль здесь означает лишь «кого взять,
+ * если не сказано иное», и записью нового профиля не меняется.
+ */
+export interface Credentials {
+    baseUrl: string;
+    token: string;
+}
+declare const ConfigSchema: z.ZodObject<{
+    defaultProfile: z.ZodDefault<z.ZodString>;
+    profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        baseUrl: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+/** Профиль без секрета: всё, что можно показывать наружу. */
+export interface ProfileInfo {
+    name: string;
+    baseUrl: string;
+    isDefault: boolean;
+}
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Путь к конфигурации.
+ *
+ * На Windows — `%APPDATA%`, потому что там место пользовательских настроек;
+ * на остальных системах — XDG. `YOUTRACK_MCP_CONFIG` перебивает обе ветки:
+ * это нужно тестам и запуску нескольких окружений рядом.
+ */
+export declare function configPath(): string;
+export declare function readConfig(): Promise<Config>;
+/**
+ * Сохраняет профиль.
+ *
+ * Активный профиль намеренно не трогает: заведение сервисной учётки не должно
+ * даже на секунду превращать в неё все остальные сессии.
+ */
+export declare function saveProfile(name: string, credentials: Credentials): Promise<void>;
+export declare function setDefaultProfile(name: string): Promise<void>;
+export declare function removeProfile(name: string): Promise<void>;
+export declare function listProfiles(): Promise<ProfileInfo[]>;
+/**
+ * Находит учётку для вызова: переменные среды, затем файл.
+ *
+ * Переменные перебивают файл целиком и только для профиля по умолчанию: они
+ * задают одно окружение на процесс, и смешивать их с именованным профилем
+ * значило бы писать от неизвестно чьего имени.
+ */
+export declare function resolveCredentials(profile?: string): Promise<{
+    profile: string;
+    credentials: Credentials;
+}>;
+export {};

package/dist/config.js

@@ -0,0 +1,122 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+const CredentialsSchema = z.object({
+    baseUrl: z.string().min(1),
+    token: z.string().min(1)
+});
+const ConfigSchema = z.object({
+    defaultProfile: z.string().default("default"),
+    profiles: z.record(z.string(), CredentialsSchema).default({})
+});
+export class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+/**
+ * Путь к конфигурации.
+ *
+ * На Windows — `%APPDATA%`, потому что там место пользовательских настроек;
+ * на остальных системах — XDG. `YOUTRACK_MCP_CONFIG` перебивает обе ветки:
+ * это нужно тестам и запуску нескольких окружений рядом.
+ */
+export function configPath() {
+    const override = process.env.YOUTRACK_MCP_CONFIG?.trim();
+    if (override)
+        return override;
+    if (process.platform === "win32" && process.env.APPDATA) {
+        return path.join(process.env.APPDATA, "youtrack-mcp", "config.json");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg && xdg !== "" ? xdg : path.join(os.homedir(), ".config");
+    return path.join(base, "youtrack-mcp", "config.json");
+}
+const EMPTY = { defaultProfile: "default", profiles: {} };
+export async function readConfig() {
+    let raw;
+    try {
+        raw = await readFile(configPath(), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ...EMPTY };
+        throw error;
+    }
+    if (raw.trim() === "")
+        return { ...EMPTY };
+    const parsed = ConfigSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+        throw new AuthError(`Конфигурация ${configPath()} испорчена: ${parsed.error.issues[0]?.message ?? "неизвестная ошибка"}.`);
+    }
+    return parsed.data;
+}
+async function writeConfig(config) {
+    const file = configPath();
+    await mkdir(path.dirname(file), { recursive: true });
+    // mode 0600 — осмысленно на POSIX; на Windows файл всё равно доступен любому
+    // процессу пользователя, и притворяться, что это защита, не стоит.
+    await writeFile(file, `${JSON.stringify(config, null, "\t")}\n`, { encoding: "utf8", mode: 0o600 });
+}
+/**
+ * Сохраняет профиль.
+ *
+ * Активный профиль намеренно не трогает: заведение сервисной учётки не должно
+ * даже на секунду превращать в неё все остальные сессии.
+ */
+export async function saveProfile(name, credentials) {
+    const config = await readConfig();
+    const parsed = CredentialsSchema.parse({
+        baseUrl: credentials.baseUrl.trim().replace(/\/+$/, ""),
+        token: credentials.token.trim()
+    });
+    config.profiles[name] = parsed;
+    await writeConfig(config);
+}
+export async function setDefaultProfile(name) {
+    const config = await readConfig();
+    if (!config.profiles[name])
+        throw new AuthError(`Профиля «${name}» нет в конфигурации.`);
+    config.defaultProfile = name;
+    await writeConfig(config);
+}
+export async function removeProfile(name) {
+    const config = await readConfig();
+    delete config.profiles[name];
+    await writeConfig(config);
+}
+export async function listProfiles() {
+    const config = await readConfig();
+    return Object.entries(config.profiles).map(([name, credentials]) => ({
+        name,
+        baseUrl: credentials.baseUrl,
+        isDefault: name === config.defaultProfile
+    }));
+}
+/**
+ * Находит учётку для вызова: переменные среды, затем файл.
+ *
+ * Переменные перебивают файл целиком и только для профиля по умолчанию: они
+ * задают одно окружение на процесс, и смешивать их с именованным профилем
+ * значило бы писать от неизвестно чьего имени.
+ */
+export async function resolveCredentials(profile) {
+    const envUrl = process.env.YOUTRACK_URL?.trim();
+    const envToken = process.env.YOUTRACK_TOKEN?.trim();
+    if (!profile && envUrl && envToken) {
+        return { profile: "env", credentials: { baseUrl: envUrl.replace(/\/+$/, ""), token: envToken } };
+    }
+    const config = await readConfig();
+    const name = profile ?? config.defaultProfile;
+    const credentials = config.profiles[name];
+    if (!credentials) {
+        const known = Object.keys(config.profiles);
+        const hint = known.length > 0
+            ? `Известные профили: ${known.join(", ")}.`
+            : `Ни одного профиля нет. Войдите: youtrack-mcp login --base-url <URL> --token-stdin`;
+        throw new AuthError(`Профиля «${name}» нет в ${configPath()}. ${hint}`);
+    }
+    return { profile: name, credentials };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Библиотека YouTrack: то же самое, что делает MCP-сервер, но вызовом функции.
+ *
+ * Приложению протокол не нужен — оно на том же языке, поэтому ходит сюда
+ * напрямую, а MCP остаётся тем, чем и был: способом дать инструменты модели.
+ */
+export { YouTrackClient, YouTrackError } from "./client.js";
+export { AuthError, configPath, listProfiles, readConfig, removeProfile, resolveCredentials, saveProfile, setDefaultProfile } from "./config.js";
+export type { Config, Credentials, ProfileInfo } from "./config.js";
+export { me, readIssue, searchIssues } from "./issues.js";
+export type { Attachment, Comment, Found, Issue, Link, Person, ReadOptions } from "./issues.js";
+export { createServer } from "./server.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Библиотека YouTrack: то же самое, что делает MCP-сервер, но вызовом функции.
+ *
+ * Приложению протокол не нужен — оно на том же языке, поэтому ходит сюда
+ * напрямую, а MCP остаётся тем, чем и был: способом дать инструменты модели.
+ */
+export { YouTrackClient, YouTrackError } from "./client.js";
+export { AuthError, configPath, listProfiles, readConfig, removeProfile, resolveCredentials, saveProfile, setDefaultProfile } from "./config.js";
+export { me, readIssue, searchIssues } from "./issues.js";
+export { createServer } from "./server.js";

package/dist/issues.d.ts

@@ -0,0 +1,63 @@
+import type { YouTrackClient } from "./client.js";
+export type Person = {
+    login: string;
+    name: string;
+};
+export type Comment = {
+    id: string;
+    author: Person;
+    created: string;
+    text: string;
+    /** Виден заказчику. Внутренняя заметка ответом заказчику не считается. */
+    public: boolean;
+};
+export type Attachment = {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    /** Комментарий, к которому приложен файл, либо null — если к самой задаче. */
+    commentId: string | null;
+    /** Путь на диске. Появляется, только если файлы просили скачать. */
+    path?: string;
+};
+export type Link = {
+    /** Как связь читается со стороны этой задачи: «duplicates», «relates to». */
+    type: string;
+    issues: {
+        id: string;
+        summary: string;
+    }[];
+};
+export type Issue = {
+    id: string;
+    summary: string;
+    description: string;
+    url: string;
+    project: string;
+    reporter: Person;
+    created: string;
+    updated: string;
+    resolved: string | null;
+    /** Значения полей задачи по именам: Type, State, Business solution, Priority. */
+    fields: Record<string, string>;
+    comments: Comment[];
+    attachments: Attachment[];
+    links: Link[];
+};
+export type ReadOptions = {
+    /** Скачать вложения на диск и проставить им `path`. */
+    downloadAttachments?: boolean;
+    /** Куда складывать файлы. По умолчанию — подкаталог задачи во временном каталоге. */
+    directory?: string;
+};
+export declare function readIssue(client: YouTrackClient, id: string, options?: ReadOptions): Promise<Issue>;
+export type Found = {
+    id: string;
+    summary: string;
+    fields: Record<string, string>;
+};
+export declare function searchIssues(client: YouTrackClient, query: string, limit?: number): Promise<Found[]>;
+export declare function me(client: YouTrackClient): Promise<Person & {
+    email: string;
+}>;

package/dist/issues.js

@@ -0,0 +1,144 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Поля, которые запрашиваются у YouTrack.
+ *
+ * Держатся здесь, а не в промпте скилла: забытое поле не ломает вызов, а тихо
+ * отдаёт пустоту, и заметно это становится на живой задаче.
+ */
+const ISSUE_FIELDS = [
+    "idReadable",
+    "summary",
+    "description",
+    "created",
+    "updated",
+    "resolved",
+    "project(shortName,name)",
+    "reporter(login,fullName)",
+    // Тип поля спрашивается вместе со значением: у даты значение приезжает голым
+    // числом, и без типа её не отличить от обычного целого.
+    "customFields(name,projectCustomField(field(fieldType(id))),value(name,login,fullName,presentation,text,minutes))",
+    "comments(id,created,text,author(login,fullName),visibility($type))",
+    "attachments(id,name,size,mimeType,url,comment(id))",
+    "links(direction,linkType(name,sourceToTarget,targetToSource),issues(idReadable,summary))"
+].join(",");
+const SEARCH_FIELDS = "idReadable,summary,customFields(name,projectCustomField(field(fieldType(id))),value(name,login,fullName,presentation,text,minutes))";
+function person(raw) {
+    return { login: raw?.login ?? "", name: raw?.fullName ?? raw?.login ?? "" };
+}
+function moment(value) {
+    return value ? new Date(value).toISOString() : null;
+}
+/**
+ * Приводит значение поля к строке.
+ *
+ * У YouTrack `value` бывает объектом, массивом, строкой и числом в зависимости
+ * от типа поля — разбирать это на каждом вызове не должен никто, кроме этого
+ * места.
+ */
+function fieldValue(value, fieldType) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        // Дата приезжает миллисекундами эпохи. Отдавать её так наружу — значит
+        // заставить читающего гадать, срок это или количество.
+        if (fieldType === "date")
+            return new Date(value).toISOString().slice(0, 10);
+        if (fieldType === "date and time")
+            return new Date(value).toISOString();
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => fieldValue(item, fieldType))
+            .filter(Boolean)
+            .join(", ");
+    }
+    const raw = value;
+    return raw.name ?? raw.fullName ?? raw.login ?? raw.presentation ?? raw.text ?? (raw.minutes === undefined ? "" : String(raw.minutes));
+}
+/**
+ * Собирает поля задачи в плоскую карту.
+ *
+ * Пустые не кладёт: «поля нет» и «поле не заполнено» для читающего одно и то же,
+ * а два десятка пустых строк в каждом ответе — это чужой контекст, потраченный
+ * впустую.
+ */
+function collectFields(raw) {
+    const fields = {};
+    for (const field of raw.customFields ?? []) {
+        if (!field.name)
+            continue;
+        const value = fieldValue(field.value, field.projectCustomField?.field?.fieldType?.id);
+        if (value !== "")
+            fields[field.name] = value;
+    }
+    return fields;
+}
+function toIssue(raw, baseUrl) {
+    const id = raw.idReadable ?? "";
+    return {
+        id,
+        summary: raw.summary ?? "",
+        description: raw.description ?? "",
+        url: `${baseUrl}/issue/${id}`,
+        project: raw.project?.name ?? raw.project?.shortName ?? "",
+        reporter: person(raw.reporter),
+        created: moment(raw.created) ?? "",
+        updated: moment(raw.updated) ?? "",
+        resolved: moment(raw.resolved),
+        fields: collectFields(raw),
+        comments: (raw.comments ?? []).map((comment) => ({
+            id: comment.id ?? "",
+            author: person(comment.author),
+            created: moment(comment.created) ?? "",
+            text: comment.text ?? "",
+            // Ограниченная видимость — внутренняя заметка. Отсутствие поля значит,
+            // что комментарий видят все, включая заказчика.
+            public: comment.visibility?.$type !== "IssueCommentVisibility" && comment.visibility?.$type !== "LimitedVisibility"
+        })),
+        attachments: (raw.attachments ?? []).map((attachment) => ({
+            id: attachment.id ?? "",
+            name: attachment.name ?? "",
+            mimeType: attachment.mimeType ?? "",
+            size: attachment.size ?? 0,
+            commentId: attachment.comment?.id ?? null
+        })),
+        links: (raw.links ?? [])
+            .filter((link) => (link.issues ?? []).length > 0)
+            .map((link) => ({
+            type: (link.direction === "INWARD" ? link.linkType?.targetToSource : link.linkType?.sourceToTarget) ??
+                link.linkType?.name ??
+                "",
+            issues: (link.issues ?? []).map((issue) => ({ id: issue.idReadable ?? "", summary: issue.summary ?? "" }))
+        }))
+    };
+}
+export async function readIssue(client, id, options = {}) {
+    const raw = await client.get(`/api/issues/${encodeURIComponent(id)}`, { fields: ISSUE_FIELDS });
+    const issue = toIssue(raw, client.baseUrl);
+    if (!options.downloadAttachments || issue.attachments.length === 0)
+        return issue;
+    const directory = options.directory ?? path.join(os.tmpdir(), "youtrack", issue.id);
+    const urls = new Map((raw.attachments ?? []).map((attachment) => [attachment.id ?? "", attachment.url ?? ""]));
+    // Последовательно: вложения бывают крупными, и параллельная загрузка десятка
+    // файлов упирается не в нас, а в YouTrack.
+    for (const attachment of issue.attachments) {
+        const url = urls.get(attachment.id);
+        if (url)
+            attachment.path = await client.download(url, directory, attachment.name);
+    }
+    return issue;
+}
+export async function searchIssues(client, query, limit = 50) {
+    const raw = await client.get("/api/issues", { query, $top: limit, fields: SEARCH_FIELDS });
+    return raw.map((issue) => {
+        return { id: issue.idReadable ?? "", summary: issue.summary ?? "", fields: collectFields(issue) };
+    });
+}
+export async function me(client) {
+    const raw = await client.get("/api/users/me", { fields: "login,fullName,email" });
+    return { ...person(raw), email: raw.email ?? "" };
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,101 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { YouTrackClient } from "./client.js";
+import { resolveCredentials } from "./config.js";
+import { me, readIssue, searchIssues } from "./issues.js";
+/**
+ * Клиенты живут по имени профиля: конфигурацию незачем перечитывать на каждый
+ * вызов, а профилей всё равно единицы.
+ */
+const clients = new Map();
+async function clientFor(profile) {
+    const resolved = await resolveCredentials(profile);
+    const cached = clients.get(resolved.profile);
+    if (cached)
+        return cached;
+    const client = new YouTrackClient(resolved.credentials);
+    clients.set(resolved.profile, client);
+    return client;
+}
+const profileArg = z
+    .string()
+    .optional()
+    .describe("Профиль учётной записи. Не указан — работа идёт от вашего имени; сервисная учётка задаётся здесь и только на время одного вызова.");
+const PersonSchema = z.object({ login: z.string(), name: z.string() });
+const IssueSchema = z.object({
+    id: z.string(),
+    summary: z.string(),
+    description: z.string(),
+    url: z.string(),
+    project: z.string(),
+    reporter: PersonSchema,
+    created: z.string(),
+    updated: z.string(),
+    resolved: z.string().nullable(),
+    fields: z.record(z.string(), z.string()),
+    comments: z.array(z.object({
+        id: z.string(),
+        author: PersonSchema,
+        created: z.string(),
+        text: z.string(),
+        public: z.boolean()
+    })),
+    attachments: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        mimeType: z.string(),
+        size: z.number(),
+        commentId: z.string().nullable(),
+        path: z.string().optional()
+    })),
+    links: z.array(z.object({ type: z.string(), issues: z.array(z.object({ id: z.string(), summary: z.string() })) }))
+});
+export function createServer() {
+    const server = new McpServer({ name: "youtrack", version: "0.1.0" });
+    server.registerTool("read_issue", {
+        title: "Прочитать задачу",
+        description: "Задача целиком: поля, описание, комментарии и вложения одним вызовом. " +
+            "Конкретика — номера, даты, периоды — обычно живёт в комментариях и вложениях, а не в описании, " +
+            "поэтому отдельного вызова за ними не нужно. " +
+            "У комментария `public` означает, что его видит заказчик: внутренняя заметка ответом заказчику не считается. " +
+            "С `attachments: true` файлы скачиваются на диск, и у каждого появляется `path` — содержимое читается оттуда, в ответ оно не попадает.",
+        inputSchema: {
+            id: z.string().describe("Идентификатор задачи, например PROJ-1234"),
+            attachments: z.boolean().default(false).describe("Скачать вложения на диск"),
+            profile: profileArg
+        },
+        outputSchema: IssueSchema.shape,
+        annotations: { readOnlyHint: true, openWorldHint: true }
+    }, async ({ id, attachments, profile }) => {
+        const issue = await readIssue(await clientFor(profile), id, { downloadAttachments: attachments });
+        return { content: [{ type: "text", text: `${issue.id}: ${issue.summary}` }], structuredContent: issue };
+    });
+    server.registerTool("search_issues", {
+        title: "Найти задачи",
+        description: "Поиск запросом YouTrack, например `project: PROJ State: Open Assignee: me`. " +
+            "Возвращает только идентификатор, тему и поля — за подробностями по конкретной задаче идите в read_issue.",
+        inputSchema: {
+            query: z.string().describe("Поисковый запрос YouTrack"),
+            limit: z.number().int().min(1).max(200).default(50).describe("Сколько задач вернуть"),
+            profile: profileArg
+        },
+        outputSchema: {
+            issues: z.array(z.object({ id: z.string(), summary: z.string(), fields: z.record(z.string(), z.string()) }))
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true }
+    }, async ({ query, limit, profile }) => {
+        const issues = await searchIssues(await clientFor(profile), query, limit);
+        return { content: [{ type: "text", text: `Найдено задач: ${issues.length}` }], structuredContent: { issues } };
+    });
+    server.registerTool("whoami", {
+        title: "Кто я в YouTrack",
+        description: "Учётная запись, от имени которой идут вызовы. Нужна там, где скилл ставит Assignee на себя.",
+        inputSchema: { profile: profileArg },
+        outputSchema: { login: z.string(), name: z.string(), email: z.string() },
+        annotations: { readOnlyHint: true, openWorldHint: true }
+    }, async ({ profile }) => {
+        const user = await me(await clientFor(profile));
+        return { content: [{ type: "text", text: `${user.name} (${user.login})` }], structuredContent: user };
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@levinariy.fedorov/youtrack-mcp",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "MCP-сервер и библиотека для YouTrack: задача целиком одним вызовом — поля, комментарии, вложения, связи.",
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"youtrack",
+		"jetbrains",
+		"issue-tracking",
+		"claude"
+	],
+	"license": "MIT",
+	"author": "Levinariy Fedorov",
+	"homepage": "https://gitlab.ics-it.ru/levinariy.fedorov/youtrack-mcp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://gitlab.ics-it.ru/levinariy.fedorov/youtrack-mcp.git"
+	},
+	"bugs": {
+		"url": "https://gitlab.ics-it.ru/levinariy.fedorov/youtrack-mcp/-/issues"
+	},
+	"bin": {
+		"youtrack-mcp": "dist/bin.js"
+	},
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"files": [
+		"dist/"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"prepare": "tsc -p tsconfig.json",
+		"build": "tsc -p tsconfig.json",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "node --test",
+		"dev": "node --watch src/bin.ts"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"zod": "^4.5.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.13.5",
+		"typescript": "^5.7.3"
+	}
+}