@kaneo/mcp 0.1.5 → 0.1.7

package/README.md

@@ -1,9 +1,11 @@
 # Kaneo MCP server
 
-`@kaneo/mcp` is a local MCP server for Kaneo.
+[`@kaneo/mcp`](https://www.npmjs.com/package/@kaneo/mcp) is the official MCP (Model Context Protocol) server for [Kaneo](https://kaneo.app), the open source project management platform. It is maintained in the [usekaneo/kaneo](https://github.com/usekaneo/kaneo) monorepo and published to npm by the Kaneo team.
 
 It runs over stdio, signs in with Kaneo's device flow, and then calls the Kaneo API with a bearer token. The package lives in `packages/mcp` in this monorepo and exposes the `kaneo-mcp` CLI.
 
+> **Tip:** Every Kaneo instance also ships a built-in HTTP MCP endpoint at `/api/mcp`. If your MCP client supports Streamable HTTP transport (e.g. Claude Code), you can connect directly without this package. See the [MCP docs](https://docs.kaneo.app/core/integrations/mcp) for details.
+
 ## Prerequisites
 
 - Node.js 20+
@@ -23,6 +25,7 @@ DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp,your-client-id
 |----------|-------------|
 | `KANEO_API_URL` | Kaneo API origin (default `http://localhost:1337`). Do not include `/api`. |
 | `KANEO_MCP_CLIENT_ID` | Device-flow client id (default `kaneo-mcp`). Must match `DEVICE_AUTH_CLIENT_IDS` on the server. |
+| `KANEO_API_KEY` | **Optional.** A Kaneo API key (create one under Settings → Account → Developer). When set, the server authenticates with it as a Bearer token and skips the interactive device flow. Use this for headless/Docker setups. |
 
 ## Install
 
@@ -106,10 +109,21 @@ On the first tool call that needs Kaneo, the server:
 4. Polls `POST /api/auth/device/token` until approved
 5. Stores the access token at `~/.config/kaneo-mcp/credentials.json` with mode `0600`
 
+### Non-interactive (API key)
+
+For headless or sandboxed environments where opening a browser is impractical, set `KANEO_API_KEY` to a key created under Settings → Account → Developer. The server sends it as a Bearer token on every request and skips the device flow entirely, so no token is cached to disk.
+
 ## Tools
 
 - Session: `whoami`, `list_workspaces`
 - Projects: `list_projects`, `get_project`, `create_project`, `update_project`
 - Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
-- Comments: `list_task_comments`, `create_task_comment`
-- Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`
+- 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`
+- Task relations: `create_task_relation`, `get_task_relations`, `delete_task_relation`
+
+## Releasing
+
+Bump `version` in `packages/mcp/package.json` and merge to `main`. The [publish workflow](../../.github/workflows/publish-mcp.yml) runs the package tests, publishes the new version to npm, and creates a `mcp-v<version>` GitHub release. Nothing is published while the version stays the same, so tool changes reach npm only once the version is bumped.
+
+Publishing a GitHub release manually also works: tag it `mcp-v<version>` with the tag version matching `packages/mcp/package.json` on the tagged commit.

package/dist/auth/auth-service.d.ts

@@ -0,0 +1,24 @@
+export type AuthServiceOptions = {
+    baseUrl: string;
+    clientId: string;
+    apiKey?: string;
+};
+export declare class AuthService {
+    readonly baseUrl: string;
+    readonly clientId: string;
+    private readonly apiKey?;
+    private activeGetAccessTokenPromise?;
+    constructor(options: AuthServiceOptions);
+    /**
+     * True when a pre-created Kaneo API key is used instead of the interactive
+     * device flow. Callers use this to avoid clearing/retrying auth on a 401.
+     */
+    get usingApiKey(): boolean;
+    clearToken(): Promise<void>;
+    private validateAccessToken;
+    private log;
+    /**
+     * Returns a valid access token, running the device authorization flow if needed.
+     */
+    getAccessToken(): Promise<string>;
+}

package/dist/auth/auth-service.js

@@ -4,12 +4,24 @@ import { clearCredentials, loadCredentials, saveCredentials, } from "./token-sto
 export class AuthService {
     baseUrl;
     clientId;
+    apiKey;
     activeGetAccessTokenPromise;
     constructor(options) {
         this.baseUrl = options.baseUrl;
         this.clientId = options.clientId;
+        this.apiKey = options.apiKey;
+    }
+    /**
+     * True when a pre-created Kaneo API key is used instead of the interactive
+     * device flow. Callers use this to avoid clearing/retrying auth on a 401.
+     */
+    get usingApiKey() {
+        return Boolean(this.apiKey);
     }
     async clearToken() {
+        // Nothing to clear for API-key auth; the key is static config.
+        if (this.apiKey)
+            return;
         await clearCredentials();
     }
     async validateAccessToken(token) {
@@ -39,6 +51,12 @@ export class AuthService {
      * Returns a valid access token, running the device authorization flow if needed.
      */
     async getAccessToken() {
+        // Non-interactive auth: a pre-created Kaneo API key (KANEO_API_KEY) is sent
+        // as a Bearer token, which the REST API already accepts. This skips the
+        // device flow so the MCP server works in headless/Docker environments.
+        if (this.apiKey) {
+            return this.apiKey;
+        }
         if (this.activeGetAccessTokenPromise) {
             return await this.activeGetAccessTokenPromise;
         }

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,21 @@
+export type DeviceCodeResponse = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    interval: number;
+    expires_in: number;
+};
+export type DeviceTokenErrorBody = {
+    error?: string;
+    error_description?: string;
+};
+export declare function requestDeviceCode(baseUrl: string, clientId: string): Promise<DeviceCodeResponse>;
+/**
+ * Polls `/api/auth/device/token` until success or terminal error.
+ * First attempt is immediate; subsequent attempts wait `interval` seconds (increased on `slow_down`).
+ */
+export declare function pollDeviceAccessToken(baseUrl: string, clientId: string, deviceCode: string, initialIntervalSec: number, options?: {
+    maxWaitMs?: number;
+    log?: (msg: string) => void;
+}): Promise<string>;

package/dist/auth/token-store.d.ts

@@ -0,0 +1,10 @@
+export type StoredCredentials = {
+    version: 1;
+    baseUrl: string;
+    clientId: string;
+    accessToken: string;
+};
+export declare function credentialsPath(): string;
+export declare function loadCredentials(): Promise<StoredCredentials | null>;
+export declare function saveCredentials(data: StoredCredentials): Promise<void>;
+export declare function clearCredentials(): Promise<void>;

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(): Promise<void>;

package/dist/cli.js

@@ -35,7 +35,7 @@ async function startMcpServer() {
     await server.connect(transport);
 }
 function printMainHelp() {
-    console.log(`kaneo-mcp — Kaneo MCP server (stdio transport)
+    console.log(`kaneo-mcp: Kaneo MCP server (stdio transport)
 
 Usage:
   npx @kaneo/mcp         Interactive installer (terminal only; no global install)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/install/index.d.ts

@@ -0,0 +1,11 @@
+export type ParsedInstallArgs = {
+    target?: string;
+    output?: string;
+    name: string;
+    yes: boolean;
+    apiUrl?: string;
+    projectDir: string;
+    help: boolean;
+};
+export declare function parseInstallArgs(argv: string[]): ParsedInstallArgs;
+export declare function runInstall(argv: string[]): Promise<void>;

package/dist/install/index.js

@@ -273,7 +273,7 @@ export async function runInstall(argv) {
     console.log("\nRestart your MCP client (or reload the window) if needed.");
 }
 function printInstallHelp() {
-    console.log(`kaneo-mcp install — register Kaneo in an MCP client config
+    console.log(`kaneo-mcp install: register Kaneo in an MCP client config
 
 Usage:
   kaneo-mcp install [options]

package/dist/install/merge-config.d.ts

@@ -0,0 +1,10 @@
+export type McpServerEntry = {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+};
+/**
+ * Merges or replaces `mcpServers[serverName]` and returns formatted JSON.
+ * Preserves other top-level keys and other MCP server entries.
+ */
+export declare function mergeMcpServerEntry(existingJson: string | null, serverName: string, serverConfig: McpServerEntry): string;

package/dist/install/resolve-entry.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Absolute path to this package's `dist/index.js` (the MCP stdio entry).
+ * Resolved from `dist/install/resolve-entry.js` at runtime.
+ */
+export declare function resolvePackageEntryPath(): string;

package/dist/install/targets.d.ts

@@ -0,0 +1,39 @@
+export type InstallTargetId = "cursor-user" | "cursor-project" | "claude-desktop" | "custom";
+export type InstallTarget = {
+    id: InstallTargetId;
+    label: string;
+    description: string;
+};
+/**
+ * Validates a non-interactive custom MCP config path (same rules as the install wizard).
+ * Returns the trimmed absolute path on success.
+ */
+export declare function validateCustomConfigPathInput(raw: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    message: string;
+};
+export declare const INSTALL_TARGETS: readonly [{
+    readonly id: "cursor-user";
+    readonly label: "Cursor (user-wide)";
+    readonly description: "~/.cursor/mcp.json, available in all projects";
+}, {
+    readonly id: "cursor-project";
+    readonly label: "Cursor (this project only)";
+    readonly description: ".cursor/mcp.json in the current directory";
+}, {
+    readonly id: "claude-desktop";
+    readonly label: "Claude Desktop";
+    readonly description: "claude_desktop_config.json for the Claude app";
+}, {
+    readonly id: "custom";
+    readonly label: "Custom file path";
+    readonly description: "Any JSON file you choose (advanced)";
+}];
+export declare function getClaudeDesktopConfigPath(): string;
+export declare function resolveTargetConfigPath(id: InstallTargetId, options: {
+    cwd: string;
+    customPath?: string;
+}): string;

package/dist/install/targets.js

@@ -21,7 +21,7 @@ export const INSTALL_TARGETS = [
     {
         id: "cursor-user",
         label: "Cursor (user-wide)",
-        description: "~/.cursor/mcp.json — available in all projects",
+        description: "~/.cursor/mcp.json, available in all projects",
     },
     {
         id: "cursor-project",

package/dist/install/wizard.d.ts

@@ -0,0 +1,4 @@
+import { type InstallTargetId } from "./targets.js";
+export declare function promptTargetSelect(): Promise<InstallTargetId[]>;
+export declare function promptCustomConfigPath(): Promise<string>;
+export declare function promptConfirmOverwrite(serverName: string, configPath: string): Promise<boolean>;

package/dist/kaneo/client.d.ts

@@ -0,0 +1,14 @@
+import type { AuthService } from "../auth/auth-service.js";
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export declare class KaneoClient {
+    readonly baseUrl: string;
+    private readonly auth;
+    constructor(options: {
+        baseUrl: string;
+        auth: AuthService;
+    });
+    private authorizedFetch;
+    json<T = Json>(path: string, init?: RequestInit): Promise<T>;
+}

package/dist/kaneo/client.js

@@ -18,7 +18,9 @@ export class KaneoClient {
             ? AbortSignal.any([init.signal, timeoutSignal])
             : timeoutSignal;
         const res = await fetch(url, { ...init, headers, signal });
-        if (res.status === 401 && !didRetry) {
+        // With a static API key there is nothing to refresh, so surface the 401
+        // instead of looping back into the interactive device flow.
+        if (res.status === 401 && !didRetry && !this.auth.usingApiKey) {
             await this.auth.clearToken();
             return this.authorizedFetch(path, init, true);
         }

package/dist/kaneo/task-helpers.d.ts

@@ -0,0 +1,19 @@
+declare const PRIORITIES: readonly ["no-priority", "low", "medium", "high", "urgent"];
+export type TaskPriority = (typeof PRIORITIES)[number];
+export declare function isTaskPriority(v: string): v is TaskPriority;
+export type TaskUpdatePatch = {
+    title?: string;
+    description?: string | null;
+    status?: string;
+    priority?: TaskPriority;
+    projectId?: string;
+    position?: number;
+    startDate?: string | null;
+    dueDate?: string | null;
+    userId?: string | null;
+};
+/**
+ * Builds the JSON body for `PUT /api/task/:id` from an existing task plus a patch.
+ */
+export declare function buildFullTaskUpdateBody(existing: Record<string, unknown>, patch: TaskUpdatePatch): Record<string, string | number | undefined>;
+export {};

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createMcpServer(): McpServer;

package/dist/server.js

@@ -9,7 +9,8 @@ const { version: packageVersion } = require("../package.json");
 export function createMcpServer() {
     const baseUrl = normalizeBaseUrl(process.env.KANEO_API_URL || "http://localhost:1337");
     const clientId = process.env.KANEO_MCP_CLIENT_ID || "kaneo-mcp";
-    const auth = new AuthService({ baseUrl, clientId });
+    const apiKey = process.env.KANEO_API_KEY || undefined;
+    const auth = new AuthService({ baseUrl, clientId, apiKey });
     const client = new KaneoClient({ baseUrl, auth });
     const server = new McpServer({
         name: "kaneo-mcp",

package/dist/tools/register.d.ts

@@ -0,0 +1,5 @@
+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;
+}): void;

package/dist/tools/register.js

@@ -255,6 +255,22 @@ export function registerTools(server, ctx) {
         method: "POST",
         body: JSON.stringify({ content: args.content }),
     })));
+    server.registerTool("update_task_comment", {
+        description: "Update one of your comments on a task.",
+        inputSchema: z.object({
+            commentId: nonEmptyString,
+            content: nonEmptyString,
+        }),
+    }, async (args) => run(() => client.json(`/api/comment/${encodeURIComponent(args.commentId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ content: args.content }),
+    })));
+    server.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", {
         description: "List labels defined in a workspace.",
         inputSchema: z.object({ workspaceId: nonEmptyString }),
@@ -292,4 +308,43 @@ export function registerTools(server, ctx) {
     }, async (args) => run(() => client.json(`/api/label/${encodeURIComponent(args.labelId)}/task`, {
         method: "DELETE",
     })));
+    server.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,
+            targetTaskId: nonEmptyString,
+            relationType: z.enum(["subtask", "blocks", "related"]),
+        }),
+    }, async (args) => run(() => client.json("/api/task-relation", {
+        method: "POST",
+        body: JSON.stringify({
+            sourceTaskId: args.sourceTaskId,
+            targetTaskId: args.targetTaskId,
+            relationType: args.relationType,
+        }),
+    })));
+    server.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", {
+        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.",
+        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).");
+        }
+        return client.json(`/api/label/${encodeURIComponent(args.id)}`, {
+            method: "DELETE",
+        });
+    }));
 }

package/dist/utils/mcp-result.d.ts

@@ -0,0 +1,3 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function textResult(data: unknown, isError?: boolean): CallToolResult;
+export declare function errorResult(message: string): CallToolResult;

package/dist/utils/normalize-base-url.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Kaneo API base URL without trailing slash and without `/api` suffix.
+ */
+export declare function normalizeBaseUrl(raw: string): string;

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "@kaneo/mcp",
-	"version": "0.1.5",
-	"description": "Model Context Protocol (stdio) server for Kaneo — tasks, projects, labels, and device authorization",
+	"version": "0.1.7",
+	"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",
-	"homepage": "https://github.com/usekaneo/kaneo/",
+	"author": "Kaneo (https://kaneo.app)",
+	"homepage": "https://docs.kaneo.app/core/integrations/mcp",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/usekaneo/kaneo/",
@@ -13,6 +14,12 @@
 	"bin": {
 		"kaneo-mcp": "dist/index.js"
 	},
+	"exports": {
+		".": {
+			"import": "./dist/server.js",
+			"types": "./dist/server.d.ts"
+		}
+	},
 	"publishConfig": {
 		"access": "public"
 	},
@@ -23,8 +30,15 @@
 	],
 	"keywords": [
 		"mcp",
+		"mcp-server",
 		"model-context-protocol",
 		"kaneo",
+		"kaneo-mcp",
+		"project-management",
+		"tasks",
+		"kanban",
+		"ai-agents",
+		"claude",
 		"stdio"
 	],
 	"scripts": {
@@ -37,17 +51,17 @@
 		"test:watch": "vitest --config vitest.config.ts"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.26.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
 		"open": "^11.0.0",
 		"prompts": "^2.4.2",
-		"zod": "^4.3.6"
+		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@kaneo/typescript-config": "workspace:*",
 		"@types/node": "^25.3.5",
 		"@types/prompts": "^2.4.9",
-		"tsx": "^4.21.0",
+		"tsx": "^4.23.1",
 		"typescript": "^5.9.3",
-		"vitest": "^4.1.2"
+		"vitest": "^4.1.10"
 	}
 }