vikunja-mcp-ng 0.4.0

package/dist/tools/tasks/assignees/AssigneeValidationService.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Assignee validation service
+ * Handles input validation for assignee operations
+ */
+export interface AssigneeOperationInput {
+    id?: number;
+    assignees?: number[];
+}
+/**
+ * Service for validating assignee operation inputs
+ */
+export declare const AssigneeValidationService: {
+    /**
+     * Validate input for assign operations
+     */
+    validateAssignInput(args: AssigneeOperationInput): {
+        taskId: number;
+        assigneeIds: number[];
+    };
+    /**
+     * Validate input for unassign operations
+     */
+    validateUnassignInput(args: AssigneeOperationInput): {
+        taskId: number;
+        userIds: number[];
+    };
+    /**
+     * Validate input for list assignees operation. `search`/`page`/`perPage`
+     * map onto the dedicated `GET /tasks/{taskID}/assignees` endpoint's
+     * documented `s`/`page`/`per_page` query params — id validation for
+     * page/perPage happens in AssigneeOperationsService.fetchAssigneesViaRest,
+     * which is the only place that knows the field names used on the wire.
+     */
+    validateListInput(args: {
+        id?: number;
+        search?: string;
+        page?: number;
+        perPage?: number;
+    }): {
+        taskId: number;
+        search?: string;
+        page?: number;
+        perPage?: number;
+    };
+};
+//# sourceMappingURL=AssigneeValidationService.d.ts.map

package/dist/tools/tasks/assignees/AssigneeValidationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssigneeValidationService.d.ts","sourceRoot":"","sources":["../../../../src/tools/tasks/assignees/AssigneeValidationService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,sBAAsB;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB;IACpC;;OAEG;8BACuB,sBAAsB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE;IAsB5F;;OAEG;gCACyB,sBAAsB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAsB1F;;;;;;OAMG;4BACqB;QACtB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAgBzE,CAAC"}

package/dist/tools/tasks/assignees/AssigneeValidationService.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Assignee validation service
+ * Handles input validation for assignee operations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssigneeValidationService = void 0;
+const types_1 = require("../../../types");
+const validation_1 = require("../validation");
+/**
+ * Service for validating assignee operation inputs
+ */
+exports.AssigneeValidationService = {
+    /**
+     * Validate input for assign operations
+     */
+    validateAssignInput(args) {
+        if (!args.id) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Task id is required for assign operation');
+        }
+        (0, validation_1.validateId)(args.id, 'id');
+        if (!args.assignees || args.assignees.length === 0) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'At least one assignee (user id) is required');
+        }
+        // Validate assignee IDs
+        args.assignees.forEach((id) => (0, validation_1.validateId)(id, 'assignee ID'));
+        return {
+            taskId: args.id,
+            assigneeIds: args.assignees,
+        };
+    },
+    /**
+     * Validate input for unassign operations
+     */
+    validateUnassignInput(args) {
+        if (!args.id) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Task id is required for unassign operation');
+        }
+        (0, validation_1.validateId)(args.id, 'id');
+        if (!args.assignees || args.assignees.length === 0) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'At least one assignee (user id) is required to unassign');
+        }
+        // Validate assignee IDs
+        args.assignees.forEach((id) => (0, validation_1.validateId)(id, 'assignee ID'));
+        return {
+            taskId: args.id,
+            userIds: args.assignees,
+        };
+    },
+    /**
+     * Validate input for list assignees operation. `search`/`page`/`perPage`
+     * map onto the dedicated `GET /tasks/{taskID}/assignees` endpoint's
+     * documented `s`/`page`/`per_page` query params — id validation for
+     * page/perPage happens in AssigneeOperationsService.fetchAssigneesViaRest,
+     * which is the only place that knows the field names used on the wire.
+     */
+    validateListInput(args) {
+        if (args.id === undefined) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Task id is required for list-assignees operation');
+        }
+        (0, validation_1.validateId)(args.id, 'id');
+        return {
+            taskId: args.id,
+            ...(args.search !== undefined && { search: args.search }),
+            ...(args.page !== undefined && { page: args.page }),
+            ...(args.perPage !== undefined && { perPage: args.perPage }),
+        };
+    },
+};
+//# sourceMappingURL=AssigneeValidationService.js.map

package/dist/tools/tasks/assignees/AssigneeValidationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssigneeValidationService.js","sourceRoot":"","sources":["../../../../src/tools/tasks/assignees/AssigneeValidationService.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,0CAAqD;AACrD,8CAA2C;AAO3C;;GAEG;AACU,QAAA,yBAAyB,GAAG;IACvC;;OAEG;IACH,mBAAmB,CAAC,IAA4B;QAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,gBAAQ,CAAC,iBAAS,CAAC,gBAAgB,EAAE,0CAA0C,CAAC,CAAC;QAC7F,CAAC;QACD,IAAA,uBAAU,EAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAE1B,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,gBAAQ,CAChB,iBAAS,CAAC,gBAAgB,EAC1B,6CAA6C,CAC9C,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAA,uBAAU,EAAC,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAE9D,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,WAAW,EAAE,IAAI,CAAC,SAAS;SAC5B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,qBAAqB,CAAC,IAA4B;QAChD,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,gBAAQ,CAAC,iBAAS,CAAC,gBAAgB,EAAE,4CAA4C,CAAC,CAAC;QAC/F,CAAC;QACD,IAAA,uBAAU,EAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAE1B,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,gBAAQ,CAChB,iBAAS,CAAC,gBAAgB,EAC1B,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAA,uBAAU,EAAC,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;QAE9D,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,OAAO,EAAE,IAAI,CAAC,SAAS;SACxB,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,IAKjB;QACC,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,gBAAQ,CAChB,iBAAS,CAAC,gBAAgB,EAC1B,kDAAkD,CACnD,CAAC;QACJ,CAAC;QACD,IAAA,uBAAU,EAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAE1B,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;YACzD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7D,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/tasks/assignees/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Assignee operations for tasks
+ * Refactored to use modular service architecture
+ */
+import type { AuthManager } from '../../../auth/AuthManager';
+/**
+ * Assign users to a task
+ */
+export declare function assignUsers(args: {
+    id?: number;
+    assignees?: number[];
+}, authManager: AuthManager): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Unassign users from a task
+ */
+export declare function unassignUsers(args: {
+    id?: number;
+    assignees?: number[];
+}, authManager: AuthManager): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * List assignees of a task.
+ *
+ * Calls the dedicated `GET /tasks/{taskID}/assignees` endpoint directly
+ * (not `GET /tasks/{id}` + the embedded `assignees` array, which is what
+ * `assignUsers`/`unassignUsers` use internally for verification/refresh) so
+ * that the endpoint's documented `s` (username search) and `page`/`per_page`
+ * query params are actually reachable — see docs/API-COVERAGE.md's
+ * `GET /tasks/{taskID}/assignees` row for the gap this closes.
+ */
+export declare function listAssignees(args: {
+    id?: number;
+    search?: string;
+    page?: number;
+    perPage?: number;
+    sessionId?: string;
+}, authManager: AuthManager): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/tasks/assignees/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/tasks/assignees/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAM7D;;GAEG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE;IACJ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,EACD,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA8B7D;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE;IACJ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,EACD,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAoB7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE;IACJ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,EACD,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CA2C7D"}

package/dist/tools/tasks/assignees/index.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Assignee operations for tasks
+ * Refactored to use modular service architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignUsers = assignUsers;
+exports.unassignUsers = unassignUsers;
+exports.listAssignees = listAssignees;
+const types_1 = require("../../../types");
+const response_factory_1 = require("../../../utils/response-factory");
+const AssigneeOperationsService_1 = require("./AssigneeOperationsService");
+const AssigneeValidationService_1 = require("./AssigneeValidationService");
+const AssigneeResponseFormatter_1 = require("./AssigneeResponseFormatter");
+/**
+ * Assign users to a task
+ */
+async function assignUsers(args, authManager) {
+    try {
+        const { taskId, assigneeIds } = AssigneeValidationService_1.AssigneeValidationService.validateAssignInput(args);
+        // Perform the assignment operation
+        await AssigneeOperationsService_1.AssigneeOperationsService.assignUsersToTask(authManager, taskId, assigneeIds);
+        // Verify the assignees actually persisted (defense-in-depth against silent
+        // API failures — adapted from upstream PR #43). Fails open on fetch errors.
+        const missingIds = await AssigneeOperationsService_1.AssigneeOperationsService.verifyAssignees(authManager, taskId, assigneeIds);
+        // Fetch updated task data
+        const task = await AssigneeOperationsService_1.AssigneeOperationsService.fetchTaskWithAssignees(authManager, taskId);
+        // Format and return response, surfacing a warning if verification failed
+        const response = AssigneeResponseFormatter_1.AssigneeResponseFormatter.formatAssignResponse(task);
+        if (missingIds.length > 0) {
+            response.success = false;
+            response.message =
+                `Assignee operation reported success, but user(s) [${missingIds.join(', ')}] were not persisted. ` +
+                    `This is a known Vikunja API limitation with API token auth. Try using JWT authentication instead.`;
+        }
+        return AssigneeResponseFormatter_1.AssigneeResponseFormatter.formatMcpResponse(response);
+    }
+    catch (error) {
+        throw new types_1.MCPError(types_1.ErrorCode.API_ERROR, `Failed to assign users to task: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Unassign users from a task
+ */
+async function unassignUsers(args, authManager) {
+    try {
+        const { taskId, userIds } = AssigneeValidationService_1.AssigneeValidationService.validateUnassignInput(args);
+        // Perform the unassignment operation
+        await AssigneeOperationsService_1.AssigneeOperationsService.removeUsersFromTask(authManager, taskId, userIds);
+        // Fetch updated task data
+        const task = await AssigneeOperationsService_1.AssigneeOperationsService.fetchTaskWithAssignees(authManager, taskId);
+        // Format and return response
+        const response = AssigneeResponseFormatter_1.AssigneeResponseFormatter.formatUnassignResponse(task);
+        return AssigneeResponseFormatter_1.AssigneeResponseFormatter.formatMcpResponse(response);
+    }
+    catch (error) {
+        throw new types_1.MCPError(types_1.ErrorCode.API_ERROR, `Failed to remove users from task: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * List assignees of a task.
+ *
+ * Calls the dedicated `GET /tasks/{taskID}/assignees` endpoint directly
+ * (not `GET /tasks/{id}` + the embedded `assignees` array, which is what
+ * `assignUsers`/`unassignUsers` use internally for verification/refresh) so
+ * that the endpoint's documented `s` (username search) and `page`/`per_page`
+ * query params are actually reachable — see docs/API-COVERAGE.md's
+ * `GET /tasks/{taskID}/assignees` row for the gap this closes.
+ */
+async function listAssignees(args, authManager) {
+    try {
+        const { taskId, search, page, perPage } = AssigneeValidationService_1.AssigneeValidationService.validateListInput(args);
+        const assignees = await AssigneeOperationsService_1.AssigneeOperationsService.fetchAssigneesViaRest(authManager, taskId, {
+            ...(search !== undefined && { search }),
+            ...(page !== undefined && { page }),
+            ...(perPage !== undefined && { perPage }),
+        });
+        const response = (0, response_factory_1.createStandardResponse)('get', `Task ${taskId} has ${assignees.length} assignee(s)`, {
+            taskId,
+            assignees: assignees.map((a) => ({
+                id: a.id ?? null,
+                username: a.username ?? null,
+                name: a.name ?? null,
+                email: a.email ?? null,
+            })),
+            count: assignees.length,
+        }, {
+            timestamp: new Date().toISOString(),
+            count: assignees.length,
+            ...(search !== undefined && { search }),
+            ...(page !== undefined && { page }),
+            ...(perPage !== undefined && { perPage }),
+        }, args.sessionId);
+        return { content: [{ type: 'text', text: (0, response_factory_1.formatAorpAsMarkdown)(response) }] };
+    }
+    catch (error) {
+        if (error instanceof types_1.MCPError) {
+            throw error;
+        }
+        throw new types_1.MCPError(types_1.ErrorCode.API_ERROR, `Failed to list task assignees: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/tasks/assignees/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tools/tasks/assignees/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/tasks/attach.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Attach subcommand of `vikunja_tasks`.
+ *
+ * Uploads a file as an attachment on an existing task via the Vikunja REST
+ * endpoint `PUT /tasks/{id}/attachments` (`multipart/form-data`, field name
+ * `files`). The endpoint accepts multiple files per call; this handler
+ * uploads a single file per invocation to keep the schema simple.
+ *
+ * Two ways to provide the file:
+ *   - `filePath`: absolute path readable by the MCP server process.
+ *   - `fileContent`: base64-encoded contents (typical when the MCP client
+ *     runs on a different machine than the server).
+ *
+ * When both are present, `filePath` takes precedence. `filename` is optional
+ * and falls back to `basename(filePath)` or `attachment.bin`. Any directory
+ * components in `filename` are stripped before upload.
+ */
+import { z } from 'zod';
+import type { AuthManager } from '../../auth/AuthManager';
+export declare const attachSchemaFields: {
+    filePath: z.ZodOptional<z.ZodString>;
+    fileContent: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+};
+export interface TaskAttachArgs {
+    id?: number;
+    filePath?: string;
+    fileContent?: string;
+    filename?: string;
+}
+interface AttachResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+export declare function handleAttach(args: TaskAttachArgs, authManager: AuthManager): Promise<AttachResult>;
+export {};
+//# sourceMappingURL=attach.d.ts.map

package/dist/tools/tasks/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/tools/tasks/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,YAAY,CAAC,CAgFvB"}

package/dist/tools/tasks/attach.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Attach subcommand of `vikunja_tasks`.
+ *
+ * Uploads a file as an attachment on an existing task via the Vikunja REST
+ * endpoint `PUT /tasks/{id}/attachments` (`multipart/form-data`, field name
+ * `files`). The endpoint accepts multiple files per call; this handler
+ * uploads a single file per invocation to keep the schema simple.
+ *
+ * Two ways to provide the file:
+ *   - `filePath`: absolute path readable by the MCP server process.
+ *   - `fileContent`: base64-encoded contents (typical when the MCP client
+ *     runs on a different machine than the server).
+ *
+ * When both are present, `filePath` takes precedence. `filename` is optional
+ * and falls back to `basename(filePath)` or `attachment.bin`. Any directory
+ * components in `filename` are stripped before upload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSchemaFields = void 0;
+exports.handleAttach = handleAttach;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const types_1 = require("../../types");
+const vikunja_rest_1 = require("../../utils/vikunja-rest");
+exports.attachSchemaFields = {
+    filePath: zod_1.z.string().optional(),
+    fileContent: zod_1.z.string().optional(),
+    filename: zod_1.z.string().optional(),
+};
+async function handleAttach(args, authManager) {
+    const { id, filePath, fileContent, filename } = args ?? {};
+    if (typeof id !== 'number' || !Number.isFinite(id) || id <= 0) {
+        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'attach requires a positive numeric task id');
+    }
+    let bytes;
+    let name;
+    let source;
+    if (filePath) {
+        try {
+            bytes = (0, node_fs_1.readFileSync)(filePath);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, `attach: cannot read filePath ${filePath}: ${message}`);
+        }
+        name = filename || (0, node_path_1.basename)(filePath);
+        source = 'filePath';
+    }
+    else if (fileContent) {
+        const decoded = Buffer.from(fileContent, 'base64');
+        if (decoded.length === 0) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'attach: decoded fileContent is empty (not valid base64 or empty input)');
+        }
+        bytes = decoded;
+        name = filename || 'attachment.bin';
+        source = 'fileContent';
+    }
+    else {
+        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'attach requires filePath or fileContent');
+    }
+    // Strip any directory component a caller might inject via `filename`.
+    name = (0, node_path_1.basename)(name);
+    const form = new FormData();
+    form.append('files', new Blob([bytes]), name);
+    // Uploads go through the shared REST helper's multipart variant, which
+    // gives this call the same URL normalization, named circuit breaker, and
+    // MCPError/statusCode error contract as every other direct-REST call —
+    // it previously built its own URL by hand (skipping the `/api/v1`
+    // normalization vikunjaRestRequest applies) and had no failure
+    // protection at all. Retries stay off by default here (see
+    // DEFAULT_MULTIPART_RETRY in vikunja-rest.ts): resending a file upload
+    // after an ambiguous failure risks duplicating the attachment.
+    const data = await (0, vikunja_rest_1.vikunjaRestMultipartRequest)(authManager, 'PUT', `/tasks/${id}/attachments`, form);
+    const summary = { taskId: id, filename: name, bytes: bytes.length, source };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `## ✅ Success\n\nAttached \`${name}\` (${bytes.length} bytes) to task #${id}\n\n` +
+                    `**Operation:** attach-task-file\n\n` +
+                    '```json\n' +
+                    JSON.stringify({ summary, response: data }, null, 2) +
+                    '\n```',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=attach.js.map

package/dist/tools/tasks/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../../src/tools/tasks/attach.ts"],"names":[],"mappings":"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"}

package/dist/tools/tasks/attachments.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Attachments read-side subcommands of `vikunja_tasks`.
+ *
+ * Complements `attach.ts`'s upload path (`PUT /tasks/{id}/attachments`) with:
+ *   - `list-attachments`:    `GET /tasks/{id}/attachments` (page/per_page).
+ *   - `get-attachment-info`: metadata for one attachment. The spec has no
+ *     single-attachment metadata endpoint — `GET
+ *     /tasks/{id}/attachments/{attachmentID}` returns the raw file bytes,
+ *     not JSON — so this is derived by fetching the list and finding the
+ *     matching id, the same fetch-list-and-filter shape `vikunja_webhooks`
+ *     uses for its `get` subcommand (no per-id GET exists there either).
+ *   - `delete-attachment`:   `DELETE /tasks/{id}/attachments/{attachmentID}`.
+ *   - `download-attachment`: per the OpenAPI spec, `GET
+ *     /tasks/{id}/attachments/{attachmentID}` produces
+ *     `application/octet-stream`. MCP has no binary/file-delivery channel
+ *     (see docs/API_NOTES.md's "MCP-Specific Limitations"), so this cannot
+ *     fetch and hand back the file itself. Honesty over pretending
+ *     (docs/ENDPOINT-PLAYBOOK.md §7): it returns the direct download URL and
+ *     the auth header the caller needs to fetch it themselves — the same
+ *     shape as `vikunja_download_user_export` in `src/tools/export.ts`.
+ */
+import type { AuthManager } from '../../auth/AuthManager';
+/** Preview sizes documented for the download endpoint's `preview_size` query param. */
+export type AttachmentPreviewSize = 'sm' | 'md' | 'lg' | 'xl';
+export interface AttachmentSubcommandArgs {
+    /** Id of the task the attachment belongs to. */
+    id?: number;
+    /** Id of a specific attachment (required by get-attachment-info, delete-attachment, download-attachment). */
+    attachmentId?: number;
+    /** Pagination (list-attachments, get-attachment-info). */
+    page?: number;
+    perPage?: number;
+    /** Preview image size hint for download-attachment (spec: sm/md/lg/xl). */
+    previewSize?: AttachmentPreviewSize;
+    /** Session id for AORP response tracking. */
+    sessionId?: string;
+}
+type McpTextResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+/**
+ * Lists a task's attachments (`GET /tasks/{id}/attachments`).
+ */
+export declare function listAttachments(args: AttachmentSubcommandArgs, authManager: AuthManager): Promise<McpTextResult>;
+/**
+ * Retrieves metadata (file name, size, mime, created, author) for a single
+ * attachment. There is no dedicated single-attachment metadata endpoint in
+ * the spec, so this fetches the list and picks out the matching id.
+ */
+export declare function getAttachmentInfo(args: AttachmentSubcommandArgs, authManager: AuthManager): Promise<McpTextResult>;
+/**
+ * Deletes an attachment (`DELETE /tasks/{id}/attachments/{attachmentID}`).
+ */
+export declare function deleteAttachment(args: AttachmentSubcommandArgs, authManager: AuthManager): Promise<McpTextResult>;
+/**
+ * Returns the direct download URL for an attachment plus auth guidance,
+ * instead of pretending this tool can deliver the binary file itself. See
+ * the module doc comment for why: `GET
+ * /tasks/{id}/attachments/{attachmentID}` returns
+ * `application/octet-stream`, and MCP has no binary content channel.
+ */
+export declare function downloadAttachment(args: AttachmentSubcommandArgs, authManager: AuthManager): McpTextResult;
+export {};
+//# sourceMappingURL=attachments.d.ts.map

package/dist/tools/tasks/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../../src/tools/tasks/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAS1D,uFAAuF;AACvF,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9D,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6GAA6G;IAC7G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,KAAK,aAAa,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AA0DxE;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,wBAAwB,EAC9B,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,aAAa,CAAC,CAsBxB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,EAC9B,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,aAAa,CAAC,CA0BxB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,wBAAwB,EAC9B,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,aAAa,CAAC,CAmBxB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,wBAAwB,EAC9B,WAAW,EAAE,WAAW,GACvB,aAAa,CA4Bf"}