@kaneo/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaneo MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Kaneo MCP server
+
+`@kaneo/mcp` is a local MCP server for Kaneo.
+
+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 `apps/mcp` in this monorepo and exposes the `kaneo-mcp` CLI.
+
+## Prerequisites
+
+- Node.js 20+
+- 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.
+
+If you want to run this server with a different client ID, allow it on the Kaneo server:
+
+```bash
+DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp,your-client-id
+```
+
+## Environment
+
+| Variable | Description |
+|----------|-------------|
+| `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. |
+
+## Install
+
+**Recommended (no global install):** run the interactive installer with npx:
+
+```bash
+npx @kaneo/mcp
+```
+
+npm downloads the package, then an **interactive menu** (arrow keys + Enter) asks **where** to register the server (Cursor user-wide, Cursor project, Claude Desktop, or a custom JSON path). It then merges a `mcpServers` entry that points at this package’s `dist/index.js` with your current Node binary.
+
+In a normal terminal, `npx @kaneo/mcp` and `kaneo-mcp` with no subcommand both start the installer. When the process is **not** attached to a TTY (for example when Cursor launches the MCP server with a pipe), the same entry runs the stdio MCP server instead.
+
+To run the server manually from a shell (for example to debug stdio), use:
+
+```bash
+npx @kaneo/mcp serve
+```
+
+If you prefer a global install:
+
+```bash
+npm install -g @kaneo/mcp
+kaneo-mcp
+```
+
+(`kaneo-mcp install` is the same installer with an explicit subcommand.)
+
+Non-interactive example (Cursor user config, skip overwrite prompts):
+
+```bash
+kaneo-mcp install --target cursor-user -y
+```
+
+Point at a self-hosted API when generating the config:
+
+```bash
+kaneo-mcp install --target cursor-user -y --api-url https://kaneo.example.com
+```
+
+See all options:
+
+```bash
+kaneo-mcp install --help
+```
+
+If you are currently inside the local `apps/mcp` package directory, npm may resolve the local workspace package instead of the published one and fail to expose the bin. In that case, either run `npx` from outside `apps/mcp`, or use a local build:
+
+```bash
+node dist/index.js
+```
+
+The published package includes `dist/`. `prepublishOnly` runs the build before publish.
+
+## Develop from source
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm --filter @kaneo/mcp run build
+pnpm --filter @kaneo/mcp run start
+pnpm --filter @kaneo/mcp run test
+```
+
+Or run it from the package directory:
+
+```bash
+pnpm -C apps/mcp run build
+```
+
+The CLI entry points to `./dist/index.js`. Use `npx @kaneo/mcp` or `kaneo-mcp` after a global install so your IDE config points at the resolved path.
+
+## Authentication
+
+On the first tool call that needs Kaneo, the server:
+
+1. Requests a device code from `POST /api/auth/device/code`
+2. Prints the verification URL and user code to `stderr`
+3. Tries to open the browser
+4. Polls `POST /api/auth/device/token` until approved
+5. Stores the access token at `~/.config/kaneo-mcp/credentials.json` with mode `0600`
+
+## 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`

package/dist/auth/auth-service.js

@@ -0,0 +1,69 @@
+import open from "open";
+import { pollDeviceAccessToken, requestDeviceCode } from "./device-flow.js";
+import { clearCredentials, loadCredentials, saveCredentials, } from "./token-store.js";
+export class AuthService {
+    baseUrl;
+    clientId;
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.clientId = options.clientId;
+    }
+    async clearToken() {
+        await clearCredentials();
+    }
+    async validateAccessToken(token) {
+        try {
+            const res = await fetch(`${this.baseUrl}/api/auth/get-session`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (res.status === 401) {
+                return "invalid";
+            }
+            if (!res.ok) {
+                return "unknown";
+            }
+            const data = (await res.json().catch(() => null));
+            return data?.user?.id ? "valid" : "unknown";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    log(msg) {
+        console.error(`[kaneo-mcp] ${msg}`);
+    }
+    /**
+     * Returns a valid access token, running the device authorization flow if needed.
+     */
+    async getAccessToken() {
+        const cached = await loadCredentials();
+        if (cached &&
+            cached.baseUrl === this.baseUrl &&
+            cached.clientId === this.clientId &&
+            cached.accessToken) {
+            const validation = await this.validateAccessToken(cached.accessToken);
+            if (validation === "valid" || validation === "unknown") {
+                return cached.accessToken;
+            }
+            await this.clearToken();
+        }
+        const code = await requestDeviceCode(this.baseUrl, this.clientId);
+        const verifyUrl = code.verification_uri_complete || code.verification_uri;
+        this.log(`Open ${verifyUrl} and approve this device. User code: ${code.user_code}`);
+        try {
+            await open(verifyUrl);
+        }
+        catch {
+            this.log("Could not open a browser automatically; use the URL above.");
+        }
+        const accessToken = await pollDeviceAccessToken(this.baseUrl, this.clientId, code.device_code, code.interval, { log: (m) => this.log(m) });
+        const toStore = {
+            version: 1,
+            baseUrl: this.baseUrl,
+            clientId: this.clientId,
+            accessToken,
+        };
+        await saveCredentials(toStore);
+        return accessToken;
+    }
+}

package/dist/auth/device-flow.js

@@ -0,0 +1,64 @@
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function requestDeviceCode(baseUrl, clientId) {
+    const res = await fetch(`${baseUrl}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ client_id: clientId }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(`device/code failed (${res.status}): ${JSON.stringify(body)}`);
+    }
+    if (!("device_code" in body) || typeof body.device_code !== "string") {
+        throw new Error(`device/code: unexpected response ${JSON.stringify(body)}`);
+    }
+    return body;
+}
+/**
+ * Polls `/api/auth/device/token` until success or terminal error.
+ * First attempt is immediate; subsequent attempts wait `interval` seconds (increased on `slow_down`).
+ */
+export async function pollDeviceAccessToken(baseUrl, clientId, deviceCode, initialIntervalSec, options) {
+    const maxWait = options?.maxWaitMs ?? 30 * 60 * 1000;
+    const log = options?.log ?? (() => { });
+    const started = Date.now();
+    let intervalMs = Math.max(1000, initialIntervalSec * 1000);
+    for (let attempt = 0; Date.now() - started < maxWait; attempt++) {
+        if (attempt > 0) {
+            await sleep(intervalMs);
+        }
+        const res = await fetch(`${baseUrl}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCode,
+                client_id: clientId,
+            }),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok && typeof body.access_token === "string") {
+            return body.access_token;
+        }
+        const err = body.error;
+        if (err === "authorization_pending") {
+            log("Waiting for device approval…");
+            continue;
+        }
+        if (err === "slow_down") {
+            intervalMs += 5000;
+            log(`Rate limited (slow_down); polling every ${intervalMs / 1000}s`);
+            continue;
+        }
+        if (err === "access_denied") {
+            throw new Error("Device authorization was denied.");
+        }
+        if (err === "expired_token") {
+            throw new Error("Device code expired; start login again.");
+        }
+        throw new Error(`device/token failed (${res.status}): ${JSON.stringify(body)}`);
+    }
+    throw new Error("Device authorization timed out waiting for approval.");
+}

package/dist/auth/token-store.js

@@ -0,0 +1,50 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+function configDir() {
+    const base = process.env.XDG_CONFIG_HOME?.trim() || path.join(homedir(), ".config");
+    return path.join(base, "kaneo-mcp");
+}
+export function credentialsPath() {
+    return path.join(configDir(), "credentials.json");
+}
+export async function loadCredentials() {
+    try {
+        const raw = await readFile(credentialsPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version === 1 &&
+            typeof parsed.baseUrl === "string" &&
+            typeof parsed.clientId === "string" &&
+            typeof parsed.accessToken === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(data) {
+    const dir = configDir();
+    await mkdir(dir, { recursive: true, mode: DIR_MODE });
+    const file = credentialsPath();
+    await writeFile(file, `${JSON.stringify(data, null, 2)}\n`, {
+        mode: FILE_MODE,
+    });
+    try {
+        await chmod(file, FILE_MODE);
+    }
+    catch {
+        /* ignore chmod failures on some FS */
+    }
+}
+export async function clearCredentials() {
+    try {
+        await unlink(credentialsPath());
+    }
+    catch {
+        /* noop */
+    }
+}

package/dist/cli.js

@@ -0,0 +1,55 @@
+import { stdin as input } from "node:process";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { runInstall } from "./install/index.js";
+import { createMcpServer } from "./server.js";
+const SERVE_ALIASES = new Set(["serve", "server", "stdio", "run"]);
+export async function runCli() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "-h" || argv[0] === "--help" || argv[0] === "help") {
+        printMainHelp();
+        return;
+    }
+    if (argv[0] === "install" || argv[0] === "setup") {
+        await runInstall(argv.slice(1));
+        return;
+    }
+    if (argv[0] !== undefined) {
+        if (SERVE_ALIASES.has(argv[0])) {
+            await startMcpServer();
+            return;
+        }
+        console.error(`Unknown command: ${argv[0]}`);
+        printMainHelp();
+        process.exitCode = 1;
+        return;
+    }
+    if (input.isTTY) {
+        await runInstall([]);
+        return;
+    }
+    await startMcpServer();
+}
+async function startMcpServer() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function printMainHelp() {
+    console.log(`kaneo-mcp — Kaneo MCP server (stdio transport)
+
+Usage:
+  npx @kaneo/mcp         Interactive installer (terminal only; no global install)
+  kaneo-mcp              Same: installer in a TTY; MCP server when stdin is piped
+  kaneo-mcp install      Register in Cursor / Claude / a custom path (explicit)
+  kaneo-mcp serve        Run the MCP server (use from a terminal to test stdio)
+  kaneo-mcp help
+
+Options:
+  -h, --help             Show this help
+
+MCP clients (Cursor, etc.) run this process with a pipe, so they get the server.
+In a normal terminal, the default is the interactive installer.
+
+See also: kaneo-mcp install --help
+`);
+}

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+runCli().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/install/index.js

@@ -0,0 +1,248 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { stdin as input, stdout as output } from "node:process";
+import { mergeMcpServerEntry } from "./merge-config.js";
+import { resolvePackageEntryPath } from "./resolve-entry.js";
+import { resolveTargetConfigPath } from "./targets.js";
+import { promptConfirmOverwrite, promptCustomConfigPath, promptTargetSelect, } from "./wizard.js";
+export function parseInstallArgs(argv) {
+    let target;
+    let output;
+    let name = "kaneo";
+    let yes = false;
+    let apiUrl;
+    let projectDir = process.cwd();
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined) {
+            continue;
+        }
+        if (a === "-h" || a === "--help") {
+            help = true;
+            continue;
+        }
+        if (a === "-y" || a === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (a === "--target") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--target requires a value");
+            }
+            target = v;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--target=")) {
+            target = a.slice("--target=".length);
+            continue;
+        }
+        if (a === "--output") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--output requires a value");
+            }
+            output = v;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--output=")) {
+            output = a.slice("--output=".length);
+            continue;
+        }
+        if (a === "--name") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--name requires a value");
+            }
+            name = v;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--name=")) {
+            name = a.slice("--name=".length);
+            continue;
+        }
+        if (a === "--api-url") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--api-url requires a value");
+            }
+            apiUrl = v;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--api-url=")) {
+            apiUrl = a.slice("--api-url=".length);
+            continue;
+        }
+        if (a === "--project-dir") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--project-dir requires a value");
+            }
+            projectDir = v;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--project-dir=")) {
+            projectDir = a.slice("--project-dir=".length);
+            continue;
+        }
+        throw new Error(`Unknown option: ${a}`);
+    }
+    return { target, output, name, yes, apiUrl, projectDir, help };
+}
+function hasExistingServerEntry(jsonText, serverName) {
+    if (!jsonText) {
+        return false;
+    }
+    try {
+        const root = JSON.parse(jsonText);
+        if (!root || typeof root !== "object" || Array.isArray(root)) {
+            return false;
+        }
+        const m = root.mcpServers;
+        if (!m || typeof m !== "object" || Array.isArray(m)) {
+            return false;
+        }
+        return Object.hasOwn(m, serverName);
+    }
+    catch {
+        return false;
+    }
+}
+const VALID_TARGETS = [
+    "cursor-user",
+    "cursor-project",
+    "claude-desktop",
+    "custom",
+];
+function isInstallTargetId(s) {
+    return VALID_TARGETS.includes(s);
+}
+export async function runInstall(argv) {
+    let parsed;
+    try {
+        parsed = parseInstallArgs(argv);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        printInstallHelp();
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.help) {
+        printInstallHelp();
+        return;
+    }
+    if (parsed.target !== undefined && !isInstallTargetId(parsed.target)) {
+        console.error(`Invalid --target. Use one of: ${VALID_TARGETS.join(", ")}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!parsed.name.trim()) {
+        console.error("--name must be a non-empty string.");
+        process.exitCode = 1;
+        return;
+    }
+    let targetId = parsed.target;
+    const needsInteractive = input.isTTY && output.isTTY && !parsed.yes && targetId === undefined;
+    if (needsInteractive) {
+        targetId = await promptTargetSelect();
+    }
+    else if (targetId === undefined) {
+        console.error("Non-interactive mode: specify --target (e.g. --target cursor-user) and use -y to confirm.");
+        printInstallHelp();
+        process.exitCode = 1;
+        return;
+    }
+    let customPath = parsed.output;
+    if (targetId === "custom") {
+        if (!customPath) {
+            if (input.isTTY && output.isTTY) {
+                customPath = await promptCustomConfigPath();
+            }
+            else {
+                console.error("Custom target requires --output <path>");
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
+    const configPath = resolveTargetConfigPath(targetId, {
+        cwd: parsed.projectDir,
+        customPath,
+    });
+    const entryPath = resolvePackageEntryPath();
+    const env = parsed.apiUrl !== undefined && parsed.apiUrl.length > 0
+        ? { KANEO_API_URL: parsed.apiUrl }
+        : undefined;
+    const serverConfig = {
+        command: process.execPath,
+        args: [entryPath],
+        ...(env ? { env } : {}),
+    };
+    let existingText = null;
+    try {
+        existingText = await readFile(configPath, "utf8");
+    }
+    catch {
+        existingText = null;
+    }
+    const already = hasExistingServerEntry(existingText, parsed.name);
+    if (already && !parsed.yes) {
+        if (input.isTTY && output.isTTY) {
+            const ok = await promptConfirmOverwrite(parsed.name);
+            if (!ok) {
+                console.log("Aborted.");
+                return;
+            }
+        }
+        else {
+            console.error(`Entry "${parsed.name}" already exists. Pass -y to overwrite.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    let merged;
+    try {
+        merged = mergeMcpServerEntry(existingText, parsed.name, serverConfig);
+    }
+    catch {
+        console.error(`Cannot update config (invalid JSON or merge error): ${configPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, merged, { encoding: "utf8", mode: 0o600 });
+    console.log(`Wrote MCP server "${parsed.name}" to:\n  ${configPath}`);
+    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
+
+Usage:
+  kaneo-mcp install [options]
+
+Without options, runs interactively (pick Cursor / Claude / custom path).
+
+Options:
+  --target <id>       cursor-user | cursor-project | claude-desktop | custom
+  --output <path>     Required for --target custom (absolute path to JSON file)
+  --project-dir <dir> Base directory for cursor-project (default: current dir)
+  --name <string>     MCP server key under mcpServers (default: kaneo)
+  --api-url <url>     Set KANEO_API_URL in the generated entry (optional)
+  -y, --yes           Overwrite existing entry without prompting
+  -h, --help          Show this help
+
+Examples:
+  npm install -g @kaneo/mcp
+  kaneo-mcp install
+
+  kaneo-mcp install --target cursor-user -y
+  kaneo-mcp install --target custom --output /path/to/mcp.json -y
+`);
+}

package/dist/install/merge-config.js

@@ -0,0 +1,25 @@
+/**
+ * Merges or replaces `mcpServers[serverName]` and returns formatted JSON.
+ * Preserves other top-level keys and other MCP server entries.
+ */
+export function mergeMcpServerEntry(existingJson, serverName, serverConfig) {
+    let root = {};
+    if (existingJson) {
+        const parsed = JSON.parse(existingJson);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            root = { ...parsed };
+        }
+    }
+    const mcpServers = (() => {
+        const raw = root.mcpServers;
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+            return { ...raw };
+        }
+        return {};
+    })();
+    mcpServers[serverName] = serverConfig;
+    root.mcpServers = mcpServers;
+    return `${JSON.stringify(root, null, 2)}\n`;
+}

package/dist/install/resolve-entry.js

@@ -0,0 +1,9 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Absolute path to this package's `dist/index.js` (the MCP stdio entry).
+ * Resolved from `dist/install/resolve-entry.js` at runtime.
+ */
+export function resolvePackageEntryPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "../index.js");
+}

package/dist/install/targets.js

@@ -0,0 +1,55 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const INSTALL_TARGETS = [
+    {
+        id: "cursor-user",
+        label: "Cursor (user-wide)",
+        description: "~/.cursor/mcp.json — available in all projects",
+    },
+    {
+        id: "cursor-project",
+        label: "Cursor (this project only)",
+        description: ".cursor/mcp.json in the current directory",
+    },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        description: "claude_desktop_config.json for the Claude app",
+    },
+    {
+        id: "custom",
+        label: "Custom file path",
+        description: "Any JSON file you choose (advanced)",
+    },
+];
+export function getClaudeDesktopConfigPath() {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        const appData = process.env.APPDATA;
+        if (!appData) {
+            throw new Error("APPDATA is not set; cannot resolve Claude Desktop path");
+        }
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+export function resolveTargetConfigPath(id, options) {
+    switch (id) {
+        case "cursor-user":
+            return join(homedir(), ".cursor", "mcp.json");
+        case "cursor-project":
+            return join(options.cwd, ".cursor", "mcp.json");
+        case "claude-desktop":
+            return getClaudeDesktopConfigPath();
+        case "custom": {
+            const p = options.customPath?.trim();
+            if (!p) {
+                throw new Error("Custom target requires a file path");
+            }
+            return p;
+        }
+    }
+}

package/dist/install/wizard.js

@@ -0,0 +1,59 @@
+import prompts from "prompts";
+import { INSTALL_TARGETS } from "./targets.js";
+function onCancel() {
+    console.log("\nCancelled.");
+    process.exit(0);
+}
+function printIntro() {
+    console.log(`
+────────────────────────────────────────
+  Kaneo MCP  ·  editor setup
+────────────────────────────────────────
+  Use ↑ / ↓ to move, Enter to select.
+────────────────────────────────────────
+`);
+}
+export async function promptTargetSelect() {
+    printIntro();
+    const answer = await prompts({
+        type: "select",
+        name: "target",
+        message: "Where should Kaneo register this MCP server?",
+        choices: INSTALL_TARGETS.map((t) => ({
+            title: t.label,
+            description: t.description,
+            value: t.id,
+        })),
+        initial: 0,
+    }, { onCancel });
+    if (answer.target === undefined) {
+        onCancel();
+    }
+    return answer.target;
+}
+export async function promptCustomConfigPath() {
+    const answer = await prompts({
+        type: "text",
+        name: "path",
+        message: "Absolute path to the JSON config file (create or update):",
+        validate: (v) => typeof v === "string" && v.trim().length > 0
+            ? true
+            : "Path is required",
+    }, { onCancel });
+    if (answer.path === undefined) {
+        onCancel();
+    }
+    return String(answer.path).trim();
+}
+export async function promptConfirmOverwrite(serverName) {
+    const answer = await prompts({
+        type: "confirm",
+        name: "overwrite",
+        message: `MCP server "${serverName}" is already in this file. Overwrite it?`,
+        initial: false,
+    }, { onCancel });
+    if (answer.overwrite === undefined) {
+        onCancel();
+    }
+    return Boolean(answer.overwrite);
+}

package/dist/kaneo/client.js

@@ -0,0 +1,53 @@
+export class KaneoClient {
+    baseUrl;
+    auth;
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.auth = options.auth;
+    }
+    async authorizedFetch(path, init, didRetry = false) {
+        const token = await this.auth.getAccessToken();
+        const headers = new Headers(init?.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        if (init?.body != null && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const res = await fetch(url, { ...init, headers });
+        if (res.status === 401 && !didRetry) {
+            await this.auth.clearToken();
+            return this.authorizedFetch(path, init, true);
+        }
+        return res;
+    }
+    async json(path, init) {
+        const res = await this.authorizedFetch(path, init);
+        const text = await res.text();
+        let body = null;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        if (!res.ok) {
+            let detail;
+            if (typeof body === "object" &&
+                body !== null &&
+                "message" in body &&
+                typeof body.message === "string") {
+                detail = body.message;
+            }
+            else if (typeof body === "string" && body.length > 0) {
+                detail = body.length > 500 ? `${body.slice(0, 500)}…` : body;
+            }
+            else {
+                detail = `HTTP ${res.status}`;
+            }
+            throw new Error(`${path}: ${detail}`);
+        }
+        return body;
+    }
+}

package/dist/kaneo/task-helpers.js

@@ -0,0 +1,84 @@
+const PRIORITIES = ["no-priority", "low", "medium", "high", "urgent"];
+export function isTaskPriority(v) {
+    return PRIORITIES.includes(v);
+}
+/**
+ * Builds the JSON body for `PUT /api/task/:id` from an existing task plus a patch.
+ */
+export function buildFullTaskUpdateBody(existing, patch) {
+    const positionRaw = patch.position ?? existing.position;
+    const position = typeof positionRaw === "number"
+        ? positionRaw
+        : typeof positionRaw === "string"
+            ? Number(positionRaw)
+            : Number.NaN;
+    if (!Number.isFinite(position)) {
+        throw new Error("Cannot update task: missing numeric `position` on existing task.");
+    }
+    const title = patch.title ??
+        (typeof existing.title === "string" ? existing.title : undefined);
+    if (!title) {
+        throw new Error("Cannot update task: missing title.");
+    }
+    const description = patch.description !== undefined
+        ? patch.description === null
+            ? ""
+            : String(patch.description)
+        : existing.description == null
+            ? ""
+            : String(existing.description);
+    const status = patch.status ??
+        (typeof existing.status === "string" ? existing.status : undefined);
+    if (!status) {
+        throw new Error("Cannot update task: missing status.");
+    }
+    const priorityRaw = patch.priority ??
+        (typeof existing.priority === "string" ? existing.priority : undefined);
+    if (!priorityRaw || !isTaskPriority(priorityRaw)) {
+        throw new Error("Cannot update task: invalid or missing priority.");
+    }
+    const projectId = patch.projectId ??
+        (typeof existing.projectId === "string" ? existing.projectId : undefined);
+    if (!projectId) {
+        throw new Error("Cannot update task: missing projectId.");
+    }
+    const userId = patch.userId !== undefined
+        ? patch.userId === null
+            ? ""
+            : patch.userId
+        : typeof existing.userId === "string"
+            ? existing.userId
+            : undefined;
+    const startDate = formatOptionalIso(patch.startDate !== undefined ? patch.startDate : existing.startDate);
+    const dueDate = formatOptionalIso(patch.dueDate !== undefined ? patch.dueDate : existing.dueDate);
+    const body = {
+        title,
+        description,
+        status,
+        priority: priorityRaw,
+        projectId,
+        position,
+    };
+    if (startDate !== undefined) {
+        body.startDate = startDate;
+    }
+    if (dueDate !== undefined) {
+        body.dueDate = dueDate;
+    }
+    if (userId !== undefined) {
+        body.userId = userId;
+    }
+    return body;
+}
+function formatOptionalIso(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return undefined;
+}

package/dist/server.js

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AuthService } from "./auth/auth-service.js";
+import { KaneoClient } from "./kaneo/client.js";
+import { registerTools } from "./tools/register.js";
+import { normalizeBaseUrl } from "./utils/normalize-base-url.js";
+const require = createRequire(import.meta.url);
+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 client = new KaneoClient({ baseUrl, auth });
+    const server = new McpServer({
+        name: "kaneo-mcp",
+        version: packageVersion,
+    });
+    registerTools(server, { client });
+    return server;
+}

package/dist/tools/register.js

@@ -0,0 +1,269 @@
+import { z } from "zod";
+import { buildFullTaskUpdateBody } from "../kaneo/task-helpers.js";
+import { errorResult, textResult } from "../utils/mcp-result.js";
+const prioritySchema = z.enum([
+    "no-priority",
+    "low",
+    "medium",
+    "high",
+    "urgent",
+]);
+const nonEmptyString = z.string().trim().min(1);
+const optionalNonEmptyString = nonEmptyString.optional();
+const nullableOptionalNonEmptyString = nonEmptyString.nullable().optional();
+const isoDateTimeSchema = z.string().datetime({ offset: true });
+const optionalIsoDateTimeSchema = isoDateTimeSchema.optional();
+const nullableOptionalIsoDateTimeSchema = isoDateTimeSchema
+    .nullable()
+    .optional();
+const hexColorSchema = z
+    .string()
+    .regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, "Expected a hex color like #FF6600");
+function run(fn) {
+    return fn()
+        .then((data) => textResult(data))
+        .catch((e) => errorResult(e instanceof Error ? e.message : String(e)));
+}
+export function registerTools(server, ctx) {
+    const { client } = ctx;
+    server.registerTool("whoami", {
+        description: "Return the current Kaneo session and user for the cached device token.",
+        inputSchema: z.object({}),
+    }, async () => run(() => client.json("/api/auth/get-session", { method: "GET" })));
+    server.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", {
+        description: "List projects in a workspace.",
+        inputSchema: z.object({
+            workspaceId: nonEmptyString.describe("Workspace ID"),
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe("Include archived projects"),
+        }),
+    }, async (args) => {
+        const { workspaceId, includeArchived } = args;
+        const qs = new URLSearchParams({ workspaceId });
+        if (includeArchived === true) {
+            qs.set("includeArchived", "true");
+        }
+        return run(() => client.json(`/api/project?${qs.toString()}`, { method: "GET" }));
+    });
+    server.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", {
+        description: "Create a project in a workspace.",
+        inputSchema: z.object({
+            name: nonEmptyString,
+            workspaceId: nonEmptyString,
+            icon: nonEmptyString,
+            slug: nonEmptyString,
+        }),
+    }, async (args) => run(() => client.json("/api/project", {
+        method: "POST",
+        body: JSON.stringify({
+            name: args.name,
+            workspaceId: args.workspaceId,
+            icon: args.icon,
+            slug: args.slug,
+        }),
+    })));
+    server.registerTool("update_project", {
+        description: "Update project metadata.",
+        inputSchema: z.object({
+            id: nonEmptyString,
+            name: nonEmptyString,
+            icon: nonEmptyString,
+            slug: nonEmptyString,
+            description: z.string(),
+            isPublic: z.boolean(),
+        }),
+    }, async (args) => run(() => client.json(`/api/project/${encodeURIComponent(args.id)}`, {
+        method: "PUT",
+        body: JSON.stringify({
+            name: args.name,
+            icon: args.icon,
+            slug: args.slug,
+            description: args.description,
+            isPublic: args.isPublic,
+        }),
+    })));
+    const listTasksSchema = z.object({
+        projectId: nonEmptyString,
+        status: optionalNonEmptyString,
+        priority: prioritySchema.optional(),
+        assigneeId: optionalNonEmptyString,
+        page: z.number().int().positive().optional(),
+        limit: z.number().int().positive().optional(),
+        sortBy: z
+            .enum(["createdAt", "priority", "dueDate", "position", "title", "number"])
+            .optional(),
+        sortOrder: z.enum(["asc", "desc"]).optional(),
+        dueBefore: optionalIsoDateTimeSchema,
+        dueAfter: optionalIsoDateTimeSchema,
+    });
+    server.registerTool("list_tasks", {
+        description: "List tasks for a project (optionally filtered/sorted).",
+        inputSchema: listTasksSchema,
+    }, async (args) => {
+        const { projectId, ...rest } = args;
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(rest)) {
+            if (v === undefined || v === null) {
+                continue;
+            }
+            qs.set(k, String(v));
+        }
+        const q = qs.toString();
+        const path = `/api/task/tasks/${encodeURIComponent(projectId)}${q ? `?${q}` : ""}`;
+        return run(() => client.json(path, { method: "GET" }));
+    });
+    server.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", {
+        description: "Create a task in a project.",
+        inputSchema: z.object({
+            projectId: nonEmptyString,
+            title: nonEmptyString,
+            description: z.string(),
+            priority: prioritySchema,
+            status: nonEmptyString,
+            startDate: optionalIsoDateTimeSchema,
+            dueDate: optionalIsoDateTimeSchema,
+            userId: optionalNonEmptyString,
+        }),
+    }, async (args) => {
+        const body = {
+            title: args.title,
+            description: args.description,
+            priority: args.priority,
+            status: args.status,
+        };
+        if (args.startDate !== undefined) {
+            body.startDate = args.startDate;
+        }
+        if (args.dueDate !== undefined) {
+            body.dueDate = args.dueDate;
+        }
+        if (args.userId !== undefined) {
+            body.userId = args.userId;
+        }
+        return run(() => client.json(`/api/task/${encodeURIComponent(args.projectId)}`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        }));
+    });
+    const updateTaskSchema = z.object({
+        taskId: nonEmptyString,
+        title: optionalNonEmptyString,
+        description: z.string().nullable().optional(),
+        status: optionalNonEmptyString,
+        priority: prioritySchema.optional(),
+        projectId: optionalNonEmptyString,
+        position: z.number().optional(),
+        startDate: nullableOptionalIsoDateTimeSchema,
+        dueDate: nullableOptionalIsoDateTimeSchema,
+        userId: nullableOptionalNonEmptyString,
+    });
+    server.registerTool("update_task", {
+        description: "Update a task (fetches current task, merges fields, then full update).",
+        inputSchema: updateTaskSchema,
+    }, async (args) => {
+        const { taskId, ...patch } = args;
+        return run(async () => {
+            const existing = (await client.json(`/api/task/${encodeURIComponent(taskId)}`, { method: "GET" }));
+            const body = buildFullTaskUpdateBody(existing, patch);
+            return client.json(`/api/task/${encodeURIComponent(taskId)}`, {
+                method: "PUT",
+                body: JSON.stringify(body),
+            });
+        });
+    });
+    server.registerTool("move_task", {
+        description: "Move a task to another project (and optional column status).",
+        inputSchema: z.object({
+            taskId: nonEmptyString,
+            destinationProjectId: nonEmptyString,
+            destinationStatus: optionalNonEmptyString,
+        }),
+    }, async (args) => run(() => client.json(`/api/task/move/${encodeURIComponent(args.taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify({
+            destinationProjectId: args.destinationProjectId,
+            ...(args.destinationStatus !== undefined
+                ? { destinationStatus: args.destinationStatus }
+                : {}),
+        }),
+    })));
+    server.registerTool("update_task_status", {
+        description: "Update only the status (column) of a task.",
+        inputSchema: z.object({
+            taskId: nonEmptyString,
+            status: nonEmptyString,
+        }),
+    }, async (args) => run(() => client.json(`/api/task/status/${encodeURIComponent(args.taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ status: args.status }),
+    })));
+    server.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", {
+        description: "Add a comment to a task.",
+        inputSchema: z.object({
+            taskId: nonEmptyString,
+            content: nonEmptyString,
+        }),
+    }, async (args) => run(() => client.json(`/api/comment/${encodeURIComponent(args.taskId)}`, {
+        method: "POST",
+        body: JSON.stringify({ content: args.content }),
+    })));
+    server.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", {
+        description: "Create a label in a workspace (optionally attach to a task).",
+        inputSchema: z.object({
+            name: nonEmptyString,
+            color: hexColorSchema,
+            workspaceId: nonEmptyString,
+            taskId: optionalNonEmptyString,
+        }),
+    }, async (args) => run(() => client.json("/api/label", {
+        method: "POST",
+        body: JSON.stringify({
+            name: args.name,
+            color: args.color,
+            workspaceId: args.workspaceId,
+            ...(args.taskId !== undefined ? { taskId: args.taskId } : {}),
+        }),
+    })));
+    server.registerTool("attach_label_to_task", {
+        description: "Attach an existing label to a task.",
+        inputSchema: z.object({
+            labelId: nonEmptyString,
+            taskId: nonEmptyString,
+        }),
+    }, async (args) => run(() => client.json(`/api/label/${encodeURIComponent(args.labelId)}/task`, {
+        method: "PUT",
+        body: JSON.stringify({ taskId: args.taskId }),
+    })));
+    server.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",
+    })));
+}

package/dist/utils/mcp-result.js

@@ -0,0 +1,14 @@
+export function textResult(data, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+        isError,
+    };
+}
+export function errorResult(message) {
+    return textResult({ error: message }, true);
+}

package/dist/utils/normalize-base-url.js

@@ -0,0 +1,18 @@
+/**
+ * Kaneo API base URL without trailing slash and without `/api` suffix.
+ */
+export function normalizeBaseUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    try {
+        const u = new URL(trimmed);
+        let path = u.pathname.replace(/\/+$/, "");
+        if (path === "/api" || path.endsWith("/api")) {
+            path = path.replace(/\/?api$/, "") || "/";
+            u.pathname = path;
+        }
+        return `${u.protocol}//${u.host}${path === "/" ? "" : path}`;
+    }
+    catch {
+        return trimmed.replace(/\/api\/?$/, "").replace(/\/+$/, "");
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@kaneo/mcp",
+	"version": "0.1.1",
+	"description": "Model Context Protocol (stdio) server for Kaneo — tasks, projects, labels, and device authorization",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"kaneo-mcp": "dist/index.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"kaneo",
+		"stdio"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"prepublishOnly": "npm run build",
+		"dev": "tsx watch src/index.ts",
+		"lint": "biome check --write .",
+		"start": "node dist/index.js",
+		"test": "vitest run --config vitest.config.ts",
+		"test:watch": "vitest --config vitest.config.ts"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.26.0",
+		"open": "^10.1.0",
+		"prompts": "^2.4.2",
+		"zod": "^3.25.0"
+	},
+	"devDependencies": {
+		"@kaneo/typescript-config": "workspace:*",
+		"@types/node": "^25.3.5",
+		"@types/prompts": "^2.4.9",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.1.2"
+	}
+}