vikunja-mcp-ng 0.4.0

package/dist/tools/projects/permission.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Shared permission-level resolution for project sharing operations.
+ *
+ * The Vikunja API encodes project permission levels as a small integer
+ * (0 = Read, 1 = Write, 2 = Admin) — `models.Permission` in the vendored
+ * OpenAPI spec — on every sharing-related endpoint: link shares
+ * (`models.LinkSharing.permission`), direct user shares
+ * (`models.ProjectUser.permission`), and direct team shares
+ * (`models.TeamProject.permission`). MCP tool callers may supply either the
+ * numeric value directly or one of the friendly string aliases (`'read'` /
+ * `'write'` / `'admin'`); this resolves either form to the numeric value the
+ * API expects, with one shared set of validation rules used everywhere a
+ * sharing permission is accepted — link shares, direct user shares, and
+ * direct team shares alike.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePermission = resolvePermission;
+const types_1 = require("../../types");
+const PERMISSION_NAME_TO_VALUE = {
+    read: 0,
+    write: 1,
+    admin: 2,
+};
+/**
+ * Resolves a caller-supplied permission (string alias or numeric value) to
+ * the numeric `models.Permission` value the Vikunja API expects.
+ *
+ * @throws MCPError (VALIDATION_ERROR) when `right` is missing, an
+ *         unrecognized string, an out-of-range number, or neither a string
+ *         nor a number.
+ */
+function resolvePermission(right) {
+    if (right === undefined) {
+        throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Share right is required');
+    }
+    if (typeof right === 'string') {
+        const normalized = right.trim().toLowerCase();
+        const resolved = PERMISSION_NAME_TO_VALUE[normalized];
+        if (resolved === undefined) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Share right must be one of: read, write, admin');
+        }
+        return resolved;
+    }
+    if (typeof right === 'number') {
+        if (right !== 0 && right !== 1 && right !== 2) {
+            throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Invalid permission level. Use: 0=Read, 1=Write, 2=Admin');
+        }
+        return right;
+    }
+    throw new types_1.MCPError(types_1.ErrorCode.VALIDATION_ERROR, 'Share right must be a string or number');
+}
+//# sourceMappingURL=permission.js.map

package/dist/tools/projects/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../../src/tools/projects/permission.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAoBH,8CA4BC;AA9CD,uCAAkD;AAIlD,MAAM,wBAAwB,GAA8B;IAC1D,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;CACT,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,iBAAiB,CAAC,KAAkC;IAClE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,gBAAQ,CAAC,iBAAS,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;IAC5E,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,wBAAwB,CAAC,UAAU,CAAC,CAAC;QACtD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,gBAAQ,CAChB,iBAAS,CAAC,gBAAgB,EAC1B,gDAAgD,CACjD,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,gBAAQ,CAChB,iBAAS,CAAC,gBAAgB,EAC1B,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,gBAAQ,CAAC,iBAAS,CAAC,gBAAgB,EAAE,wCAAwC,CAAC,CAAC;AAC3F,CAAC"}

package/dist/tools/projects/response-formatter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Project Response Formatter Module
+ * Handles AORP response creation and formatting for project operations
+ */
+import type { ResponseMetadata } from '../../types/responses';
+import type { AorpFactoryResult } from '../../types';
+import type { components } from '../../types/generated/vikunja-openapi';
+type Project = components['schemas']['models.Project'];
+/**
+ * Creates an AORP response for project operations
+ */
+export declare function createProjectResponse(operation: string, message: string, _data: unknown, _metadata?: Partial<ResponseMetadata>, _verbosity?: string, _useOptimizedFormat?: boolean, _useAorp?: boolean): AorpFactoryResult;
+/**
+ * Creates a success response for project operations
+ */
+export declare function createProjectSuccessResponse(operation: string, data: unknown, options?: {
+    message?: string;
+    verbosity?: string;
+    useOptimizedFormat?: boolean;
+    useAorp?: boolean;
+    metadata?: Partial<ResponseMetadata>;
+}): AorpFactoryResult;
+/**
+ * Creates a project list response with pagination metadata
+ *
+ * GET /projects returns a bare array with no total-count metadata in the
+ * response body (the server does not report total items or total pages),
+ * so this cannot honestly claim to know `totalPages`/`totalItems`. Instead
+ * `hasMore` is derived from whether a full page was returned: if fewer than
+ * `perPage` items came back, this is the last page.
+ */
+export declare function createProjectListResponse(projects: unknown[], currentPage: number, perPage: number, options?: {
+    verbosity?: string;
+    useOptimizedFormat?: boolean;
+    useAorp?: boolean;
+}): AorpFactoryResult;
+/**
+ * Creates a project tree response with hierarchy metadata
+ */
+export declare function createProjectTreeResponse(treeData: unknown, depth: number, totalNodes: number, options?: {
+    verbosity?: string;
+    useOptimizedFormat?: boolean;
+    useAorp?: boolean;
+}): AorpFactoryResult;
+/**
+ * Creates a breadcrumb response for project hierarchy navigation
+ */
+export declare function createBreadcrumbResponse(breadcrumb: Project[], options?: {
+    verbosity?: string;
+    useOptimizedFormat?: boolean;
+    useAorp?: boolean;
+}): AorpFactoryResult;
+export {};
+//# sourceMappingURL=response-formatter.d.ts.map

package/dist/tools/projects/response-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-formatter.d.ts","sourceRoot":"","sources":["../../../src/tools/projects/response-formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAKxE,KAAK,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAC;AAUvD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,OAAO,CAAC,gBAAgB,CAAM,EACzC,UAAU,CAAC,EAAE,MAAM,EACnB,mBAAmB,CAAC,EAAE,OAAO,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,iBAAiB,CAqDnB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjC,GACL,iBAAiB,CAkBnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,iBAAiB,CAwBnB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,iBAAiB,CAoBnB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,OAAO,EAAE,EACrB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,iBAAiB,CAmBnB"}

package/dist/tools/projects/response-formatter.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Project Response Formatter Module
+ * Handles AORP response creation and formatting for project operations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectResponse = createProjectResponse;
+exports.createProjectSuccessResponse = createProjectSuccessResponse;
+exports.createProjectListResponse = createProjectListResponse;
+exports.createProjectTreeResponse = createProjectTreeResponse;
+exports.createBreadcrumbResponse = createBreadcrumbResponse;
+const response_factory_1 = require("../../utils/response-factory");
+const base_1 = require("../../transforms/base");
+/**
+ * Creates an AORP response for project operations
+ */
+function createProjectResponse(operation, message, _data, _metadata = {}, _verbosity, _useOptimizedFormat, _useAorp) {
+    // An explicit per-call verbosity always takes precedence over the
+    // VIKUNJA_RESPONSE_VERBOSITY environment default.
+    const selectedVerbosity = _verbosity ?? (0, base_1.getDefaultVerbosity)();
+    // Cast data to ResponseData for type compatibility
+    const responseData = _data;
+    // Use simple response format
+    const simpleAorpResult = (0, response_factory_1.createAorpResponse)(operation, message, responseData, {
+        success: true,
+        metadata: {
+            verbosity: selectedVerbosity,
+        },
+    });
+    // Add transformation property for compatibility with AorpFactoryResult
+    const mockOptimizedResponse = {
+        success: true,
+        operation,
+        message,
+        data: responseData,
+        metadata: {
+            timestamp: new Date().toISOString(),
+        }
+    };
+    return {
+        response: simpleAorpResult,
+        transformation: {
+            originalResponse: mockOptimizedResponse,
+            context: {
+                operation,
+                success: true,
+                dataSize: JSON.stringify(responseData).length,
+                processingTime: 0,
+                verbosity: selectedVerbosity,
+                verbosityLevel: 'simple',
+                complexityFactors: {
+                    dataSize: JSON.stringify(responseData).length >= 1024,
+                    hasWarnings: false,
+                    hasErrors: false,
+                    isBulkOperation: false,
+                    isPartialSuccess: false,
+                    custom: {}
+                }
+            },
+            metrics: {
+                aorpProcessingTime: 0,
+                totalTime: 0
+            }
+        }
+    };
+}
+/**
+ * Creates a success response for project operations
+ */
+function createProjectSuccessResponse(operation, data, options = {}) {
+    const { message = `${operation} operation completed successfully`, verbosity, useOptimizedFormat, useAorp, metadata = {} } = options;
+    return createProjectResponse(operation, message, data, metadata, verbosity, useOptimizedFormat, useAorp);
+}
+/**
+ * Creates a project list response with pagination metadata
+ *
+ * GET /projects returns a bare array with no total-count metadata in the
+ * response body (the server does not report total items or total pages),
+ * so this cannot honestly claim to know `totalPages`/`totalItems`. Instead
+ * `hasMore` is derived from whether a full page was returned: if fewer than
+ * `perPage` items came back, this is the last page.
+ */
+function createProjectListResponse(projects, currentPage, perPage, options = {}) {
+    const hasMore = perPage > 0 && projects.length >= perPage;
+    const metadata = {
+        pagination: {
+            page: currentPage,
+            perPage,
+            hasMore,
+            nextPage: hasMore ? currentPage + 1 : undefined,
+            prevPage: currentPage > 1 ? currentPage - 1 : undefined,
+        },
+    };
+    const projectWord = projects.length === 1 ? 'project' : 'projects';
+    const message = `Retrieved ${projects.length} ${projectWord}`;
+    return createProjectSuccessResponse('list_projects', projects, {
+        message,
+        ...options,
+        metadata
+    });
+}
+/**
+ * Creates a project tree response with hierarchy metadata
+ */
+function createProjectTreeResponse(treeData, depth, totalNodes, options = {}) {
+    const metadata = {
+        hierarchy: {
+            depth,
+            totalNodes,
+            maxDepth: 10, // From MAX_PROJECT_DEPTH
+        },
+        totalProjects: totalNodes,
+    };
+    const tree = treeData;
+    return createProjectSuccessResponse('get-project-tree', { tree: tree.length === 1 ? tree[0] : tree }, {
+        message: `Retrieved project tree with ${totalNodes} nodes at depth ${depth}`,
+        ...options,
+        metadata
+    });
+}
+/**
+ * Creates a breadcrumb response for project hierarchy navigation
+ */
+function createBreadcrumbResponse(breadcrumb, options = {}) {
+    const metadata = {
+        navigation: {
+            breadcrumbLength: breadcrumb.length,
+            hasPath: breadcrumb.length > 0,
+        },
+        path: breadcrumb.map((p) => p.title).join(' > ') || 'Root',
+        depth: breadcrumb.length,
+    };
+    return createProjectSuccessResponse('get-project-breadcrumb', { breadcrumb }, {
+        message: `Retrieved breadcrumb path with ${breadcrumb.length} items`,
+        ...options,
+        metadata
+    });
+}
+//# sourceMappingURL=response-formatter.js.map

package/dist/tools/projects/response-formatter.js.map

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

package/dist/tools/projects/sharing-access.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Direct project sharing with users & teams.
+ *
+ * Distinct from `sharing.ts` (anonymous/password link shares): this module
+ * grants access to specific, named users and teams. Entirely new coverage —
+ * this MCP server previously exposed no way to share a project with a user
+ * or team directly (see docs/API-COVERAGE.md, HIGH finding). Built
+ * direct-REST per the Wave D playbook (docs/ENDPOINT-PLAYBOOK.md); there is
+ * no existing legacy client call site here to migrate.
+ *
+ * Endpoints (verified against docs/vikunja-openapi.json — note the body
+ * field is `permission`, NOT the legacy client's stale `right`):
+ *   - GET    /projects/{id}/users                list users on a project
+ *   - PUT    /projects/{id}/users                 add a user to a project
+ *   - POST   /projects/{projectID}/users/{userID} update a user's permission
+ *   - DELETE /projects/{projectID}/users/{userID} remove a user
+ *   - GET    /projects/{id}/teams                 list teams on a project
+ *   - PUT    /projects/{id}/teams                 add a team to a project
+ *   - POST   /projects/{projectID}/teams/{teamID} update a team's permission
+ *   - DELETE /projects/{projectID}/teams/{teamID} remove a team
+ *   - GET    /projects/{id}/projectusers           project-scoped user search
+ *   - GET    /users                                global user search (by username/name/email)
+ *   - GET    /teams                                team search (by name)
+ *
+ * Composite-first (docs/ENDPOINT-PLAYBOOK.md §1): `share-with-user` and
+ * `share-with-team` are the headline subcommands — they take a username or
+ * team name plus a permission level, resolve it to an id internally, add
+ * it, then verify the grant actually landed, using `CompositeOperation`
+ * (src/utils/composite-operation.ts) for the multi-step write with opt-in
+ * atomic rollback (remove-on-failure). Primitives (list/add/update/remove
+ * by numeric id) remain available for fine-grained control. `list-members`
+ * is a read composite answering "who has access to this project" (users +
+ * teams + link shares) in one call.
+ */
+import type { AuthManager } from '../../auth/AuthManager';
+import { type PermissionInput } from './permission';
+type McpResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export interface ListProjectUsersArgs {
+    projectId: number;
+    search?: string;
+    page?: number;
+    perPage?: number;
+    sessionId?: string;
+}
+/** Lists the users who have direct access to a project, with their permission. */
+export declare function listProjectUsers(args: ListProjectUsersArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface SearchProjectUsersArgs {
+    projectId: number;
+    search?: string;
+    sessionId?: string;
+}
+/** Project-scoped user search (`GET /projects/{id}/projectusers`) — for finding a user to share with, distinct from the global `/users` search. */
+export declare function searchProjectUsers(args: SearchProjectUsersArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface AddProjectUserArgs {
+    projectId: number;
+    username: string;
+    right: PermissionInput;
+    sessionId?: string;
+}
+/** Grants a named user direct access to a project (`PUT /projects/{id}/users`, body `{username, permission}`). */
+export declare function addProjectUser(args: AddProjectUserArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface UpdateProjectUserPermissionArgs {
+    projectId: number;
+    userId: number;
+    right: PermissionInput;
+    sessionId?: string;
+}
+/** Updates a user's permission on a project (`POST /projects/{projectID}/users/{userID}`, body `{permission}`). */
+export declare function updateProjectUserPermission(args: UpdateProjectUserPermissionArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface RemoveProjectUserArgs {
+    projectId: number;
+    userId: number;
+    sessionId?: string;
+}
+/** Removes a user's direct access to a project (`DELETE /projects/{projectID}/users/{userID}`). */
+export declare function removeProjectUser(args: RemoveProjectUserArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface ListProjectTeamsArgs {
+    projectId: number;
+    search?: string;
+    page?: number;
+    perPage?: number;
+    sessionId?: string;
+}
+/** Lists the teams with direct access to a project, with their permission. */
+export declare function listProjectTeams(args: ListProjectTeamsArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface AddProjectTeamArgs {
+    projectId: number;
+    teamId: number;
+    right: PermissionInput;
+    sessionId?: string;
+}
+/** Grants a team direct access to a project (`PUT /projects/{id}/teams`, body `{team_id, permission}`). */
+export declare function addProjectTeam(args: AddProjectTeamArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface UpdateProjectTeamPermissionArgs {
+    projectId: number;
+    teamId: number;
+    right: PermissionInput;
+    sessionId?: string;
+}
+/** Updates a team's permission on a project (`POST /projects/{projectID}/teams/{teamID}`, body `{permission}`). */
+export declare function updateProjectTeamPermission(args: UpdateProjectTeamPermissionArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface RemoveProjectTeamArgs {
+    projectId: number;
+    teamId: number;
+    sessionId?: string;
+}
+/** Removes a team's direct access to a project (`DELETE /projects/{projectID}/teams/{teamID}`). */
+export declare function removeProjectTeam(args: RemoveProjectTeamArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface ShareWithUserArgs {
+    projectId: number;
+    username: string;
+    right: PermissionInput;
+    /**
+     * Opt into atomic rollback: if the post-add verification fails, the grant
+     * is removed. Default `false` (best-effort) — see
+     * docs/ENDPOINT-PLAYBOOK.md §5 / `CompositeOperation`'s design rule (a).
+     * This is best-effort compensation against a live API, not a real
+     * transaction: side effects of the `add-user` step (e.g. any webhook it
+     * fires) are not undone by the rollback.
+     */
+    atomic?: boolean;
+    sessionId?: string;
+}
+/**
+ * Composite: share a project with a user by **username**. Resolves the
+ * username to a user id via the global user search (`GET /users?s=`), adds
+ * the user to the project, then verifies the grant actually landed by
+ * re-reading the project's user list. Uses `CompositeOperation` so a failed
+ * verification can (opt-in, `atomic: true`) remove the just-added grant
+ * rather than leaving a silently-unverified share in place.
+ */
+export declare function shareProjectWithUser(args: ShareWithUserArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface ShareWithTeamArgs {
+    projectId: number;
+    teamName: string;
+    right: PermissionInput;
+    /** Opt into atomic rollback — see `ShareWithUserArgs.atomic`. */
+    atomic?: boolean;
+    sessionId?: string;
+}
+/**
+ * Composite: share a project with a team by **name**. Resolves the team
+ * name to a team id via `GET /teams?s=`, adds the team to the project, then
+ * verifies the grant landed by re-reading the project's team list. Same
+ * `CompositeOperation` + opt-in atomic rollback shape as `share-with-user`.
+ */
+export declare function shareProjectWithTeam(args: ShareWithTeamArgs, authManager: AuthManager): Promise<McpResponse>;
+export interface ListMembersArgs {
+    projectId: number;
+    sessionId?: string;
+}
+/**
+ * Read composite: answers "who has access to this project" in one call —
+ * direct users, direct teams, and link shares — instead of making the
+ * caller issue three separate list calls. Purely a read; no
+ * `CompositeOperation` needed since there is nothing to compensate.
+ */
+export declare function listProjectMembers(args: ListMembersArgs, authManager: AuthManager): Promise<McpResponse>;
+export {};
+//# sourceMappingURL=sharing-access.d.ts.map

package/dist/tools/projects/sharing-access.d.ts.map

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