@vitalyostanin/youtrack-mcp 0.2.0

package/dist/src/types.d.ts

@@ -0,0 +1,433 @@
+import type { MappedYoutrackIssue, MappedYoutrackIssueComment, MappedYoutrackIssueDetails, MappedYoutrackWorkItem } from "./utils/mappers.js";
+export interface ServiceInfo {
+    name: string;
+    version: string;
+    description?: string;
+}
+export type UserAliasMap = Record<string, string>;
+export interface YoutrackConfig {
+    baseUrl: string;
+    token: string;
+    timezone: string;
+    holidays?: string[];
+    preHolidays?: string[];
+    userAliases?: UserAliasMap;
+}
+export interface DurationValue {
+    minutes?: number;
+    presentation?: string;
+    $type?: string;
+}
+export interface YoutrackProject {
+    id: string;
+    shortName: string;
+    name?: string;
+}
+export interface YoutrackIssue {
+    id: string;
+    idReadable: string;
+    summary?: string;
+    description?: string;
+    wikifiedDescription?: string;
+    usesMarkdown?: boolean;
+    project?: YoutrackProject;
+    parent?: {
+        idReadable: string;
+        id?: string;
+    } | null;
+    assignee?: YoutrackUser | null;
+}
+export interface YoutrackIssueCreateInput {
+    project: string;
+    summary: string;
+    description?: string;
+    parentIssueId?: string;
+    assigneeLogin?: string;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackIssueUpdateInput {
+    issueId: string;
+    summary?: string;
+    description?: string;
+    parentIssueId?: string | null;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackIssueAssignInput {
+    issueId: string;
+    assigneeLogin: string;
+}
+export interface YoutrackUser {
+    id: string;
+    login: string;
+    name?: string;
+    fullName?: string;
+    email?: string;
+}
+export interface YoutrackUserListPayload {
+    users: YoutrackUser[];
+}
+export interface YoutrackProjectListPayload {
+    projects: YoutrackProject[];
+}
+export interface YoutrackWorkItem {
+    id: string;
+    date: number;
+    updated?: number;
+    duration: DurationValue;
+    text?: string;
+    textPreview?: string;
+    usesMarkdown?: boolean;
+    description?: string;
+    issue: {
+        idReadable: string;
+        id?: string;
+    };
+    author?: YoutrackUser;
+}
+export interface YoutrackWorkItemCreateInput {
+    issueId: string;
+    date: string | number | Date;
+    minutes: number;
+    summary?: string;
+    description?: string;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackWorkItemUpdateInput {
+    issueId: string;
+    workItemId: string;
+    date?: string | number | Date;
+    minutes?: number;
+    summary?: string;
+    description?: string;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackWorkItemPeriodCreateInput {
+    issueId: string;
+    startDate: string | number | Date;
+    endDate: string | number | Date;
+    minutes: number;
+    summary?: string;
+    description?: string;
+    usesMarkdown?: boolean;
+    excludeWeekends?: boolean;
+    excludeHolidays?: boolean;
+    holidays?: Array<string | number | Date>;
+    preHolidays?: Array<string | number | Date>;
+}
+export interface YoutrackWorkItemIdempotentCreateInput {
+    issueId: string;
+    date: string | number | Date;
+    minutes: number;
+    description: string;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackWorkItemReportOptions {
+    author?: string;
+    startDate?: string | number | Date;
+    endDate?: string | number | Date;
+    issueId?: string;
+    expectedDailyMinutes?: number;
+    excludeWeekends?: boolean;
+    excludeHolidays?: boolean;
+    holidays?: Array<string | number | Date>;
+    preHolidays?: Array<string | number | Date>;
+    allUsers?: boolean;
+}
+export interface ServiceStatusPayload {
+    service: ServiceInfo;
+    configuration: {
+        hasToken: boolean;
+        baseUrl: string | null;
+        holidays?: string[];
+        preHolidays?: string[];
+    };
+}
+export interface IssueLookupPayload {
+    issue: MappedYoutrackIssue;
+}
+export interface WorkItemsPayload {
+    items: MappedYoutrackWorkItem[];
+}
+export interface WorkItemCreatePayload {
+    item: MappedYoutrackWorkItem;
+}
+export interface WorkItemUpdatePayload {
+    item: MappedYoutrackWorkItem;
+}
+export interface WorkItemDeletePayload {
+    issueId: string;
+    workItemId: string;
+    deleted: true;
+}
+export interface YoutrackIssueDetails extends YoutrackIssue {
+    created?: number | null;
+    updated?: number | null;
+    resolved?: number | null;
+    reporter?: YoutrackUser;
+    updater?: YoutrackUser;
+}
+export interface IssueDetailsPayload {
+    issue: MappedYoutrackIssueDetails;
+}
+export interface YoutrackIssueComment {
+    id: string;
+    text?: string;
+    textPreview?: string;
+    usesMarkdown?: boolean;
+    author?: YoutrackUser;
+    created: number;
+    updated?: number;
+}
+export interface IssueCommentsPayload {
+    comments: MappedYoutrackIssueComment[];
+}
+export interface IssueCommentCreateInput {
+    issueId: string;
+    text: string;
+    usesMarkdown?: boolean;
+}
+export interface YoutrackActivityItem {
+    id: string;
+    timestamp: number;
+    author?: YoutrackUser;
+    category?: {
+        id: string;
+    };
+    target?: {
+        text?: string;
+    };
+    added?: Array<{
+        name?: string;
+        id?: string;
+        login?: string;
+    }>;
+    removed?: Array<{
+        name?: string;
+        id?: string;
+        login?: string;
+    }>;
+    $type?: string;
+}
+export interface IssueCommentCreatePayload {
+    comment: MappedYoutrackIssueComment;
+}
+export interface WorkItemReportDay {
+    date: string;
+    expectedMinutes: number;
+    actualMinutes: number;
+    difference: number;
+    percent: number;
+    items: MappedYoutrackWorkItem[];
+}
+export interface WorkItemSummary {
+    totalMinutes: number;
+    totalHours: number;
+    expectedMinutes: number;
+    expectedHours: number;
+    workDays: number;
+    averageHoursPerDay: number;
+}
+export interface WorkItemReportPayload {
+    summary: WorkItemSummary;
+    days: WorkItemReportDay[];
+    period: {
+        startDate: string;
+        endDate: string;
+    };
+    invalidDays: WorkItemInvalidDay[];
+}
+export interface WorkItemBulkResultPayload {
+    created: MappedYoutrackWorkItem[];
+    failed: Array<{
+        date: string;
+        reason: string;
+    }>;
+}
+export interface WorkItemInvalidDay {
+    date: string;
+    expectedMinutes: number;
+    actualMinutes: number;
+    difference: number;
+    percent: number;
+    items: MappedYoutrackWorkItem[];
+}
+export interface WorkItemUsersReportPayload {
+    reports: Array<{
+        userLogin: string;
+        summary: WorkItemSummary;
+        invalidDays: WorkItemInvalidDay[];
+        period: {
+            startDate: string;
+            endDate: string;
+        };
+    }>;
+}
+export interface WorkItemsForUsersPayload {
+    items: MappedYoutrackWorkItem[];
+    users: string[];
+}
+export interface WorkItemsAllUsersPayload {
+    items: MappedYoutrackWorkItem[];
+}
+export interface WorkItemIdempotentCreatePayload {
+    created: boolean;
+    item: MappedYoutrackWorkItem | null;
+}
+export interface YoutrackArticle {
+    id: string;
+    idReadable: string;
+    summary: string;
+    content?: string;
+    contentPreview?: string;
+    usesMarkdown?: boolean;
+    parentArticle?: {
+        id: string;
+        idReadable: string;
+    };
+    childArticles?: Array<{
+        id: string;
+        idReadable: string;
+        summary: string;
+    }>;
+    project?: {
+        id: string;
+        shortName: string;
+        name?: string;
+    };
+}
+export interface ArticlePayload {
+    article: YoutrackArticle;
+}
+export interface ArticleListPayload {
+    articles: YoutrackArticle[];
+}
+export interface ArticleCreateInput {
+    summary: string;
+    content?: string;
+    parentArticleId?: string;
+    projectId?: string;
+    usesMarkdown?: boolean;
+    returnRendered?: boolean;
+}
+export interface ArticleUpdateInput {
+    articleId: string;
+    summary?: string;
+    content?: string;
+    usesMarkdown?: boolean;
+    returnRendered?: boolean;
+}
+export interface ArticleSearchInput {
+    query: string;
+    projectId?: string;
+    parentArticleId?: string;
+    limit?: number;
+    returnRendered?: boolean;
+}
+export interface ArticleSearchPayload {
+    articles: YoutrackArticle[];
+    query: string;
+}
+export interface IssueSearchInput {
+    userLogins: string[];
+    startDate?: string | number | Date;
+    endDate?: string | number | Date;
+    dateFilterMode?: "issue_updated" | "user_activity";
+    limit?: number;
+    skip?: number;
+}
+export interface IssueSearchPayload {
+    issues: Array<MappedYoutrackIssue & {
+        lastActivityDate?: string;
+    }>;
+    userLogins: string[];
+    period?: {
+        startDate?: string;
+        endDate?: string;
+    };
+    pagination: {
+        returned: number;
+        limit: number;
+        skip: number;
+    };
+}
+export interface IssueError {
+    issueId: string;
+    error: string;
+}
+export interface IssuesLookupPayload {
+    issues: MappedYoutrackIssue[];
+    errors?: IssueError[];
+}
+export interface IssuesDetailsPayload {
+    issues: MappedYoutrackIssueDetails[];
+    errors?: IssueError[];
+}
+export interface IssuesCommentsPayload {
+    commentsByIssue: Record<string, MappedYoutrackIssueComment[]>;
+    errors?: IssueError[];
+}
+export interface YoutrackAttachment {
+    id: string;
+    name: string;
+    author?: YoutrackUser;
+    created: number;
+    updated?: number;
+    size: number;
+    mimeType?: string;
+    url?: string;
+    thumbnailURL?: string;
+    extension?: string;
+    charset?: string;
+    base64Content?: string;
+}
+export interface MappedYoutrackAttachment {
+    id: string;
+    name: string;
+    author?: {
+        id: string;
+        login: string;
+        name?: string;
+    };
+    created: string;
+    updated?: string;
+    size: number;
+    sizeFormatted: string;
+    mimeType?: string;
+    extension?: string;
+    url?: string;
+    thumbnailURL?: string;
+}
+export interface AttachmentsListPayload {
+    attachments: MappedYoutrackAttachment[];
+    issueId: string;
+}
+export interface AttachmentPayload {
+    attachment: MappedYoutrackAttachment;
+    issueId: string;
+}
+export interface AttachmentDownloadPayload {
+    attachment: MappedYoutrackAttachment;
+    downloadUrl: string;
+    issueId: string;
+}
+export interface AttachmentUploadInput {
+    issueId: string;
+    filePaths: string[];
+    muteUpdateNotifications?: boolean;
+}
+export interface AttachmentUploadPayload {
+    uploaded: MappedYoutrackAttachment[];
+    issueId: string;
+}
+export interface AttachmentDeleteInput {
+    issueId: string;
+    attachmentId: string;
+    confirmation: boolean;
+}
+export interface AttachmentDeletePayload {
+    deleted: true;
+    issueId: string;
+    attachmentId: string;
+    attachmentName: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,34 @@
+export declare function initializeTimezone(timezone: string): void;
+export declare function getTimezone(): string;
+export declare function parseDateInput(value: string | number | Date): number;
+export declare function toIsoDateString(value: string | number | Date): string;
+export declare function enumerateDateRange(start: string | number | Date, end: string | number | Date): string[];
+export declare function isWeekend(dateIso: string): boolean;
+export declare function isHoliday(date: string | number | Date, holidays?: Array<string | number | Date>): boolean;
+export declare function filterWorkingDays(dates: Array<string | Date | number>, excludeWeekends?: boolean, excludeHolidays?: boolean, holidays?: Array<string | Date | number>): string[];
+export declare function getDayBounds(value: string | number | Date): {
+    start: number;
+    end: number;
+};
+export declare function minutesToHours(minutes: number): number;
+export declare function hoursToMinutes(hours: number): number;
+export declare function calculateTotalMinutes(items: Array<{
+    duration: {
+        minutes?: number;
+    };
+}>): number;
+export declare function groupWorkItemsByDate<T extends {
+    date: number;
+}>(items: T[]): Map<string, T[]>;
+export declare function validateDateRange(start: string | number | Date, end: string | number | Date): void;
+export declare function isWorkingDay(value: string | number | Date): boolean;
+export declare function dateToUnixMs(value: string | Date, timezone?: string): number;
+export declare function unixMsToDate(timestamp: number): Date;
+export declare function formatDate(value: string | number | Date): string;
+export declare function formatDateInTimezone(value: string | number | Date, timezone: string): string;
+export declare function generateDateRange(start: string | number | Date, end: string | number | Date): Date[];
+export declare function filterWorkingDates(dates: Date[], excludeWeekends?: boolean, excludeHolidays?: boolean, holidays?: Date[]): Date[];
+export declare function isSameDay(left: string | number | Date, right: string | number | Date): boolean;
+export declare function getCurrentTimestamp(): number;
+export declare function getCurrentDate(timezone?: string): Date;
+//# sourceMappingURL=date.d.ts.map

package/dist/src/utils/date.js

@@ -0,0 +1,147 @@
+import { DateTime, Settings } from "luxon";
+let currentTimezone = "Europe/Moscow";
+export function initializeTimezone(timezone) {
+    currentTimezone = timezone;
+    Settings.defaultZone = timezone;
+}
+export function getTimezone() {
+    return currentTimezone;
+}
+export function parseDateInput(value) {
+    if (value instanceof Date) {
+        return DateTime.fromJSDate(value).toMillis();
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Date value must be a finite number");
+        }
+        return value;
+    }
+    const parsed = DateTime.fromISO(value, { zone: currentTimezone });
+    if (!parsed.isValid) {
+        throw new Error(`Invalid date value: ${value}`);
+    }
+    return parsed.toMillis();
+}
+export function toIsoDateString(value) {
+    const timestamp = parseDateInput(value);
+    return DateTime.fromMillis(timestamp).toFormat("yyyy-MM-dd");
+}
+export function enumerateDateRange(start, end) {
+    const startTime = DateTime.fromMillis(parseDateInput(start)).startOf("day");
+    const endTime = DateTime.fromMillis(parseDateInput(end)).startOf("day");
+    if (endTime < startTime) {
+        throw new Error("End date cannot be earlier than start date");
+    }
+    const dates = [];
+    for (let current = startTime; current <= endTime; current = current.plus({ days: 1 })) {
+        dates.push(current.toFormat("yyyy-MM-dd"));
+    }
+    return dates;
+}
+export function isWeekend(dateIso) {
+    const date = DateTime.fromISO(dateIso);
+    return date.weekday === 6 || date.weekday === 7;
+}
+export function isHoliday(date, holidays = []) {
+    const target = toIsoDateString(date);
+    return holidays.some((holiday) => toIsoDateString(holiday) === target);
+}
+export function filterWorkingDays(dates, excludeWeekends = true, excludeHolidays = true, holidays = []) {
+    return dates
+        .map((value) => toIsoDateString(value))
+        .filter((dateIso) => {
+        if (excludeWeekends && isWeekend(dateIso)) {
+            return false;
+        }
+        if (excludeHolidays && isHoliday(dateIso, holidays)) {
+            return false;
+        }
+        return true;
+    });
+}
+export function getDayBounds(value) {
+    const date = DateTime.fromMillis(parseDateInput(value));
+    const start = date.startOf("day");
+    const end = date.endOf("day");
+    return { start: start.toMillis(), end: end.toMillis() };
+}
+export function minutesToHours(minutes) {
+    return Math.round((minutes / 60) * 100) / 100;
+}
+export function hoursToMinutes(hours) {
+    return Math.round(hours * 60);
+}
+export function calculateTotalMinutes(items) {
+    return items.reduce((total, item) => total + (item.duration.minutes ?? 0), 0);
+}
+export function groupWorkItemsByDate(items) {
+    const map = new Map();
+    for (const item of items) {
+        const dateIso = toIsoDateString(item.date);
+        const bucket = map.get(dateIso) ?? [];
+        bucket.push(item);
+        map.set(dateIso, bucket);
+    }
+    return map;
+}
+export function validateDateRange(start, end) {
+    const startTime = DateTime.fromMillis(parseDateInput(start));
+    const endTime = DateTime.fromMillis(parseDateInput(end));
+    if (endTime < startTime) {
+        throw new Error("Start date must be before or equal to end date");
+    }
+}
+export function isWorkingDay(value) {
+    return !isWeekend(toIsoDateString(value));
+}
+export function dateToUnixMs(value, timezone = currentTimezone) {
+    const source = value instanceof Date ? DateTime.fromJSDate(value) : DateTime.fromISO(value);
+    const zoned = source.setZone(timezone);
+    const normalized = zoned.set({ hour: 12, minute: 0, second: 0, millisecond: 0 });
+    return normalized.toMillis();
+}
+export function unixMsToDate(timestamp) {
+    return DateTime.fromMillis(timestamp).toJSDate();
+}
+export function formatDate(value) {
+    return toIsoDateString(value);
+}
+export function formatDateInTimezone(value, timezone) {
+    const timestamp = parseDateInput(value);
+    const formatted = DateTime.fromMillis(timestamp).setZone(timezone).toFormat("yyyy-MM-dd");
+    return formatted;
+}
+export function generateDateRange(start, end) {
+    const startDate = DateTime.fromMillis(parseDateInput(start)).startOf("day");
+    const endDate = DateTime.fromMillis(parseDateInput(end)).startOf("day");
+    if (endDate < startDate) {
+        throw new Error("End date cannot be earlier than start date");
+    }
+    const dates = [];
+    for (let current = startDate; current <= endDate; current = current.plus({ days: 1 })) {
+        dates.push(current.toJSDate());
+    }
+    return dates;
+}
+export function filterWorkingDates(dates, excludeWeekends = true, excludeHolidays = true, holidays = []) {
+    return dates.filter((date) => {
+        if (excludeWeekends && !isWorkingDay(date)) {
+            return false;
+        }
+        if (excludeHolidays && holidays.some((holiday) => formatDate(holiday) === formatDate(date))) {
+            return false;
+        }
+        return true;
+    });
+}
+export function isSameDay(left, right) {
+    return formatDate(left) === formatDate(right);
+}
+export function getCurrentTimestamp() {
+    return DateTime.now().toMillis();
+}
+export function getCurrentDate(timezone = currentTimezone) {
+    return DateTime.now().setZone(timezone).toJSDate();
+}
+//# sourceMappingURL=date.js.map

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

@@ -0,0 +1,76 @@
+import type { YoutrackAttachment, YoutrackIssue, YoutrackIssueComment, YoutrackIssueDetails, YoutrackWorkItem, MappedYoutrackAttachment } from "../types.js";
+/**
+ * Convert timestamp in milliseconds to ISO date string (YYYY-MM-DD)
+ */
+export declare function timestampToIsoDate(timestamp: number | null | undefined): string | undefined;
+/**
+ * Convert timestamp in milliseconds to ISO datetime string (YYYY-MM-DDTHH:mm:ss.sssZ)
+ */
+export declare function timestampToIsoDateTime(timestamp: number | null | undefined): string | undefined;
+/**
+ * Mapped issue with ISO date strings
+ * Issue type doesn't have date fields, so it's the same as YoutrackIssue
+ */
+export type MappedYoutrackIssue = YoutrackIssue;
+/**
+ * Mapped issue details with ISO date strings
+ */
+export interface MappedYoutrackIssueDetails extends Omit<YoutrackIssueDetails, "created" | "updated" | "resolved"> {
+    created?: string;
+    updated?: string;
+    resolved?: string;
+}
+/**
+ * Mapped work item with ISO date strings
+ */
+export interface MappedYoutrackWorkItem extends Omit<YoutrackWorkItem, "date"> {
+    date: string;
+}
+/**
+ * Mapped comment with ISO date strings
+ */
+export interface MappedYoutrackIssueComment extends Omit<YoutrackIssueComment, "created" | "updated"> {
+    created: string;
+    updated?: string;
+}
+/**
+ * Map YoutrackIssue to MappedYoutrackIssue
+ */
+export declare function mapIssue(issue: YoutrackIssue): MappedYoutrackIssue;
+/**
+ * Map YoutrackIssueDetails to MappedYoutrackIssueDetails
+ */
+export declare function mapIssueDetails(issue: YoutrackIssueDetails): MappedYoutrackIssueDetails;
+/**
+ * Map YoutrackWorkItem to MappedYoutrackWorkItem
+ */
+export declare function mapWorkItem(item: YoutrackWorkItem): MappedYoutrackWorkItem;
+/**
+ * Map YoutrackIssueComment to MappedYoutrackIssueComment
+ */
+export declare function mapComment(comment: YoutrackIssueComment): MappedYoutrackIssueComment;
+/**
+ * Map array of issues
+ */
+export declare function mapIssues(issues: YoutrackIssue[]): MappedYoutrackIssue[];
+/**
+ * Map array of work items
+ */
+export declare function mapWorkItems(items: YoutrackWorkItem[]): MappedYoutrackWorkItem[];
+/**
+ * Map array of comments
+ */
+export declare function mapComments(comments: YoutrackIssueComment[]): MappedYoutrackIssueComment[];
+/**
+ * Format file size in bytes to human-readable format
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Map YoutrackAttachment to MappedYoutrackAttachment
+ */
+export declare function mapAttachment(attachment: YoutrackAttachment): MappedYoutrackAttachment;
+/**
+ * Map array of attachments
+ */
+export declare function mapAttachments(attachments: YoutrackAttachment[]): MappedYoutrackAttachment[];
+//# sourceMappingURL=mappers.d.ts.map