vikunja-mcp-ng 0.4.0

package/dist/tools/tokens.js.map

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

package/dist/tools/user-deletion.d.ts

@@ -0,0 +1,41 @@
+/**
+ * User Self-Deletion Tool
+ *
+ * Covers the Vikunja OpenAPI spec's `/user/deletion/*` operations: request,
+ * confirm, and cancel the deletion of the CURRENTLY AUTHENTICATED account.
+ * This is the reserved slot the `userDeletion` deny-by-default module config
+ * key (see src/config/types.ts DANGEROUS_MODULE_KEYS) was set aside for —
+ * before this tool, the key existed but nothing was wired to it.
+ *
+ * Reserved behind TWO gates, both of which must allow the call (module
+ * config can only narrow auth, never expand it — see src/tools/index.ts,
+ * matching the existing `admin`/`users`/`export` precedent):
+ * 1. The deny-by-default `userDeletion` module config key — an operator
+ *    must explicitly opt in before this tool is even registered.
+ * 2. JWT-only auth gating: per docs/VIKUNJA_API_ISSUES.md, ALL `/user/*`
+ *    endpoints reject `tk_*` API tokens server-side and require a JWT
+ *    session. API-token sessions never see this tool registered,
+ *    regardless of the `userDeletion` config value.
+ *
+ * `request` and `confirm` additionally require an explicit `confirm: true`
+ * tool argument (mirroring `vikunja_admin`'s `delete-user` pattern) — both
+ * legs move the account irreversibly closer to deletion once Vikunja's
+ * email-confirmation flow completes. `cancel` is the safe "undo" leg and
+ * does NOT require `confirm: true`.
+ *
+ * SECRETS: `password` (request/cancel) and `token` (confirm, delivered by
+ * email — the caller supplies it, this tool never fetches or sees the
+ * email itself) are credentials. Neither is ever included in a response or
+ * error message here: success responses only echo the server's generic
+ * confirmation message (`models.Message.message`, which Vikunja itself
+ * never populates with the submitted credential), and the request body is
+ * never interpolated into any thrown error text. See src/utils/security.ts
+ * for the shared masking conventions — `logger.debug` below intentionally
+ * logs only the subcommand (never `args`), so neither secret can reach logs
+ * even incidentally.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AuthManager } from '../auth/AuthManager';
+import type { VikunjaClientFactory } from '../client/VikunjaClientFactory';
+export declare function registerUserDeletionTool(server: McpServer, authManager: AuthManager, _clientFactory?: VikunjaClientFactory): void;
+//# sourceMappingURL=user-deletion.d.ts.map

package/dist/tools/user-deletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-deletion.d.ts","sourceRoot":"","sources":["../../src/tools/user-deletion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAY3E,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,WAAW,EACxB,cAAc,CAAC,EAAE,oBAAoB,GACpC,IAAI,CAsKN"}

package/dist/tools/user-deletion.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * User Self-Deletion Tool
+ *
+ * Covers the Vikunja OpenAPI spec's `/user/deletion/*` operations: request,
+ * confirm, and cancel the deletion of the CURRENTLY AUTHENTICATED account.
+ * This is the reserved slot the `userDeletion` deny-by-default module config
+ * key (see src/config/types.ts DANGEROUS_MODULE_KEYS) was set aside for —
+ * before this tool, the key existed but nothing was wired to it.
+ *
+ * Reserved behind TWO gates, both of which must allow the call (module
+ * config can only narrow auth, never expand it — see src/tools/index.ts,
+ * matching the existing `admin`/`users`/`export` precedent):
+ * 1. The deny-by-default `userDeletion` module config key — an operator
+ *    must explicitly opt in before this tool is even registered.
+ * 2. JWT-only auth gating: per docs/VIKUNJA_API_ISSUES.md, ALL `/user/*`
+ *    endpoints reject `tk_*` API tokens server-side and require a JWT
+ *    session. API-token sessions never see this tool registered,
+ *    regardless of the `userDeletion` config value.
+ *
+ * `request` and `confirm` additionally require an explicit `confirm: true`
+ * tool argument (mirroring `vikunja_admin`'s `delete-user` pattern) — both
+ * legs move the account irreversibly closer to deletion once Vikunja's
+ * email-confirmation flow completes. `cancel` is the safe "undo" leg and
+ * does NOT require `confirm: true`.
+ *
+ * SECRETS: `password` (request/cancel) and `token` (confirm, delivered by
+ * email — the caller supplies it, this tool never fetches or sees the
+ * email itself) are credentials. Neither is ever included in a response or
+ * error message here: success responses only echo the server's generic
+ * confirmation message (`models.Message.message`, which Vikunja itself
+ * never populates with the submitted credential), and the request body is
+ * never interpolated into any thrown error text. See src/utils/security.ts
+ * for the shared masking conventions — `logger.debug` below intentionally
+ * logs only the subcommand (never `args`), so neither secret can reach logs
+ * even incidentally.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUserDeletionTool = registerUserDeletionTool;
+const zod_1 = require("zod");
+const types_1 = require("../types");
+const logger_1 = require("../utils/logger");
+const response_factory_1 = require("../utils/response-factory");
+const vikunja_rest_1 = require("../utils/vikunja-rest");
+const read_only_1 = require("../utils/read-only");
+function registerUserDeletionTool(server, authManager, _clientFactory) {
+    server.tool('vikunja_user_deletion', (0, read_only_1.withReadOnlyNote)('vikunja_user_deletion', "Request, confirm, or cancel deletion of the CURRENTLY AUTHENTICATED Vikunja account. Reserved/deny-by-default: only registered when the 'userDeletion' module config key is explicitly enabled AND the session is JWT-authenticated (API-token sessions never see this tool, regardless of config). 'request' asks the server to start the deletion and sends a confirmation email; 'confirm' (given the token from that email) irreversibly proceeds with deletion; both require an explicit confirm: true argument. 'cancel' aborts an in-progress deletion request and does NOT require confirm: true — it is the safe undo."), {
+        subcommand: zod_1.z.enum(['request', 'confirm', 'cancel']),
+        // request / cancel
+        password: zod_1.z
+            .string()
+            .min(1)
+            .optional()
+            .describe('The account password. Required for request and cancel.'),
+        // confirm — the token Vikunja emailed to the account owner.
+        token: zod_1.z
+            .string()
+            .min(1)
+            .optional()
+            .describe('The deletion-confirmation token delivered by email. Required for confirm.'),
+        confirm: zod_1.z
+            .boolean()
+            .optional()
+            .describe('Must be true to perform request or confirm. Account deletion is scheduled and irreversible once the emailed token is confirmed. Not required for cancel.'),
+    }, (0, read_only_1.getToolAnnotations)('vikunja_user_deletion'), async (args) => {
+        if (!authManager.isAuthenticated()) {
+            throw new types_1.MCPError(types_1.ErrorCode.AUTH_REQUIRED, 'Authentication required. Please use vikunja_auth.connect first.');
+        }
+        if (authManager.getAuthType() !== 'jwt') {
+            throw new types_1.MCPError(types_1.ErrorCode.PERMISSION_DENIED, 'User deletion operations require JWT authentication. Please reconnect using vikunja_auth.connect with JWT authentication.');
+        }
+        const subcommand = args.subcommand;
+        (0, read_only_1.assertWriteAllowed)('vikunja_user_deletion', subcommand);
+        logger_1.logger.debug('User deletion tool called', { subcommand });
+        try {
+            switch (subcommand) {
+                case 'request': {
+                    if (args.confirm !== true) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Requesting account deletion starts an irreversible process: Vikunja will email a confirmation token, and confirming it schedules the account for deletion. Pass confirm: true to proceed.');
+                    }
+                    if (!args.password) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'password is required for the request subcommand');
+                    }
+                    const result = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'POST', '/user/deletion/request', { password: args.password });
+                    logger_1.logger.info('Requested account deletion');
+                    const aorpResult = (0, response_factory_1.createAorpResponse)('request', 'Account deletion requested. Vikunja has emailed a confirmation token — pass it to the confirm subcommand (with confirm: true) to proceed. The deletion is irreversible once confirmed; use the cancel subcommand beforehand to abort.', { serverMessage: result?.message ?? null }, { success: true });
+                    return { content: [{ type: 'text', text: aorpResult.content }] };
+                }
+                case 'confirm': {
+                    if (args.confirm !== true) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Confirming account deletion is irreversible: the account is scheduled for deletion once confirmed. Pass confirm: true to proceed.');
+                    }
+                    if (!args.token) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'token is required for the confirm subcommand (the token Vikunja emailed after request)');
+                    }
+                    const result = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'POST', '/user/deletion/confirm', { token: args.token });
+                    logger_1.logger.info('Confirmed account deletion');
+                    const aorpResult = (0, response_factory_1.createAorpResponse)('confirm', 'Account deletion confirmed. The account is now scheduled for deletion; this is irreversible.', { serverMessage: result?.message ?? null }, { success: true });
+                    return { content: [{ type: 'text', text: aorpResult.content }] };
+                }
+                case 'cancel': {
+                    if (!args.password) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'password is required for the cancel subcommand');
+                    }
+                    const result = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'POST', '/user/deletion/cancel', { password: args.password });
+                    logger_1.logger.info('Canceled account deletion request');
+                    const aorpResult = (0, response_factory_1.createAorpResponse)('cancel', 'Account deletion request canceled. The account will not be deleted.', { serverMessage: result?.message ?? null }, { success: true });
+                    return { content: [{ type: 'text', text: aorpResult.content }] };
+                }
+                default:
+                    throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, `Unknown subcommand: ${subcommand}`);
+            }
+        }
+        catch (error) {
+            logger_1.logger.error('User deletion operation failed', { error, subcommand });
+            if (error instanceof types_1.MCPError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                throw new types_1.MCPError(types_1.ErrorCode.API_ERROR, `User deletion operation failed: ${error.message}`);
+            }
+            throw new types_1.MCPError(types_1.ErrorCode.INTERNAL_ERROR, 'An unexpected error occurred during user deletion operation');
+        }
+    });
+}
+//# sourceMappingURL=user-deletion.js.map

package/dist/tools/user-deletion.js.map

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

package/dist/tools/users.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Users Tool
+ * Handles user operations for Vikunja
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AuthManager } from '../auth/AuthManager';
+import type { VikunjaClientFactory } from '../client/VikunjaClientFactory';
+export declare function registerUsersTool(server: McpServer, authManager: AuthManager, _clientFactory?: VikunjaClientFactory): void;
+//# sourceMappingURL=users.d.ts.map

package/dist/tools/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/tools/users.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAoH3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAkd1H"}

package/dist/tools/users.js

@@ -0,0 +1,418 @@
+"use strict";
+/**
+ * Users Tool
+ * Handles user operations for Vikunja
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUsersTool = registerUsersTool;
+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 auth_error_handler_1 = require("../utils/auth-error-handler");
+const response_factory_1 = require("../utils/response-factory");
+const vikunja_rest_1 = require("../utils/vikunja-rest");
+const read_only_1 = require("../utils/read-only");
+/**
+ * The exact set of avatar provider strings the Vikunja server accepts.
+ * The OpenAPI spec documents `avatar_provider` as a freeform `string` with
+ * valid values only spelled out in prose, so this list is instead sourced
+ * from the server's own validation in the Vikunja source
+ * (`~/Projects/vikunja/pkg/user/user.go`, the avatar-provider check ahead of
+ * `ErrInvalidAvatarProvider`). Validating client-side against the same list
+ * gives a clear Zod error instead of a round-trip 400.
+ */
+const AVATAR_PROVIDERS = [
+    'gravatar',
+    'upload',
+    'initials',
+    'marble',
+    'ldap',
+    'openid',
+    'default',
+];
+/**
+ * Type guard to check if an object is a valid user structure
+ */
+function isUserObject(obj) {
+    return obj !== null && typeof obj === 'object' && !Array.isArray(obj);
+}
+/**
+ * Safely transforms a raw REST user object (v1.UserWithSettings or
+ * user.User) to our extended User interface
+ */
+function transformUser(rawUser) {
+    if (!isUserObject(rawUser)) {
+        throw new Error('Invalid user data received');
+    }
+    const user = rawUser;
+    const safeString = (value) => {
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        if (value !== null && typeof value === 'object') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return '[object Object]';
+            }
+        }
+        return value !== null && value !== undefined && typeof value !== 'object' && typeof value !== 'boolean' ?
+            (typeof value === 'string' || typeof value === 'number' ? value.toString() : '') : '';
+    };
+    // GET /user returns v1.UserWithSettings: language, timezone, week_start,
+    // frontend_settings, email_reminders_enabled, overdue_tasks_reminders_enabled,
+    // overdue_tasks_reminders_time and name are nested under a `settings`
+    // sub-object (models.UserGeneralSettings), NOT flat on the top-level user
+    // object. (id, username, email, created, updated remain top-level.)
+    // Search results (GET /users) return plain user.User with no `settings` key,
+    // so this safely falls back to an empty object for those.
+    const settings = isUserObject(user.settings) ? user.settings : {};
+    const result = {
+        id: Number(user.id) || 0,
+        username: safeString(user.username),
+        frontend_settings: (settings.frontend_settings && typeof settings.frontend_settings === 'object') ? settings.frontend_settings : {},
+    };
+    const userResult = {
+        id: result.id,
+        username: result.username,
+        frontend_settings: result.frontend_settings,
+        ...(user.email ? { email: safeString(user.email) } : {}),
+        ...(settings.name ? { name: safeString(settings.name) } : {}),
+        ...(user.created ? { created: safeString(user.created) } : {}),
+        ...(user.updated ? { updated: safeString(user.updated) } : {}),
+        ...(settings.language ? { language: safeString(settings.language) } : {}),
+        ...(settings.timezone ? { timezone: safeString(settings.timezone) } : {}),
+        ...(settings.week_start !== undefined ? { week_start: Number(settings.week_start) } : {}),
+        ...(settings.email_reminders_enabled !== undefined ? { email_reminders_enabled: Boolean(settings.email_reminders_enabled) } : {}),
+        ...(settings.overdue_tasks_reminders_enabled !== undefined ? { overdue_tasks_reminders_enabled: Boolean(settings.overdue_tasks_reminders_enabled) } : {}),
+        ...(settings.overdue_tasks_reminders_time ? { overdue_tasks_reminders_time: safeString(settings.overdue_tasks_reminders_time) } : {}),
+    };
+    return userResult;
+}
+function registerUsersTool(server, authManager, _clientFactory) {
+    server.tool('vikunja_users', (0, read_only_1.withReadOnlyNote)('vikunja_users', "Manage user profiles, search users, and update user settings. Use the 'timezones' subcommand to fetch this Vikunja instance's list of valid IANA time zone names before calling 'update-settings' with a timezone value — the server rejects unrecognized zone names, and the valid set is instance-dependent (depends on the OS Vikunja runs on). 'get-avatar'/'set-avatar' read and write the avatar *provider* setting (JSON — one of gravatar/upload/initials/marble/ldap/openid/default), not image bytes; 'upload-avatar' uploads an actual image file and only takes effect once the provider is 'upload' (which it also sets as a side effect)."), {
+        // Operation type
+        subcommand: zod_1.z.enum([
+            'current',
+            'search',
+            'settings',
+            'update-settings',
+            'timezones',
+            'get-avatar',
+            'set-avatar',
+            'upload-avatar',
+        ]),
+        // Search parameters
+        search: zod_1.z.string().optional(),
+        page: zod_1.z.number().positive().optional(),
+        perPage: zod_1.z.number().positive().max(100).optional(),
+        // Settings update fields
+        name: zod_1.z.string().optional(),
+        language: zod_1.z.string().optional(),
+        timezone: zod_1.z.string().optional(),
+        weekStart: zod_1.z.number().min(0).max(6).optional(),
+        frontendSettings: zod_1.z.record(zod_1.z.unknown()).optional(),
+        // Notification preferences
+        emailRemindersEnabled: zod_1.z.boolean().optional(),
+        overdueTasksRemindersEnabled: zod_1.z.boolean().optional(),
+        overdueTasksRemindersTime: zod_1.z.string().optional(),
+        // Avatar settings (get-avatar/set-avatar/upload-avatar)
+        avatarProvider: zod_1.z.enum(AVATAR_PROVIDERS).optional(),
+        // Local file to upload, same contract as `vikunja_tasks attach`:
+        // `filePath` (absolute path readable by the MCP server process) takes
+        // precedence over `fileContent` (base64) when both are given.
+        filePath: zod_1.z.string().optional(),
+        fileContent: zod_1.z.string().optional(),
+        filename: zod_1.z.string().optional(),
+    }, (0, read_only_1.getToolAnnotations)('vikunja_users'), async (args) => {
+        if (!authManager.isAuthenticated()) {
+            throw new types_1.MCPError(types_1.ErrorCode.AUTH_REQUIRED, 'Authentication required. Please use vikunja_auth.connect first.');
+        }
+        // User operations require JWT authentication
+        if (authManager.getAuthType() !== 'jwt') {
+            throw new types_1.MCPError(types_1.ErrorCode.PERMISSION_DENIED, 'User operations require JWT authentication. Please reconnect using vikunja_auth.connect with JWT authentication.');
+        }
+        (0, read_only_1.assertWriteAllowed)('vikunja_users', args.subcommand);
+        try {
+            const subcommand = args.subcommand;
+            switch (subcommand) {
+                case 'current': {
+                    const rawUser = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', '/user');
+                    // Safely transform the raw REST user response to our extended User
+                    // interface. Extended properties may not be available from all Vikunja API versions
+                    const enhancedUser = transformUser(rawUser);
+                    const response = (0, types_1.createStandardResponse)('get-current-user', 'Current user retrieved successfully', { user: enhancedUser });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'search': {
+                    const params = {};
+                    if (args.search !== undefined)
+                        params.s = args.search;
+                    if (args.page !== undefined)
+                        params.page = args.page;
+                    if (args.perPage !== undefined)
+                        params.per_page = args.perPage;
+                    // GET /users only accepts the `s` query param per the spec (no
+                    // page/per_page) — the legacy client's UserSearchParams type includes
+                    // pagination fields the real endpoint doesn't support, so the
+                    // request only ever sent `s` server-side even before this
+                    // migration. `params`/`paramsMetadata` still record whatever the
+                    // caller passed for the response metadata below.
+                    const query = new URLSearchParams();
+                    if (params.s !== undefined)
+                        query.set('s', params.s);
+                    const queryString = query.toString();
+                    const usersResult = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', `/users${queryString ? `?${queryString}` : ''}`);
+                    const users = usersResult ?? [];
+                    const paramsMetadata = {};
+                    if (args.search !== undefined)
+                        paramsMetadata.search = args.search;
+                    if (args.page !== undefined)
+                        paramsMetadata.page = args.page;
+                    if (args.perPage !== undefined)
+                        paramsMetadata.perPage = args.perPage;
+                    const response = (0, types_1.createStandardResponse)('search-users', `Found ${users.length} users`, { users: users.map(transformUser) }, { count: users.length, params: paramsMetadata });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'settings': {
+                    // Get current user first to get their settings
+                    const rawUser = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', '/user');
+                    // Safely transform the raw REST user response to our extended User interface
+                    const user = transformUser(rawUser);
+                    // Handle the actual API response format gracefully
+                    const settings = {
+                        id: user.id,
+                        username: user.username,
+                        ...(user.email && { email: user.email }),
+                        ...(user.name && { name: user.name }),
+                        ...(user.language && { language: user.language }),
+                        ...(user.timezone && { timezone: user.timezone }),
+                        ...(user.week_start !== undefined && { weekStart: user.week_start }),
+                        frontendSettings: user.frontend_settings || {},
+                        ...(user.email_reminders_enabled !== undefined && { emailRemindersEnabled: user.email_reminders_enabled }),
+                        ...(user.overdue_tasks_reminders_enabled !== undefined && { overdueTasksRemindersEnabled: user.overdue_tasks_reminders_enabled }),
+                        ...(user.overdue_tasks_reminders_time && { overdueTasksRemindersTime: user.overdue_tasks_reminders_time }),
+                    };
+                    const response = (0, types_1.createStandardResponse)('get-user-settings', 'User settings retrieved successfully', { settings });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'update-settings': {
+                    if (!args.name &&
+                        !args.language &&
+                        !args.timezone &&
+                        args.weekStart === undefined &&
+                        !args.frontendSettings &&
+                        args.emailRemindersEnabled === undefined &&
+                        args.overdueTasksRemindersEnabled === undefined &&
+                        args.overdueTasksRemindersTime === undefined) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'At least one setting field is required');
+                    }
+                    const settings = {};
+                    const affectedFields = [];
+                    if (args.name !== undefined) {
+                        settings.name = args.name;
+                        affectedFields.push('name');
+                    }
+                    if (args.language !== undefined) {
+                        settings.language = args.language;
+                        affectedFields.push('language');
+                    }
+                    if (args.timezone !== undefined) {
+                        settings.timezone = args.timezone;
+                        affectedFields.push('timezone');
+                    }
+                    if (args.weekStart !== undefined) {
+                        settings.week_start = args.weekStart;
+                        affectedFields.push('weekStart');
+                    }
+                    if (args.frontendSettings !== undefined) {
+                        settings.frontend_settings = args.frontendSettings;
+                        affectedFields.push('frontendSettings');
+                    }
+                    if (args.emailRemindersEnabled !== undefined) {
+                        settings.email_reminders_enabled = args.emailRemindersEnabled;
+                        affectedFields.push('emailRemindersEnabled');
+                    }
+                    if (args.overdueTasksRemindersEnabled !== undefined) {
+                        settings.overdue_tasks_reminders_enabled = args.overdueTasksRemindersEnabled;
+                        affectedFields.push('overdueTasksRemindersEnabled');
+                    }
+                    if (args.overdueTasksRemindersTime !== undefined) {
+                        settings.overdue_tasks_reminders_time = args.overdueTasksRemindersTime;
+                        affectedFields.push('overdueTasksRemindersTime');
+                    }
+                    await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'POST', '/user/settings/general', settings);
+                    // Get updated user info
+                    const rawUpdatedUser = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', '/user');
+                    // Safely transform the raw REST user response to our extended User interface
+                    const updatedUser = transformUser(rawUpdatedUser);
+                    const response = (0, types_1.createStandardResponse)('update-user-settings', 'User settings updated successfully', { user: updatedUser }, { affectedFields });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'timezones': {
+                    // GET /user/timezones. Not exposed via the legacy client's client
+                    // (all new HTTP calls go through vikunjaRestRequest per
+                    // docs/ENDPOINT-PLAYBOOK.md §3). The instance-dependent list of
+                    // valid IANA time zone names this call returns is exactly what
+                    // 'update-settings'' timezone argument needs to be validated
+                    // against before being sent to POST /user/settings/general —
+                    // Vikunja rejects unrecognized zone names there.
+                    const timezones = (await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', '/user/timezones')) ?? [];
+                    const response = (0, types_1.createStandardResponse)('get-user-timezones', `Retrieved ${timezones.length} available time zones`, { timezones }, { count: timezones.length });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'get-avatar': {
+                    // GET /user/settings/avatar returns v1.UserAvatarProvider
+                    // ({avatar_provider}) — JSON, not image bytes. See the type
+                    // comment above and docs/ENDPOINT-TAIL-RETRIAGE.md G5.
+                    const raw = await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'GET', '/user/settings/avatar');
+                    const avatarProvider = raw?.avatar_provider ?? '';
+                    const response = (0, types_1.createStandardResponse)('get-avatar-provider', 'Avatar provider retrieved successfully', { avatarProvider });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'set-avatar': {
+                    if (!args.avatarProvider) {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, `set-avatar requires avatarProvider (one of: ${AVATAR_PROVIDERS.join(', ')})`);
+                    }
+                    // POST /user/settings/avatar, body v1.UserAvatarProvider. Zod's
+                    // enum check above already rejects anything outside
+                    // AVATAR_PROVIDERS before the handler runs.
+                    await (0, vikunja_rest_1.vikunjaRestRequest)(authManager, 'POST', '/user/settings/avatar', { avatar_provider: args.avatarProvider });
+                    const response = (0, types_1.createStandardResponse)('set-avatar-provider', `Avatar provider set to '${args.avatarProvider}'` +
+                        (args.avatarProvider === 'upload'
+                            ? " — call 'upload-avatar' with a file to complete the switch."
+                            : ''), { avatarProvider: args.avatarProvider });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                case 'upload-avatar': {
+                    // PUT /user/settings/avatar/upload, multipart/form-data, field
+                    // name `avatar` (single file). This endpoint ALSO sets the
+                    // avatar provider to 'upload' as a side effect on the server
+                    // (see the Vikunja source's UploadAvatar handler) — the upload
+                    // only actually shows up once the provider is 'upload', which
+                    // this call itself guarantees going forward, but a *prior*
+                    // 'gravatar'/'initials'/etc. provider is silently overwritten by
+                    // it. Same file-input contract as `vikunja_tasks attach`:
+                    // `filePath` (server-local path) or `fileContent` (base64),
+                    // `filePath` wins when both are given.
+                    const { filePath, fileContent, filename } = args;
+                    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, `upload-avatar: 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, 'upload-avatar: decoded fileContent is empty (not valid base64 or empty input)');
+                        }
+                        bytes = decoded;
+                        name = filename || 'avatar.png';
+                        source = 'fileContent';
+                    }
+                    else {
+                        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'upload-avatar 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('avatar', new Blob([bytes]), name);
+                    const data = await (0, vikunja_rest_1.vikunjaRestMultipartRequest)(authManager, 'PUT', '/user/settings/avatar/upload', form);
+                    const response = (0, types_1.createStandardResponse)('upload-avatar', `Avatar uploaded (${bytes.length} bytes) and provider set to 'upload'`, { filename: name, bytes: bytes.length, source, response: data });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: (0, response_factory_1.formatAorpAsMarkdown)(response),
+                            },
+                        ],
+                    };
+                }
+                default:
+                    throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, `Invalid subcommand: ${String(subcommand)}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof types_1.MCPError) {
+                // A REST-layer 401/403 on a user endpoint is the documented
+                // Vikunja API quirk (docs/API_NOTES.md "User Endpoint
+                // Authentication"): the same token that works everywhere else can
+                // be rejected on `/user`/`/users`. Route it through the same
+                // friendly auth-error translation legacy-client-sourced exceptions
+                // used to get — `vikunjaRestRequest` throws `MCPError` with the
+                // HTTP status under `details.statusCode`, not a `.message` string
+                // `handleAuthError`'s pattern matching recognizes, so this has to
+                // be detected structurally rather than by message content.
+                const statusCode = error.details?.statusCode;
+                if (statusCode === 401 || statusCode === 403) {
+                    (0, auth_error_handler_1.handleAuthError)(new Error(`${statusCode} ${error.message}`), `user.${args.subcommand}`, `User operation error: ${error.message}`);
+                }
+                throw error;
+            }
+            // Use consistent auth error handling
+            (0, auth_error_handler_1.handleAuthError)(error, `user.${args.subcommand}`, `User operation error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+//# sourceMappingURL=users.js.map