@kaneo/mcp 0.1.10 → 0.1.12

package/README.md

@@ -8,7 +8,7 @@ It runs over stdio, signs in with Kaneo's device flow, and then calls the Kaneo
 
 ## Prerequisites
 
-- Node.js 20+
+- Node.js 24+
 - A running Kaneo API (for example `http://localhost:1337`) and web app (for device approval UI).
 
 Kaneo allows `kaneo-cli` and `kaneo-mcp` by default, so you usually do not need extra server configuration.
@@ -118,7 +118,7 @@ For headless or sandboxed environments where opening a browser is impractical, s
 - Session: `whoami`, `list_workspaces`, `list_workspace_members`, `list_notifications`
 - Search: `search`
 - Projects: `list_projects`, `get_project`, `create_project`, `update_project`, `list_project_columns`
-- Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `delete_task`, `move_task`, `update_task_status`, `update_task_assignee`, `update_task_due_date`, `list_task_activity`
+- Tasks: `list_tasks`, `get_task`, `get_task_by_ticket_id`, `create_task`, `update_task`, `delete_task`, `move_task`, `update_task_status`, `update_task_assignee`, `update_task_due_date`, `list_task_activity`
 - Time entries: `list_task_time_entries`, `get_time_entry`, `create_time_entry`, `update_time_entry`
 - Comments: `list_task_comments`, `create_task_comment`, `update_task_comment`, `delete_task_comment`
 - Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`, `delete_label`
@@ -126,6 +126,9 @@ For headless or sandboxed environments where opening a browser is impractical, s
 
 Call `list_project_columns` before setting a status: the column slugs it
 returns are the values `create_task` and `update_task_status` accept.
+Call `get_task_by_ticket_id` with a key such as `KAN-12` to retrieve one task
+without listing a project. If the same key identifies multiple accessible tasks,
+pass `workspaceId` or `projectId` to select one.
 `list_workspace_members` resolves the user IDs the assignee tools expect.
 Time entries have no delete endpoint on the API, so there is no
 `delete_time_entry` tool.

package/dist/kaneo/client.d.ts

@@ -9,6 +9,7 @@ export declare class KaneoClient {
         baseUrl: string;
         auth: AuthService;
     });
+    get usingApiKey(): boolean;
     private authorizedFetch;
     json<T = Json>(path: string, init?: RequestInit): Promise<T>;
 }

package/dist/kaneo/client.js

@@ -5,6 +5,9 @@ export class KaneoClient {
         this.baseUrl = options.baseUrl;
         this.auth = options.auth;
     }
+    get usingApiKey() {
+        return this.auth.usingApiKey;
+    }
     async authorizedFetch(path, init, didRetry = false) {
         const token = await this.auth.getAccessToken();
         const headers = new Headers(init?.headers);

package/dist/tools/register.d.ts

@@ -1,5 +1,15 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { KaneoClient } from "../kaneo/client.js";
-export declare function registerTools(server: McpServer, ctx: {
-    client: KaneoClient;
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+export type ToolClient = {
+    readonly usingApiKey?: boolean;
+    json<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+};
+export type ToolRegistrar = {
+    registerTool(name: string, config: {
+        description: string;
+        inputSchema: z.ZodObject;
+    }, callback: (args: unknown) => Promise<CallToolResult>): unknown;
+};
+export declare function registerTools(server: ToolRegistrar, ctx: {
+    client: ToolClient;
 }): void;

package/dist/tools/register.js

@@ -26,15 +26,21 @@ function run(fn) {
 }
 export function registerTools(server, ctx) {
     const { client } = ctx;
-    server.registerTool("whoami", {
-        description: "Return the current Kaneo session and user for the cached device token.",
+    const registerTool = (name, config, callback) => server.registerTool(name, config, async (args) => {
+        const parsed = config.inputSchema.safeParse(args);
+        if (!parsed.success)
+            return errorResult(z.prettifyError(parsed.error));
+        return callback(parsed.data);
+    });
+    registerTool("whoami", {
+        description: "Return the current Kaneo user for the configured authentication method.",
         inputSchema: z.object({}),
-    }, async () => run(() => client.json("/api/auth/get-session", { method: "GET" })));
-    server.registerTool("list_workspaces", {
+    }, async () => run(() => client.json(client.usingApiKey ? "/api/user/me" : "/api/auth/get-session", { method: "GET" })));
+    registerTool("list_workspaces", {
         description: "List workspaces (Better Auth organizations) the signed-in user can access.",
         inputSchema: z.object({}),
     }, async () => run(() => client.json("/api/auth/organization/list", { method: "GET" })));
-    server.registerTool("list_projects", {
+    registerTool("list_projects", {
         description: "List projects in a workspace.",
         inputSchema: z.object({
             workspaceId: nonEmptyString.describe("Workspace ID"),
@@ -51,11 +57,11 @@ export function registerTools(server, ctx) {
         }
         return run(() => client.json(`/api/project?${qs.toString()}`, { method: "GET" }));
     });
-    server.registerTool("get_project", {
+    registerTool("get_project", {
         description: "Get a single project by ID.",
         inputSchema: z.object({ id: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/project/${encodeURIComponent(args.id)}`)));
-    server.registerTool("create_project", {
+    registerTool("create_project", {
         description: "Create a project in a workspace.",
         inputSchema: z.object({
             name: nonEmptyString,
@@ -72,7 +78,7 @@ export function registerTools(server, ctx) {
             slug: args.slug,
         }),
     })));
-    server.registerTool("update_project", {
+    registerTool("update_project", {
         description: "Update project metadata (PATCH-style: only provided fields are changed).",
         inputSchema: z.object({
             id: nonEmptyString,
@@ -123,8 +129,9 @@ export function registerTools(server, ctx) {
         status: optionalNonEmptyString,
         priority: prioritySchema.optional(),
         assigneeId: optionalNonEmptyString,
-        page: z.number().int().positive().optional(),
-        limit: z.number().int().positive().optional(),
+        page: z.number().int().min(1).max(1_000_000).optional(),
+        relatedPage: z.number().int().min(1).max(1_000_000).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
         sortBy: z
             .enum(["createdAt", "priority", "dueDate", "position", "title", "number"])
             .optional(),
@@ -132,8 +139,8 @@ export function registerTools(server, ctx) {
         dueBefore: optionalIsoDateTimeSchema,
         dueAfter: optionalIsoDateTimeSchema,
     });
-    server.registerTool("list_tasks", {
-        description: "List tasks for a project (optionally filtered/sorted).",
+    registerTool("list_tasks", {
+        description: "List a bounded page of tasks for a project (50 by default, maximum 100). Use pagination.totalPages and page to retrieve the rest; filters and sorting apply before pagination. For every task page, also follow relatedPage through pagination.relatedTotalPages for complete labels, links and column metadata.",
         inputSchema: listTasksSchema,
     }, async (args) => {
         const { projectId, ...rest } = args;
@@ -148,13 +155,29 @@ export function registerTools(server, ctx) {
         const path = `/api/task/tasks/${encodeURIComponent(projectId)}${q ? `?${q}` : ""}`;
         return run(() => client.json(path, { method: "GET" }));
     });
-    server.registerTool("get_task", {
+    registerTool("get_task", {
         description: "Get a task by ID.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/task/${encodeURIComponent(args.taskId)}`, {
         method: "GET",
     })));
-    server.registerTool("create_task", {
+    registerTool("get_task_by_ticket_id", {
+        description: "Get one task by its ticket ID (project key and number, e.g. KAN-12). If multiple accessible tasks share the ID, provide workspaceId or projectId.",
+        inputSchema: z.object({
+            ticketId: nonEmptyString,
+            workspaceId: optionalNonEmptyString,
+            projectId: optionalNonEmptyString,
+        }),
+    }, async ({ ticketId, workspaceId, projectId }) => {
+        const query = new URLSearchParams();
+        if (workspaceId)
+            query.set("workspaceId", workspaceId);
+        if (projectId)
+            query.set("projectId", projectId);
+        const suffix = query.toString();
+        return run(() => client.json(`/api/task/by-ticket-id/${encodeURIComponent(ticketId)}${suffix ? `?${suffix}` : ""}`, { method: "GET" }));
+    });
+    registerTool("create_task", {
         description: "Create a task in a project.",
         inputSchema: z.object({
             projectId: nonEmptyString,
@@ -187,6 +210,22 @@ export function registerTools(server, ctx) {
             body: JSON.stringify(body),
         }));
     });
+    registerTool("duplicate_task", {
+        description: "Duplicate a task in the same project, copying its fields and labels. Pass title to rename the copy.",
+        inputSchema: z.object({
+            taskId: nonEmptyString,
+            title: optionalNonEmptyString,
+        }),
+    }, async (args) => {
+        const body = {};
+        if (args.title !== undefined) {
+            body.title = args.title;
+        }
+        return run(() => client.json(`/api/task/duplicate/${encodeURIComponent(args.taskId)}`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        }));
+    });
     const updateTaskSchema = z.object({
         taskId: nonEmptyString,
         title: optionalNonEmptyString,
@@ -199,7 +238,7 @@ export function registerTools(server, ctx) {
         dueDate: nullableOptionalIsoDateTimeSchema,
         userId: nullableOptionalNonEmptyString,
     });
-    server.registerTool("update_task", {
+    registerTool("update_task", {
         description: "Update a task (fetches current task, merges fields, then full update).",
         inputSchema: updateTaskSchema,
     }, async (args) => {
@@ -213,7 +252,7 @@ export function registerTools(server, ctx) {
             });
         });
     });
-    server.registerTool("move_task", {
+    registerTool("move_task", {
         description: "Move a task to another project (and optional column status).",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -229,7 +268,7 @@ export function registerTools(server, ctx) {
                 : {}),
         }),
     })));
-    server.registerTool("update_task_status", {
+    registerTool("update_task_status", {
         description: "Update only the status (column) of a task.",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -239,13 +278,13 @@ export function registerTools(server, ctx) {
         method: "PUT",
         body: JSON.stringify({ status: args.status }),
     })));
-    server.registerTool("list_task_comments", {
+    registerTool("list_task_comments", {
         description: "List comments on a task.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/comment/${encodeURIComponent(args.taskId)}`, {
         method: "GET",
     })));
-    server.registerTool("create_task_comment", {
+    registerTool("create_task_comment", {
         description: "Add a comment to a task.",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -255,7 +294,7 @@ export function registerTools(server, ctx) {
         method: "POST",
         body: JSON.stringify({ content: args.content }),
     })));
-    server.registerTool("update_task_comment", {
+    registerTool("update_task_comment", {
         description: "Update one of your comments on a task.",
         inputSchema: z.object({
             commentId: nonEmptyString,
@@ -265,17 +304,17 @@ export function registerTools(server, ctx) {
         method: "PUT",
         body: JSON.stringify({ content: args.content }),
     })));
-    server.registerTool("delete_task_comment", {
+    registerTool("delete_task_comment", {
         description: "Delete one of your comments from a task.",
         inputSchema: z.object({ commentId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/comment/${encodeURIComponent(args.commentId)}`, {
         method: "DELETE",
     })));
-    server.registerTool("list_workspace_labels", {
+    registerTool("list_workspace_labels", {
         description: "List labels defined in a workspace.",
         inputSchema: z.object({ workspaceId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/label/workspace/${encodeURIComponent(args.workspaceId)}`, { method: "GET" })));
-    server.registerTool("create_label", {
+    registerTool("create_label", {
         description: "Create a label in a workspace (optionally attach to a task).",
         inputSchema: z.object({
             name: nonEmptyString,
@@ -292,7 +331,7 @@ export function registerTools(server, ctx) {
             ...(args.taskId !== undefined ? { taskId: args.taskId } : {}),
         }),
     })));
-    server.registerTool("attach_label_to_task", {
+    registerTool("attach_label_to_task", {
         description: "Attach an existing label to a task.",
         inputSchema: z.object({
             labelId: nonEmptyString,
@@ -302,13 +341,13 @@ export function registerTools(server, ctx) {
         method: "PUT",
         body: JSON.stringify({ taskId: args.taskId }),
     })));
-    server.registerTool("detach_label_from_task", {
+    registerTool("detach_label_from_task", {
         description: "Detach a label from its current task.",
         inputSchema: z.object({ labelId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/label/${encodeURIComponent(args.labelId)}/task`, {
         method: "DELETE",
     })));
-    server.registerTool("create_task_relation", {
+    registerTool("create_task_relation", {
         description: "Create a relation between two tasks. relationType: 'subtask' (sourceTaskId is the parent, targetTaskId the child), 'blocks' (sourceTaskId blocks targetTaskId), or 'related' (bidirectional).",
         inputSchema: z.object({
             sourceTaskId: nonEmptyString,
@@ -323,35 +362,49 @@ export function registerTools(server, ctx) {
             relationType: args.relationType,
         }),
     })));
-    server.registerTool("get_task_relations", {
+    registerTool("get_task_relations", {
         description: "List all relations (subtask/blocks/related) involving a task.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/task-relation/${encodeURIComponent(args.taskId)}`, {
         method: "GET",
     })));
-    server.registerTool("delete_task_relation", {
+    registerTool("delete_task_relation", {
         description: "Delete a task relation by its relation ID.",
         inputSchema: z.object({ id: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/task-relation/${encodeURIComponent(args.id)}`, {
         method: "DELETE",
     })));
-    server.registerTool("delete_label", {
-        description: "Delete a label by ID. Only task-associated labels can be deleted; workspace-level labels (taskId null) are rejected by the API.",
+    registerTool("delete_label", {
+        description: "Delete a task or workspace label by ID. Workspace-label cascades resume automatically; repeat the tool if pendingDeletion remains true.",
         inputSchema: z.object({ id: nonEmptyString }),
     }, async (args) => run(async () => {
-        const label = (await client.json(`/api/label/${encodeURIComponent(args.id)}`, { method: "GET" }));
-        if (!label?.taskId) {
-            throw new Error("Label is not associated with a task and cannot be deleted (workspace-level labels are not deletable via this endpoint).");
+        let result;
+        const signal = AbortSignal.timeout(10_000);
+        // Bound work per tool call. The API persists the continuation boundary.
+        for (let page = 0; page < 100; page++) {
+            if (page > 0 && signal.aborted)
+                break;
+            try {
+                result = await client.json(`/api/label/${encodeURIComponent(args.id)}`, { method: "DELETE", signal });
+            }
+            catch (error) {
+                if (signal.aborted && result)
+                    break;
+                throw error;
+            }
+            if (!result ||
+                typeof result !== "object" ||
+                !("pendingDeletion" in result) ||
+                !result.pendingDeletion)
+                break;
         }
-        return client.json(`/api/label/${encodeURIComponent(args.id)}`, {
-            method: "DELETE",
-        });
+        return result;
     }));
-    server.registerTool("list_workspace_members", {
+    registerTool("list_workspace_members", {
         description: "List the members of a workspace. Use this to resolve the user ID an assignee tool expects.",
         inputSchema: z.object({ workspaceId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/workspace/${encodeURIComponent(args.workspaceId)}/members`)));
-    server.registerTool("search", {
+    registerTool("search", {
         description: "Search across tasks, projects, workspaces, comments, and activities.",
         inputSchema: z.object({
             q: nonEmptyString.describe("Search query"),
@@ -388,17 +441,17 @@ export function registerTools(server, ctx) {
             qs.set("limit", String(args.limit));
         return run(() => client.json(`/api/search?${qs.toString()}`));
     });
-    server.registerTool("list_project_columns", {
+    registerTool("list_project_columns", {
         description: "List a project's columns. Their slugs are the values update_task_status and create_task accept as a status.",
         inputSchema: z.object({ projectId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/column/${encodeURIComponent(args.projectId)}`)));
-    server.registerTool("delete_task", {
+    registerTool("delete_task", {
         description: "Delete a task by ID.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/task/${encodeURIComponent(args.taskId)}`, {
         method: "DELETE",
     })));
-    server.registerTool("update_task_assignee", {
+    registerTool("update_task_assignee", {
         description: "Assign a task to a workspace member, or pass a null userId to unassign it.",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -410,7 +463,7 @@ export function registerTools(server, ctx) {
         method: "PUT",
         body: JSON.stringify({ userId: args.userId }),
     })));
-    server.registerTool("update_task_due_date", {
+    registerTool("update_task_due_date", {
         description: "Set a task's due date. Omit dueDate to clear it.",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -420,15 +473,15 @@ export function registerTools(server, ctx) {
         method: "PUT",
         body: JSON.stringify(args.dueDate === undefined ? {} : { dueDate: args.dueDate }),
     })));
-    server.registerTool("list_task_time_entries", {
+    registerTool("list_task_time_entries", {
         description: "List the time entries logged against a task.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/time-entry/task/${encodeURIComponent(args.taskId)}`)));
-    server.registerTool("get_time_entry", {
+    registerTool("get_time_entry", {
         description: "Get a single time entry by ID.",
         inputSchema: z.object({ id: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/time-entry/${encodeURIComponent(args.id)}`)));
-    server.registerTool("create_time_entry", {
+    registerTool("create_time_entry", {
         description: "Log time against a task. Omit endTime to leave the entry running.",
         inputSchema: z.object({
             taskId: nonEmptyString,
@@ -445,8 +498,8 @@ export function registerTools(server, ctx) {
             ...(args.description ? { description: args.description } : {}),
         }),
     })));
-    server.registerTool("update_time_entry", {
-        description: "Update a time entry. startTime is required; omit endTime to reopen the entry.",
+    registerTool("update_time_entry", {
+        description: "Update a time entry. startTime is required; omitting endTime keeps the stored one. startTime cannot be later than the end time.",
         inputSchema: z.object({
             id: nonEmptyString,
             startTime: isoDateTimeSchema,
@@ -461,11 +514,11 @@ export function registerTools(server, ctx) {
             ...(args.description ? { description: args.description } : {}),
         }),
     })));
-    server.registerTool("list_task_activity", {
+    registerTool("list_task_activity", {
         description: "List a task's activity history.",
         inputSchema: z.object({ taskId: nonEmptyString }),
     }, async (args) => run(() => client.json(`/api/activity/${encodeURIComponent(args.taskId)}`)));
-    server.registerTool("list_notifications", {
+    registerTool("list_notifications", {
         description: "List the signed-in user's notifications.",
         inputSchema: z.object({}),
     }, async () => run(() => client.json("/api/notification")));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kaneo/mcp",
-	"version": "0.1.10",
+	"version": "0.1.12",
 	"mcpName": "io.github.usekaneo/kaneo",
 	"description": "Official MCP (Model Context Protocol) server for Kaneo, the open source project management platform: manage tasks, projects, and labels from Claude, Cursor, and other MCP clients",
 	"license": "MIT",
@@ -19,6 +19,10 @@
 		".": {
 			"import": "./dist/server.js",
 			"types": "./dist/server.d.ts"
+		},
+		"./tools": {
+			"types": "./dist/tools/register.d.ts",
+			"import": "./dist/tools/register.js"
 		}
 	},
 	"publishConfig": {
@@ -30,39 +34,39 @@
 		"LICENSE"
 	],
 	"keywords": [
+		"ai-agents",
+		"claude",
+		"kanban",
+		"kaneo",
+		"kaneo-mcp",
 		"mcp",
 		"mcp-server",
 		"model-context-protocol",
-		"kaneo",
-		"kaneo-mcp",
 		"project-management",
-		"tasks",
-		"kanban",
-		"ai-agents",
-		"claude",
-		"stdio"
+		"stdio",
+		"tasks"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.json",
+		"build": "vp run compile",
 		"prepublishOnly": "pnpm run build",
 		"dev": "tsx watch src/index.ts",
-		"lint": "biome check --write .",
+		"lint": "vp check .",
 		"start": "node dist/index.js",
-		"test": "vitest run --config vitest.config.ts",
-		"test:watch": "vitest --config vitest.config.ts"
+		"test": "vp run test:run",
+		"test:watch": "vp test --config vitest.config.ts"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"open": "^11.0.0",
+		"@modelcontextprotocol/sdk": "^1.30.1",
+		"open": "^11.0.4",
 		"prompts": "^2.4.2",
-		"zod": "^4.4.3"
+		"zod": "^4.6.5"
 	},
 	"devDependencies": {
 		"@kaneo/typescript-config": "workspace:*",
-		"@types/node": "^26.1.2",
+		"@types/node": "^26.6.2",
 		"@types/prompts": "^2.4.9",
-		"tsx": "^4.23.9",
+		"tsx": "^4.23.15",
 		"typescript": "^7.0.2",
-		"vitest": "^4.1.10"
+		"vite-plus": "catalog:"
 	}
 }