bitrix24-tasks-mcp-server 1.5.2 → 1.6.2

package/build/tools/index.js

@@ -1,4 +1,7 @@
+import { createHash } from 'node:crypto';
 import { bitrix24Client } from '../bitrix24/client.js';
+import { publishTaskComposite } from '../bitrix24/compositePublisher.js';
+import { validateToolArguments } from './validation.js';
 function stripBase64FromDownloadedFile(file) {
     if (!file.base64) {
         return file;
@@ -16,6 +19,42 @@ function collectFilesWithContent(...groups) {
 function normalizeStageTitle(value) {
     return String(value ?? '').trim().toLocaleLowerCase('ru-RU');
 }
+function compareNumericIds(left, right) {
+    if (!/^\d+$/.test(left) || !/^\d+$/.test(right)) {
+        return left.localeCompare(right, 'en', { numeric: true });
+    }
+    const leftValue = BigInt(left);
+    const rightValue = BigInt(right);
+    return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}
+function compactText(value, maxChars) {
+    if (value === undefined || value.length <= maxChars) {
+        return {
+            text: value,
+            truncated: false,
+            originalChars: value?.length ?? 0
+        };
+    }
+    return {
+        text: value.slice(0, maxChars),
+        truncated: true,
+        originalChars: value.length,
+        sha256: createHash('sha256').update(value).digest('hex')
+    };
+}
+function boundedOptionalString(value, maxChars) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return String(value).slice(0, maxChars);
+}
+function boundErrors(errors) {
+    return {
+        errors: errors.slice(0, 10).map((error) => String(error).slice(0, 512)),
+        errorsTruncated: errors.length > 10 || errors.some((error) => String(error).length > 512),
+        originalErrorCount: errors.length
+    };
+}
 // Task Management Tools
 export const createTaskTool = {
     name: 'bitrix24_create_task',
@@ -125,6 +164,65 @@ export const getTaskTool = {
         required: ['id']
     }
 };
+export const getTaskSummaryTool = {
+    name: 'bitrix24_get_task_summary',
+    description: 'Read a strict bounded task projection for workflow intake and routing. DESCRIPTION is capped at 12000 characters; TITLE is display metadata and must not be used as a routing signal.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            select: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 12,
+                items: {
+                    type: 'string',
+                    enum: [
+                        'ID',
+                        'TITLE',
+                        'DESCRIPTION',
+                        'GROUP_ID',
+                        'STAGE_ID',
+                        'STATUS',
+                        'CHANGED_DATE',
+                        'CREATED_DATE',
+                        'RESPONSIBLE_ID',
+                        'DEADLINE',
+                        'PRIORITY',
+                        'PARENT_ID'
+                    ]
+                },
+                description: 'Optional Bitrix task fields. Defaults to ID, TITLE, DESCRIPTION, GROUP_ID, STAGE_ID, STATUS, CHANGED_DATE, RESPONSIBLE_ID.'
+            }
+        },
+        required: ['taskId']
+    }
+};
+export const getTaskStageTool = {
+    name: 'bitrix24_get_task_stage',
+    description: 'Read the current task stage and minimal routing metadata without loading comments, description, or files.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            }
+        },
+        required: ['taskId']
+    }
+};
 export const listTasksTool = {
     name: 'bitrix24_list_tasks',
     description: 'List tasks with optional filtering and ordering',
@@ -206,7 +304,7 @@ export const getTaskCommentsTool = {
                 description: 'Legacy comment FILTER (task.commentitem.getlist only)'
             },
             limit: {
-                type: 'number',
+                type: 'integer',
                 description: 'Max messages for chat API (1-50, default 50)',
                 default: 50
             },
@@ -250,17 +348,86 @@ export const getTaskCommentsTool = {
         required: ['taskId']
     }
 };
+export const getTaskCommentsAfterTool = {
+    name: 'bitrix24_get_comments_after',
+    description: 'Read compact comments newer than a known comment/message ID. Returns text and metadata only; never downloads attachments or file bytes.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            afterCommentId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Return only comments/messages whose numeric ID is greater than this watermark'
+            },
+            preferApi: {
+                type: 'string',
+                enum: ['auto', 'chat', 'legacy'],
+                description: 'API strategy',
+                default: 'auto'
+            },
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 20,
+                description: 'Maximum comments to inspect and return',
+                default: 20
+            },
+            includeSystemMessages: {
+                type: 'boolean',
+                description: 'Include system messages',
+                default: false
+            },
+            maxCommentChars: {
+                type: 'integer',
+                minimum: 256,
+                maximum: 8000,
+                description: 'Per-comment text cap. Truncated comments include originalChars and sha256.',
+                default: 4000
+            },
+            maxTotalChars: {
+                type: 'integer',
+                minimum: 512,
+                maximum: 32000,
+                description: 'Hard cap for text across the returned page.',
+                default: 16000
+            }
+        },
+        required: ['taskId', 'afterCommentId']
+    }
+};
 export const addTaskCommentTool = {
     name: 'bitrix24_add_task_comment',
     description: 'Post a comment/message to a task. Modern path: tasks.task.chat.message.send + im.disk.file.commit; legacy fallback: task.commentitem.add.',
     inputSchema: {
         type: 'object',
+        additionalProperties: false,
         properties: {
-            taskId: { type: 'string', description: 'Task ID' },
-            text: { type: 'string', description: 'Comment text (required if no filePaths)' },
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            text: {
+                type: 'string',
+                maxLength: 32000,
+                description: 'Comment text (required if no filePaths)'
+            },
             filePaths: {
                 type: 'array',
-                items: { type: 'string' },
+                maxItems: 12,
+                items: { type: 'string', minLength: 1, maxLength: 4096 },
                 description: 'Local files to upload and attach to the comment/message'
             },
             diskFolderId: {
@@ -311,16 +478,141 @@ export const getTaskFilesTool = {
         required: ['taskId']
     }
 };
+export const getTaskFilesMetadataTool = {
+    name: 'bitrix24_get_task_files_metadata',
+    description: 'Read one bounded page of task attachment metadata without downloading file bytes or emitting base64.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            diskFileIds: {
+                type: 'array',
+                maxItems: 50,
+                items: { type: 'string', minLength: 1, maxLength: 64 },
+                description: 'Optional exact disk file IDs; omitted means all task file references'
+            },
+            imagesOnly: {
+                type: 'boolean',
+                description: 'Return image metadata only',
+                default: false
+            },
+            afterFileId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 64,
+                description: 'Pagination watermark from nextAfterFileId'
+            },
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 25,
+                default: 25,
+                description: 'Maximum metadata records in one page'
+            }
+        },
+        required: ['taskId']
+    }
+};
+export const publishTaskCompositeTool = {
+    name: 'bitrix24_publish_task_composite',
+    description: 'Idempotently publish a bounded ordered set of final comments/evidence attachments and then move the task to one exact stage with read-back verification. Use one call for final workflow publication.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            runId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 256,
+                description: 'Stable workflow run/dispatch ID'
+            },
+            evidenceSha256: {
+                type: 'string',
+                pattern: '^[a-fA-F0-9]{64}$',
+                description: 'SHA-256 of the evidence manifest being published'
+            },
+            comments: {
+                type: 'array',
+                maxItems: 12,
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        text: { type: 'string', minLength: 1, maxLength: 32000 },
+                        filePaths: {
+                            type: 'array',
+                            maxItems: 12,
+                            items: { type: 'string', minLength: 1, maxLength: 4096 },
+                            description: 'Optional local evidence files for this comment'
+                        }
+                    },
+                    required: ['text']
+                }
+            },
+            targetStageId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 64,
+                description: 'Exact target stage ID'
+            },
+            expectedCurrentStageId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 64,
+                description: 'Optional compare-and-set guard for the current stage'
+            },
+            preferApi: {
+                type: 'string',
+                enum: ['auto', 'chat', 'legacy'],
+                default: 'auto'
+            },
+            diskFolderId: {
+                type: 'string',
+                description: 'Optional Bitrix Disk folder for evidence uploads'
+            }
+        },
+        required: [
+            'taskId',
+            'runId',
+            'evidenceSha256',
+            'comments',
+            'targetStageId'
+        ]
+    }
+};
 export const attachFilesToTaskTool = {
     name: 'bitrix24_attach_files_to_task',
     description: 'Upload local files (images, documents) to Bitrix24 Disk and attach them to an existing task',
     inputSchema: {
         type: 'object',
+        additionalProperties: false,
         properties: {
-            taskId: { type: 'string', description: 'Task ID' },
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
             filePaths: {
                 type: 'array',
-                items: { type: 'string' },
+                minItems: 1,
+                maxItems: 12,
+                items: { type: 'string', minLength: 1, maxLength: 4096 },
                 description: 'Local file paths to upload and attach'
             },
             diskFolderId: {
@@ -403,9 +695,21 @@ export const moveTaskToStageTool = {
     description: 'Move a task to another Kanban/My Plan stage using task.stages.movetask. Provide stageId directly or stageName with entityId.',
     inputSchema: {
         type: 'object',
+        additionalProperties: false,
         properties: {
-            taskId: { type: 'string', description: 'Task ID' },
-            stageId: { type: 'string', description: 'Target stage ID' },
+            taskId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 32,
+                pattern: '^\\d+$',
+                description: 'Task ID'
+            },
+            stageId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 64,
+                description: 'Target stage ID'
+            },
             stageName: {
                 type: 'string',
                 description: 'Target stage title. Used to resolve stageId when stageId is omitted.'
@@ -695,19 +999,24 @@ export const resolveUserNamesTool = {
         required: ['userIds']
     }
 };
-/** Tools exposed via MCP ListTools (comments are included in bitrix24_get_task). */
-export const allTools = [
+const allToolCatalog = [
     createTaskTool,
+    getTaskSummaryTool,
+    getTaskStageTool,
     getTaskTool,
     listTasksTool,
     getLatestTasksTool,
     getTasksFromDateRangeTool,
+    getTaskCommentsTool,
+    getTaskCommentsAfterTool,
     updateTaskTool,
     getTaskStagesTool,
     canMoveTaskInStagesTool,
     moveTaskToStageTool,
     getTaskFilesTool,
+    getTaskFilesMetadataTool,
     addTaskCommentTool,
+    publishTaskCompositeTool,
     attachFilesToTaskTool,
     addTaskChecklistItemTool,
     listTaskChecklistItemsTool,
@@ -727,8 +1036,35 @@ export const allTools = [
     getAllUsersTool,
     resolveUserNamesTool
 ];
+const WORKFLOW_TOOL_NAMES = new Set([
+    'bitrix24_get_task_summary',
+    'bitrix24_get_task_stage',
+    'bitrix24_get_comments_after',
+    'bitrix24_get_task_files_metadata',
+    'bitrix24_publish_task_composite',
+    'bitrix24_add_task_comment',
+    'bitrix24_attach_files_to_task',
+    'bitrix24_move_task_to_stage'
+]);
+export function toolsForProfile(profile = process.env.BITRIX24_TOOL_PROFILE) {
+    const normalized = profile?.trim().toLowerCase();
+    if (!normalized || normalized === 'full') {
+        return [...allToolCatalog];
+    }
+    if (normalized === 'workflow') {
+        return allToolCatalog.filter((tool) => WORKFLOW_TOOL_NAMES.has(tool.name));
+    }
+    throw new Error(`Unsupported BITRIX24_TOOL_PROFILE ${JSON.stringify(profile)}; expected full or workflow`);
+}
+/** Tools exposed via MCP ListTools for the configured deployment profile. */
+export const allTools = toolsForProfile();
 export async function executeToolCall(name, args) {
     try {
+        const tool = allTools.find((candidate) => candidate.name === name);
+        if (!tool) {
+            throw new Error(`Tool is not exposed by the active profile: ${name}`);
+        }
+        args = validateToolArguments(tool, args ?? {});
         switch (name) {
             case 'bitrix24_create_task': {
                 const task = {
@@ -795,6 +1131,88 @@ export async function executeToolCall(name, args) {
                     message: `Task created with ID: ${taskId}`
                 };
             }
+            case 'bitrix24_get_task_summary': {
+                const task = await bitrix24Client.getTaskSummary(args.taskId, Array.isArray(args.select) && args.select.length > 0
+                    ? args.select
+                    : undefined);
+                return {
+                    success: true,
+                    task
+                };
+            }
+            case 'bitrix24_get_task_stage': {
+                const stage = await bitrix24Client.getTaskStage(args.taskId);
+                return {
+                    success: true,
+                    ...stage
+                };
+            }
+            case 'bitrix24_get_comments_after': {
+                const afterCommentId = String(args.afterCommentId);
+                const afterCommentNumber = Number(afterCommentId);
+                if (!Number.isSafeInteger(afterCommentNumber)) {
+                    throw new Error('afterCommentId exceeds the supported safe integer range');
+                }
+                const limit = Math.min(20, Math.max(1, Math.trunc(Number(args.limit ?? 20))));
+                const maxCommentChars = Math.min(8_000, Math.max(256, Number(args.maxCommentChars ?? 4_000)));
+                const maxTotalChars = Math.min(32_000, Math.max(512, Number(args.maxTotalChars ?? 16_000)));
+                const commentsResult = await bitrix24Client.getTaskComments(args.taskId, {
+                    preferApi: args.preferApi,
+                    firstId: afterCommentNumber,
+                    limit: Math.min(50, limit + 1),
+                    includeSystemMessages: args.includeSystemMessages === true,
+                    includeAttachments: false,
+                    includeContent: false
+                });
+                const candidates = commentsResult.comments
+                    .filter((comment) => /^\d{1,32}$/.test(String(comment.id)))
+                    .filter((comment) => compareNumericIds(comment.id, afterCommentId) > 0)
+                    .sort((left, right) => compareNumericIds(left.id, right.id));
+                const comments = [];
+                let totalCommentChars = 0;
+                for (const comment of candidates) {
+                    if (comments.length >= limit) {
+                        break;
+                    }
+                    const remainingChars = maxTotalChars - totalCommentChars;
+                    if (remainingChars <= 0) {
+                        break;
+                    }
+                    const effectiveCap = Math.max(1, Math.min(maxCommentChars, remainingChars));
+                    const compacted = compactText(comment.postMessage, effectiveCap);
+                    const textLength = compacted.text?.length ?? 0;
+                    if (comments.length > 0 && textLength > remainingChars) {
+                        break;
+                    }
+                    comments.push({
+                        id: comment.id,
+                        authorId: boundedOptionalString(comment.authorId, 64),
+                        authorName: boundedOptionalString(comment.authorName, 256),
+                        postDate: boundedOptionalString(comment.postDate, 128),
+                        postMessage: compacted.text,
+                        truncated: compacted.truncated,
+                        originalChars: compacted.originalChars,
+                        sha256: compacted.sha256
+                    });
+                    totalCommentChars += textLength;
+                }
+                const nextAfterCommentId = comments.length > 0
+                    ? String(comments[comments.length - 1].id)
+                    : afterCommentId;
+                const boundedErrors = boundErrors(commentsResult.errors);
+                return {
+                    success: commentsResult.errors.length === 0,
+                    taskId: commentsResult.taskId,
+                    apiMode: commentsResult.apiMode,
+                    afterCommentId,
+                    nextAfterCommentId,
+                    hasMore: candidates.some((comment) => compareNumericIds(comment.id, nextAfterCommentId) > 0),
+                    pageSize: comments.length,
+                    totalCommentChars,
+                    comments,
+                    ...boundedErrors
+                };
+            }
             case 'bitrix24_get_task_comments': {
                 const order = {};
                 order[args.orderBy || 'POST_DATE'] = args.orderDirection || 'asc';
@@ -892,6 +1310,25 @@ export async function executeToolCall(name, args) {
                         : `Retrieved ${filesResult.files.length} file(s) for task ${args.taskId}`
                 };
             }
+            case 'bitrix24_get_task_files_metadata': {
+                const filesResult = await bitrix24Client.getTaskFilesMetadata(args.taskId, {
+                    diskFileIds: args.diskFileIds,
+                    imagesOnly: args.imagesOnly === true,
+                    afterFileId: args.afterFileId,
+                    limit: args.limit
+                });
+                const boundedErrors = boundErrors(filesResult.errors);
+                return {
+                    success: filesResult.errors.length === 0,
+                    taskId: filesResult.taskId,
+                    afterFileId: filesResult.afterFileId,
+                    nextAfterFileId: filesResult.nextAfterFileId,
+                    hasMore: filesResult.hasMore,
+                    pageSize: filesResult.files.length,
+                    files: filesResult.files,
+                    ...boundedErrors
+                };
+            }
             case 'bitrix24_attach_files_to_task': {
                 const attachmentResult = await bitrix24Client.attachLocalFilesToTask(args.taskId, args.filePaths, args.diskFolderId);
                 return {
@@ -904,6 +1341,22 @@ export async function executeToolCall(name, args) {
                         : `Attached ${attachmentResult.attached.length} file(s) with ${attachmentResult.errors.length} error(s)`
                 };
             }
+            case 'bitrix24_publish_task_composite': {
+                const receipt = await publishTaskComposite(bitrix24Client, {
+                    taskId: args.taskId,
+                    runId: args.runId,
+                    evidenceSha256: args.evidenceSha256,
+                    comments: args.comments,
+                    targetStageId: args.targetStageId,
+                    expectedCurrentStageId: args.expectedCurrentStageId,
+                    preferApi: args.preferApi,
+                    diskFolderId: args.diskFolderId
+                });
+                return {
+                    success: true,
+                    receipt
+                };
+            }
             case 'bitrix24_get_task': {
                 const details = await bitrix24Client.getTaskDetails(args.id, {
                     includeComments: args.includeComments,