@levinariy.fedorov/youtrack-mcp 0.2.0 → 0.3.0

package/README.md

@@ -28,7 +28,9 @@ MCP-сервер прямо в продукте, и если он у вас ес
 ## Вход
 
 Токен — постоянный токен YouTrack из профиля пользователя. Принимается только
-потоком: в аргументе он осел бы в истории оболочки и был бы виден в списке процессов.
+потоком: в аргументе он осел бы в истории оболочки и был бы виден в списке
+процессов. Флаг `--token-stdin` нужен лишь в живом терминале, где команда иначе
+молча ждала бы ввод; при передаче через конвейер он не обязателен.
 
 ```powershell
 "<токен>" | npx @levinariy.fedorov/youtrack-mcp login --base-url https://youtrack.example.com --token-stdin
@@ -51,6 +53,12 @@ npx @levinariy.fedorov/youtrack-mcp profiles
 | `read_issue` | Задача целиком: поля, комментарии, вложения, связи — одним вызовом |
 | `search_issues` | Поиск запросом YouTrack; только идентификатор, тема и поля |
 | `add_comment` | Комментарий: заказчику или ограниченного круга |
+| `edit_comment` | Переписать уже опубликованный комментарий |
+| `find_users` | Логины по фамилии, имени или домену |
+| `list_work_items` | Что уже списано за период, с суммой |
+| `edit_comment` | Переписать уже опубликованный комментарий |
+| `find_users` | Логины по фамилии, имени или домену |
+| `list_work_items` | Что уже списано за период, с суммой |
 | `update_issue` | Поля, статус, тема, описание |
 | `create_issue` | Новая задача в проекте |
 | `log_work` | Списание времени |
@@ -114,6 +122,16 @@ npm run typecheck
 Собранный `dist` в репозитории не хранится: его делает `prepare` — при публикации
 и при установке пакета из git.
 
+## Выпуск версии
+
+Публикует GitLab CI по тегу: поднимите версию в `package.json`, закоммитьте,
+повесьте тег `vX.Y.Z` и запушьте его. Пайплайн сверит тег с версией, прогонит
+проверки и опубликует пакет. Пуш в ветку ничего не публикует.
+
+Токен для публикации лежит в переменной `NPM_TOKEN`: это granular access token
+npm с правом publish и разрешённым обходом двухфакторки — ввести одноразовый код
+в пайплайне некому.
+
 ## Лицензия
 
 MIT.

package/dist/bin.js

@@ -14,7 +14,7 @@ const USAGE = `youtrack-mcp — MCP-сервер для YouTrack.
 
 Ключи login:
   --base-url <URL>    адрес YouTrack
-  --token-stdin       прочитать токен из stdin
+  --token-stdin       ждать токен из stdin в интерактивном терминале
   --profile <имя>     профиль (по умолчанию default)
   --set-default       сделать профиль основным
 `;
@@ -38,18 +38,34 @@ async function login(argv) {
     if (!baseUrl)
         throw new AuthError("Нужен --base-url: адрес YouTrack.");
     // Токен принимаем только потоком: в аргументе он осядет в истории оболочки и
-    // будет виден в списке процессов.
-    if (!values["token-stdin"])
-        throw new AuthError("Токен передаётся через --token-stdin, аргументом — никогда.");
+    // будет виден в списке процессов. Требовать при этом ещё и --token-stdin
+    // незачем — другого способа всё равно нет. Флаг остаётся ради явности, но
+    // сам по себе решает только одно: ждать ли ввода в живом терминале, где
+    // молчаливое ожидание выглядит зависанием.
+    if (process.stdin.isTTY && !values["token-stdin"]) {
+        throw new AuthError("Токен передаётся потоком. Либо направьте его в stdin, либо добавьте --token-stdin и введите вручную.");
+    }
     const token = await readStdin();
     if (token === "")
-        throw new AuthError("Пустой токен.");
+        throw new AuthError("Пустой токен: в stdin ничего не пришло.");
+    // Токен уходит в заголовок HTTP, а туда пролезают только однобайтовые символы.
+    // Без этой проверки кириллица в токене роняет запрос сообщением про ByteString,
+    // по которому не догадаться, что дело в самом токене.
+    if (!/^[\x21-\x7e]+$/.test(token)) {
+        throw new AuthError("Токен содержит недопустимые символы: постоянный токен YouTrack состоит из латиницы, цифр и знаков препинания.");
+    }
+    // Сначала проверяем, потом сохраняем: профиль с негодным токеном в файле хуже,
+    // чем его отсутствие — он выглядит настроенным и ломается позже и не там.
     const profile = values.profile ?? "default";
+    const user = await me(new YouTrackClient({ baseUrl: baseUrl.replace(/\/+$/, ""), token }));
+    // Негодный токен YouTrack не отвергает: он отвечает от лица гостя, и логин
+    // выглядит удавшимся ровно до первой попытки что-нибудь записать.
+    if (user.guest) {
+        throw new AuthError("YouTrack не принял токен: ответ пришёл от гостевой учётной записи. Проверьте, что токен скопирован целиком и не отозван.");
+    }
     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() {

package/dist/index.d.ts

@@ -7,8 +7,8 @@
 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 { addComment, createIssue, logWork, updateIssue } from "./write.js";
-export type { Audience, NewIssue, PostedComment, UpdateRequest, WorkItem } from "./write.js";
+export { findUsers, listWorkItems, me, readIssue, searchIssues } from "./issues.js";
+export type { Attachment, Comment, Found, FoundPerson, Issue, Link, Person, ReadOptions, WorkItem } from "./issues.js";
+export { addComment, createIssue, editComment, logWork, updateIssue } from "./write.js";
+export type { Audience, LoggedWork, NewIssue, PostedComment, UpdateRequest } from "./write.js";
 export { createServer } from "./server.js";

package/dist/index.js

@@ -6,6 +6,6 @@
  */
 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 { addComment, createIssue, logWork, updateIssue } from "./write.js";
+export { findUsers, listWorkItems, me, readIssue, searchIssues } from "./issues.js";
+export { addComment, createIssue, editComment, logWork, updateIssue } from "./write.js";
 export { createServer } from "./server.js";

package/dist/issues.d.ts

@@ -59,6 +59,41 @@ export type Found = {
     fields: Record<string, string>;
 };
 export declare function searchIssues(client: YouTrackClient, query: string, limit?: number): Promise<Found[]>;
+export type FoundPerson = Person & {
+    email: string;
+};
+/**
+ * Ищет людей по имени, фамилии или части адреса.
+ *
+ * Нужен там, где известен человек, а требуется логин: в упоминаниях и в поле
+ * исполнителя YouTrack принимает только логин, и угадывать его по фамилии
+ * нельзя.
+ */
+export declare function findUsers(client: YouTrackClient, query: string, limit?: number): Promise<FoundPerson[]>;
+export type WorkItem = {
+    id: string;
+    issue: {
+        id: string;
+        summary: string;
+    };
+    author: Person;
+    date: string;
+    minutes: number;
+    text: string;
+};
+/**
+ * Записи о работе за период.
+ *
+ * Без автора берутся свои: чужие списания нужны редко, а «все за неделю» на
+ * большом трекере — это тысячи записей, которые никто не просил.
+ */
+export declare function listWorkItems(client: YouTrackClient, options?: {
+    from: string;
+    to: string;
+    author?: string;
+    limit?: number;
+}): Promise<WorkItem[]>;
 export declare function me(client: YouTrackClient): Promise<Person & {
     email: string;
+    guest: boolean;
 }>;

package/dist/issues.js

@@ -138,7 +138,50 @@ export async function searchIssues(client, query, limit = 50) {
         return { id: issue.idReadable ?? "", summary: issue.summary ?? "", fields: collectFields(issue) };
     });
 }
+/**
+ * Ищет людей по имени, фамилии или части адреса.
+ *
+ * Нужен там, где известен человек, а требуется логин: в упоминаниях и в поле
+ * исполнителя YouTrack принимает только логин, и угадывать его по фамилии
+ * нельзя.
+ */
+export async function findUsers(client, query, limit = 20) {
+    const raw = await client.get("/api/users", {
+        fields: "login,fullName,email",
+        query,
+        $top: limit
+    });
+    return raw.map((item) => ({ ...person(item), email: item.email ?? "" }));
+}
+/**
+ * Записи о работе за период.
+ *
+ * Без автора берутся свои: чужие списания нужны редко, а «все за неделю» на
+ * большом трекере — это тысячи записей, которые никто не просил.
+ */
+export async function listWorkItems(client, options = { from: "", to: "" }) {
+    const author = options.author ?? (await me(client)).login;
+    const raw = await client.get("/api/workItems", {
+        fields: "id,issue(idReadable,summary),author(login,fullName),date,duration(minutes),text",
+        author,
+        startDate: options.from,
+        endDate: options.to,
+        $top: options.limit ?? 200
+    });
+    return raw.map((item) => ({
+        id: item.id ?? "",
+        issue: { id: item.issue?.idReadable ?? "", summary: item.issue?.summary ?? "" },
+        author: person(item.author),
+        date: item.date ? new Date(item.date).toISOString().slice(0, 10) : "",
+        minutes: item.duration?.minutes ?? 0,
+        text: item.text ?? ""
+    }));
+}
 export async function me(client) {
-    const raw = await client.get("/api/users/me", { fields: "login,fullName,email" });
-    return { ...person(raw), email: raw.email ?? "" };
+    // Поле guest спрашивается не из любопытства: с негодным токеном YouTrack не
+    // отвечает ошибкой, а представляется гостем — и вызов выглядит удавшимся.
+    const raw = await client.get("/api/users/me", {
+        fields: "login,fullName,email,guest"
+    });
+    return { ...person(raw), email: raw.email ?? "", guest: raw.guest === true };
 }

package/dist/server.js

@@ -2,8 +2,8 @@ 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";
-import { addComment, createIssue, logWork, updateIssue } from "./write.js";
+import { findUsers, listWorkItems, me, readIssue, searchIssues } from "./issues.js";
+import { addComment, createIssue, editComment, logWork, updateIssue } from "./write.js";
 /**
  * Клиенты живут по имени профиля: конфигурацию незачем перечитывать на каждый
  * вызов, а профилей всё равно единицы.
@@ -114,6 +114,76 @@ export function createServer() {
             structuredContent: comment
         };
     });
+    server.registerTool("edit_comment", {
+        title: "Переписать комментарий",
+        description: "Заменяет текст уже опубликованного комментария целиком — дополнить его нечем, YouTrack хранит его одной строкой, " +
+            "так что прежний текст возьмите из `read_issue` и пришлите полный новый. " +
+            "Идентификатор комментария — оттуда же. Правьте только свои: чужой комментарий переписывать не следует.",
+        inputSchema: {
+            id: z.string().describe("Идентификатор задачи, например PROJ-1234"),
+            commentId: z.string().describe("Идентификатор комментария из read_issue"),
+            text: z.string().min(1).describe("Полный новый текст"),
+            profile: profileArg
+        },
+        outputSchema: { id: z.string(), created: z.string(), public: z.boolean() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+    }, async ({ id, commentId, text, profile }) => {
+        const comment = await editComment(await clientFor(profile), id, commentId, text);
+        return { content: [{ type: "text", text: "Комментарий переписан." }], structuredContent: comment };
+    });
+    server.registerTool("find_users", {
+        title: "Найти людей",
+        description: "Ищет по имени, фамилии или части адреса и возвращает логины. Нужен там, где человек известен, а требуется логин: " +
+            "в упоминаниях и в поле исполнителя YouTrack принимает только его.",
+        inputSchema: {
+            query: z.string().min(1).describe("Фамилия, имя, часть адреса или домен компании"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Сколько человек вернуть"),
+            profile: profileArg
+        },
+        outputSchema: {
+            users: z.array(z.object({ login: z.string(), name: z.string(), email: z.string() }))
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true }
+    }, async ({ query, limit, profile }) => {
+        const users = await findUsers(await clientFor(profile), query, limit);
+        return { content: [{ type: "text", text: `Найдено людей: ${users.length}` }], structuredContent: { users } };
+    });
+    server.registerTool("list_work_items", {
+        title: "Записи о работе за период",
+        description: "Что уже списано за интервал дат — по задачам, с датами и минутами. Без `author` берутся ваши записи. " +
+            "Отвечает на «сколько уже списано» до того, как списывать ещё; `totalMinutes` — сумма по выдаче.",
+        inputSchema: {
+            from: z.string().describe("Начало периода, 2026-09-01"),
+            to: z.string().describe("Конец периода включительно, 2026-09-07"),
+            author: z.string().optional().describe("Логин автора записей; по умолчанию вы"),
+            limit: z.number().int().min(1).max(1000).default(200).describe("Сколько записей вернуть"),
+            profile: profileArg
+        },
+        outputSchema: {
+            items: z.array(z.object({
+                id: z.string(),
+                issue: z.object({ id: z.string(), summary: z.string() }),
+                author: PersonSchema,
+                date: z.string(),
+                minutes: z.number(),
+                text: z.string()
+            })),
+            totalMinutes: z.number()
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true }
+    }, async ({ from, to, author, limit, profile }) => {
+        const items = await listWorkItems(await clientFor(profile), {
+            from,
+            to,
+            limit,
+            ...(author === undefined ? {} : { author })
+        });
+        const totalMinutes = items.reduce((sum, item) => sum + item.minutes, 0);
+        return {
+            content: [{ type: "text", text: `Записей: ${items.length}, всего ${totalMinutes} мин.` }],
+            structuredContent: { items, totalMinutes }
+        };
+    });
     server.registerTool("update_issue", {
         title: "Изменить поля задачи",
         description: "Меняет поля задачи по их именам в YouTrack: `{\"State\": \"Analysis\", \"Assignee\": \"ivan.petrov\"}`. " +
@@ -183,9 +253,10 @@ export function createServer() {
     });
     server.registerTool("whoami", {
         title: "Кто я в YouTrack",
-        description: "Учётная запись, от имени которой идут вызовы. Нужна там, где скилл ставит Assignee на себя.",
+        description: "Учётная запись, от имени которой идут вызовы. Нужна там, где скилл ставит Assignee на себя. " +
+            "`guest: true` означает, что токен не принят и YouTrack отвечает анонимно: писать от такого имени нельзя.",
         inputSchema: { profile: profileArg },
-        outputSchema: { login: z.string(), name: z.string(), email: z.string() },
+        outputSchema: { login: z.string(), name: z.string(), email: z.string(), guest: z.boolean() },
         annotations: { readOnlyHint: true, openWorldHint: true }
     }, async ({ profile }) => {
         const user = await me(await clientFor(profile));

package/dist/write.d.ts

@@ -17,6 +17,13 @@ export type PostedComment = {
     public: boolean;
 };
 export declare function addComment(client: YouTrackClient, issueId: string, text: string, audience?: Audience): Promise<PostedComment>;
+/**
+ * Переписывает уже опубликованный комментарий.
+ *
+ * Текст заменяется целиком — дополнить его нечем: YouTrack хранит комментарий
+ * одной строкой. Прежний текст, если он нужен, читается из `read_issue`.
+ */
+export declare function editComment(client: YouTrackClient, issueId: string, commentId: string, text: string): Promise<PostedComment>;
 export type UpdateRequest = {
     /** Поля задачи по именам, как они называются в YouTrack. Пустая строка очищает поле. */
     fields?: Record<string, string>;
@@ -31,7 +38,7 @@ export type NewIssue = {
     fields?: Record<string, string>;
 };
 export declare function createIssue(client: YouTrackClient, request: NewIssue): Promise<Issue>;
-export type WorkItem = {
+export type LoggedWork = {
     id: string;
     minutes: number;
     date: string;
@@ -47,4 +54,4 @@ export declare function logWork(client: YouTrackClient, issueId: string, minutes
     date?: string;
     text?: string;
     type?: string;
-}): Promise<WorkItem>;
+}): Promise<LoggedWork>;

package/dist/write.js

@@ -42,6 +42,20 @@ export async function addComment(client, issueId, text, audience = []) {
         public: created.visibility?.$type !== "LimitedVisibility"
     };
 }
+/**
+ * Переписывает уже опубликованный комментарий.
+ *
+ * Текст заменяется целиком — дополнить его нечем: YouTrack хранит комментарий
+ * одной строкой. Прежний текст, если он нужен, читается из `read_issue`.
+ */
+export async function editComment(client, issueId, commentId, text) {
+    const updated = await client.post(`/api/issues/${encodeURIComponent(issueId)}/comments/${encodeURIComponent(commentId)}`, { text }, { fields: "id,created,visibility($type)" });
+    return {
+        id: updated.id ?? commentId,
+        created: updated.created ? new Date(updated.created).toISOString() : "",
+        public: updated.visibility?.$type !== "LimitedVisibility"
+    };
+}
 /**
  * Готовит значение поля к записи.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@levinariy.fedorov/youtrack-mcp",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"type": "module",
 	"description": "MCP-сервер и библиотека для YouTrack: чтение задачи целиком, комментарии, поля и статусы, списание времени.",
 	"keywords": [