@kanbodev/mcp 1.1.5 → 1.1.7

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@kanbodev/mcp.svg)](https://www.npmjs.com/package/@kanbodev/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-AI-native project management via [Model Context Protocol](https://modelcontextprotocol.io). Connect your AI assistant (Claude, Cursor, VS Code, Claude Code) to Kanbo and manage tickets, projects, releases, and workflows through natural conversation.
+AI-native project management via [Model Context Protocol](https://modelcontextprotocol.io). Connect your AI assistant (VS Code, Cursor, Windsurf, Claude Code, Claude Desktop) to Kanbo and manage tickets, projects, releases, and workflows through natural conversation.
 
 ## Quick Setup
 
@@ -15,7 +15,7 @@ That's it. This single command will:
 
 1. Open your browser to sign in and select your organization
 2. Store credentials locally at `~/.kanbo/config.json`
-3. **Auto-register the MCP server** with detected editors (VS Code, Cursor, Claude Desktop, Claude Code CLI)
+3. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
 
 Reload your editor and start using Kanbo tools immediately.
 

package/dist/index.js

@@ -29,6 +29,247 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/lib/errors.ts
+function isAppError(error) {
+  return error instanceof AppError;
+}
+function isKanboAPIError(error) {
+  return error instanceof KanboAPIError;
+}
+function getErrorCode(error) {
+  if (isAppError(error)) {
+    return error.code;
+  }
+  return ERROR_CODES.INTERNAL_ERROR;
+}
+var ERROR_CODES, AppError, ValidationError, KanboAPIError, APITimeoutError, APINotConfiguredError, InvalidAPIKeyError, APIKeyRevokedError, APIKeyExpiredError;
+var init_errors = __esm(() => {
+  ERROR_CODES = {
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+    VALIDATION_ERROR: "VALIDATION_ERROR",
+    NOT_FOUND: "NOT_FOUND",
+    UNAUTHORIZED: "UNAUTHORIZED",
+    FORBIDDEN: "FORBIDDEN",
+    BAD_REQUEST: "BAD_REQUEST",
+    CONFLICT: "CONFLICT",
+    TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+    TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+    INVALID_ARGUMENTS: "INVALID_ARGUMENTS",
+    API_ERROR: "API_ERROR",
+    API_TIMEOUT: "API_TIMEOUT",
+    API_RATE_LIMITED: "API_RATE_LIMITED",
+    API_UNAVAILABLE: "API_UNAVAILABLE",
+    API_NOT_CONFIGURED: "API_NOT_CONFIGURED",
+    INVALID_API_KEY: "INVALID_API_KEY",
+    API_KEY_REQUIRED: "API_KEY_REQUIRED",
+    API_KEY_REVOKED: "API_KEY_REVOKED",
+    API_KEY_EXPIRED: "API_KEY_EXPIRED",
+    NO_ORG_SELECTED: "NO_ORG_SELECTED",
+    PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+    NOT_PROJECT_MEMBER: "NOT_PROJECT_MEMBER",
+    TICKET_NOT_FOUND: "TICKET_NOT_FOUND",
+    INVALID_STATUS_TRANSITION: "INVALID_STATUS_TRANSITION",
+    STATUS_NOT_FOUND: "STATUS_NOT_FOUND",
+    COMMENT_NOT_FOUND: "COMMENT_NOT_FOUND",
+    NOT_COMMENT_CREATOR: "NOT_COMMENT_CREATOR",
+    TAG_NOT_FOUND: "TAG_NOT_FOUND",
+    TAG_ALREADY_EXISTS: "TAG_ALREADY_EXISTS",
+    BATCH_SIZE_EXCEEDED: "BATCH_SIZE_EXCEEDED",
+    BATCH_PARTIAL_FAILURE: "BATCH_PARTIAL_FAILURE"
+  };
+  AppError = class AppError extends Error {
+    code;
+    statusCode;
+    details;
+    isRetryable;
+    constructor(code, message, statusCode = 500, details, isRetryable = false) {
+      super(message);
+      this.name = "AppError";
+      this.code = code;
+      this.statusCode = statusCode;
+      this.details = details;
+      this.isRetryable = isRetryable;
+      if (Error.captureStackTrace) {
+        Error.captureStackTrace(this, this.constructor);
+      }
+    }
+    toJSON() {
+      return {
+        name: this.name,
+        code: this.code,
+        message: this.message,
+        statusCode: this.statusCode,
+        details: this.details,
+        isRetryable: this.isRetryable
+      };
+    }
+  };
+  ValidationError = class ValidationError extends AppError {
+    constructor(message, details) {
+      super(ERROR_CODES.VALIDATION_ERROR, message, 400, details);
+    }
+  };
+  KanboAPIError = class KanboAPIError extends AppError {
+    originalError;
+    constructor(message, statusCode = 500, originalError, details) {
+      const code = KanboAPIError.statusToErrorCode(statusCode);
+      const isRetryable = KanboAPIError.isStatusRetryable(statusCode);
+      super(code, message, statusCode, details, isRetryable);
+      this.name = "KanboAPIError";
+      this.originalError = originalError;
+    }
+    static statusToErrorCode(status) {
+      switch (status) {
+        case 400:
+          return ERROR_CODES.BAD_REQUEST;
+        case 401:
+          return ERROR_CODES.UNAUTHORIZED;
+        case 403:
+          return ERROR_CODES.FORBIDDEN;
+        case 404:
+          return ERROR_CODES.NOT_FOUND;
+        case 409:
+          return ERROR_CODES.CONFLICT;
+        case 422:
+          return ERROR_CODES.VALIDATION_ERROR;
+        case 429:
+          return ERROR_CODES.API_RATE_LIMITED;
+        case 503:
+          return ERROR_CODES.API_UNAVAILABLE;
+        default:
+          return ERROR_CODES.API_ERROR;
+      }
+    }
+    static isStatusRetryable(status) {
+      return status >= 500 || status === 429;
+    }
+  };
+  APITimeoutError = class APITimeoutError extends AppError {
+    constructor(timeoutMs) {
+      super(ERROR_CODES.API_TIMEOUT, `API request timed out after ${timeoutMs}ms`, 408, { timeoutMs }, true);
+    }
+  };
+  APINotConfiguredError = class APINotConfiguredError extends AppError {
+    constructor(message = "API client not configured") {
+      super(ERROR_CODES.API_NOT_CONFIGURED, message, 500);
+    }
+  };
+  InvalidAPIKeyError = class InvalidAPIKeyError extends AppError {
+    constructor(message = 'Invalid API key. Keys should start with "kanbo_pat_".') {
+      super(ERROR_CODES.INVALID_API_KEY, message, 401);
+    }
+  };
+  APIKeyRevokedError = class APIKeyRevokedError extends AppError {
+    constructor() {
+      super(ERROR_CODES.API_KEY_REVOKED, "This API key has been revoked. Please generate a new key from the Kanbo web app.", 401);
+    }
+  };
+  APIKeyExpiredError = class APIKeyExpiredError extends AppError {
+    constructor() {
+      super(ERROR_CODES.API_KEY_EXPIRED, "This API key has expired. Please generate a new key from the Kanbo web app.", 401);
+    }
+  };
+});
+
+// src/config/constants.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+function loadConfigFile() {
+  try {
+    const configPath = path.join(os.homedir(), ".kanbo", "config.json");
+    if (!fs.existsSync(configPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content);
+    if (config.version !== 1 || !config.apiKey) {
+      return null;
+    }
+    return config;
+  } catch {
+    return null;
+  }
+}
+function getApiKey() {
+  if (process.env.KANBO_API_KEY) {
+    return process.env.KANBO_API_KEY;
+  }
+  const config = loadConfigFile();
+  return config?.apiKey;
+}
+function getApiUrl() {
+  if (process.env.KANBO_API_URL) {
+    return process.env.KANBO_API_URL;
+  }
+  const config = loadConfigFile();
+  return config?.apiUrl || "https://api.kanbo.dev";
+}
+function getOrgId() {
+  if (process.env.KANBO_ORG_ID) {
+    return process.env.KANBO_ORG_ID;
+  }
+  const config = loadConfigFile();
+  return config?.orgId;
+}
+var CONFIG, SERVER_INFO, PAT_CONFIG, LIMITS, TICKET_LOCATIONS, TICKET_PRIORITIES, TICKET_SIZES, TAG_COLORS;
+var init_constants = __esm(() => {
+  init_errors();
+  CONFIG = {
+    KANBO_API_URL: getApiUrl(),
+    KANBO_API_KEY: getApiKey(),
+    TRANSPORT: process.env.TRANSPORT || "stdio",
+    PORT: parseInt(process.env.PORT || "8081", 10),
+    MAX_BODY_SIZE: 1048576,
+    CORS_ORIGINS: process.env.KANBO_CORS_ORIGINS?.split(",").map((s) => s.trim()).filter(Boolean) || [],
+    KANBO_ORG_ID: getOrgId(),
+    USE_OIDC_AUTH: process.env.USE_OIDC_AUTH === "true"
+  };
+  SERVER_INFO = {
+    name: "kanbo-mcp",
+    version: "1.1.7",
+    description: "MCP server for Kanbo project management"
+  };
+  PAT_CONFIG = {
+    PREFIX: "kanbo_pat_",
+    TOKEN_LENGTH: 58
+  };
+  LIMITS = {
+    TITLE_MIN: 1,
+    TITLE_MAX: 200,
+    DESCRIPTION_MAX: 5000,
+    ACCEPTANCE_CRITERIA_MAX: 1e4,
+    COMMENT_MAX: 2000,
+    NAME_MIN: 1,
+    NAME_MAX: 100,
+    TAG_NAME_MAX: 30,
+    PAGE_SIZE_DEFAULT: 20,
+    PAGE_SIZE_MAX: 100,
+    BATCH_SIZE_MAX: 50
+  };
+  TICKET_LOCATIONS = ["board", "backlog", "completed", "abandoned"];
+  TICKET_PRIORITIES = ["critical", "high", "medium", "low"];
+  TICKET_SIZES = ["xs", "s", "m", "l", "xl"];
+  TAG_COLORS = [
+    "gray",
+    "sky",
+    "blue",
+    "indigo",
+    "emerald",
+    "green",
+    "teal",
+    "cyan",
+    "amber",
+    "yellow",
+    "orange",
+    "red",
+    "violet",
+    "purple",
+    "fuchsia",
+    "pink"
+  ];
+});
+
 // node_modules/ajv/dist/compile/codegen/code.js
 var require_code = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
@@ -15534,6 +15775,7 @@ function startCallbackServer(port, expectedState, timeoutMs = 120000) {
       res.end(successHtml(email2, orgName));
       if (!resolved) {
         resolved = true;
+        server.closeAllConnections();
         server.close();
         resolve({
           success: true,
@@ -15555,6 +15797,7 @@ function startCallbackServer(port, expectedState, timeoutMs = 120000) {
     setTimeout(() => {
       if (!resolved) {
         resolved = true;
+        server.closeAllConnections();
         server.close();
         resolve({
           success: false,
@@ -15617,10 +15860,14 @@ function getConfigPath() {
   return CONFIG_PATH;
 }
 function maskApiKey(apiKey) {
-  if (!apiKey || apiKey.length < 15) {
+  if (!apiKey || apiKey.length < 10) {
     return "***";
   }
-  return apiKey.substring(0, 14) + "...";
+  const prefixEnd = apiKey.indexOf("_", apiKey.indexOf("_") + 1);
+  if (prefixEnd !== -1) {
+    return apiKey.substring(0, prefixEnd + 1) + "****";
+  }
+  return apiKey.substring(0, 4) + "****";
 }
 var CONFIG_DIR, CONFIG_PATH;
 var init_config = __esm(() => {
@@ -15639,20 +15886,39 @@ function getVscodeMcpPath() {
     return path3.join(os3.homedir(), "Library", "Application Support", "Code", "User", "mcp.json");
   }
   if (platform === "win32") {
-    return path3.join(process.env.APPDATA || "", "Code", "User", "mcp.json");
+    const appData = process.env.APPDATA || path3.join(os3.homedir(), "AppData", "Roaming");
+    return path3.join(appData, "Code", "User", "mcp.json");
   }
   return path3.join(os3.homedir(), ".config", "Code", "User", "mcp.json");
 }
+function getVscodeInsidersMcpPath() {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return path3.join(os3.homedir(), "Library", "Application Support", "Code - Insiders", "User", "mcp.json");
+  }
+  if (platform === "win32") {
+    const appData = process.env.APPDATA || path3.join(os3.homedir(), "AppData", "Roaming");
+    return path3.join(appData, "Code - Insiders", "User", "mcp.json");
+  }
+  return path3.join(os3.homedir(), ".config", "Code - Insiders", "User", "mcp.json");
+}
 function getCursorMcpPath() {
   return path3.join(os3.homedir(), ".cursor", "mcp.json");
 }
+function getWindsurfMcpPath() {
+  return path3.join(os3.homedir(), ".codeium", "windsurf", "mcp_config.json");
+}
+function getClaudeCodeSettingsPath() {
+  return path3.join(os3.homedir(), ".claude", "settings.json");
+}
 function getClaudeDesktopMcpPath() {
   const platform = process.platform;
   if (platform === "darwin") {
     return path3.join(os3.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
   if (platform === "win32") {
-    return path3.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
+    const appData = process.env.APPDATA || path3.join(os3.homedir(), "AppData", "Roaming");
+    return path3.join(appData, "Claude", "claude_desktop_config.json");
   }
   return path3.join(os3.homedir(), ".config", "Claude", "claude_desktop_config.json");
 }
@@ -15664,8 +15930,14 @@ function registerInConfigFile(configPath, hostName, serversKey = "servers") {
     }
     let config3 = {};
     if (fs3.existsSync(configPath)) {
-      const content = fs3.readFileSync(configPath, "utf-8");
-      config3 = JSON.parse(content);
+      try {
+        const content = fs3.readFileSync(configPath, "utf-8");
+        config3 = JSON.parse(content);
+      } catch {
+        const backupPath = configPath + ".backup";
+        fs3.copyFileSync(configPath, backupPath);
+        config3 = {};
+      }
     }
     const servers = config3[serversKey] || {};
     if (servers[SERVER_NAME]) {
@@ -15692,7 +15964,7 @@ function registerInConfigFile(configPath, hostName, serversKey = "servers") {
 }
 function isClaudeCliAvailable() {
   try {
-    execFileSync("claude", ["--version"], { stdio: "pipe" });
+    execFileSync("claude", ["--version"], { stdio: "pipe", ...shellOpt });
     return true;
   } catch {
     return false;
@@ -15705,7 +15977,8 @@ function registerWithClaudeCli() {
       return { host: hostName, success: false, message: "Claude Code CLI not detected" };
     }
     execFileSync("claude", ["mcp", "add", SERVER_NAME, "--", "npx", "@kanbodev/mcp"], {
-      stdio: "pipe"
+      stdio: "pipe",
+      ...shellOpt
     });
     return { host: hostName, success: true, message: "Registered via Claude Code CLI" };
   } catch (error2) {
@@ -15719,7 +15992,10 @@ function registerWithClaudeCli() {
 function registerMcpServer() {
   const results = [];
   results.push(registerInConfigFile(getVscodeMcpPath(), "VS Code"));
+  results.push(registerInConfigFile(getVscodeInsidersMcpPath(), "VS Code Insiders"));
   results.push(registerInConfigFile(getCursorMcpPath(), "Cursor"));
+  results.push(registerInConfigFile(getWindsurfMcpPath(), "Windsurf", "mcpServers"));
+  results.push(registerInConfigFile(getClaudeCodeSettingsPath(), "Claude Code", "mcpServers"));
   results.push(registerInConfigFile(getClaudeDesktopMcpPath(), "Claude Desktop", "mcpServers"));
   results.push(registerWithClaudeCli());
   return results;
@@ -15749,8 +16025,9 @@ function printRegistrationResults(results) {
   return anySuccess;
 }
 function printManualInstructions() {
-  console.log("  To register the MCP server manually, add this to your mcp.json:");
+  console.log("  To register the MCP server manually, add this to your editor config:");
   console.log("");
+  console.log("  For VS Code / Cursor (mcp.json):");
   console.log("    {");
   console.log('      "servers": {');
   console.log('        "kanbodev": {');
@@ -15761,21 +16038,36 @@ function printManualInstructions() {
   console.log("      }");
   console.log("    }");
   console.log("");
+  console.log("  For Claude Desktop / Windsurf / Claude Code:");
+  console.log("    {");
+  console.log('      "mcpServers": {');
+  console.log('        "kanbodev": {');
+  console.log('          "type": "stdio",');
+  console.log('          "command": "npx",');
+  console.log('          "args": ["@kanbodev/mcp"]');
+  console.log("        }");
+  console.log("      }");
+  console.log("    }");
+  console.log("");
   console.log("  Config file locations:");
-  console.log(`    VS Code:        ${getVscodeMcpPath()}`);
-  console.log(`    Cursor:         ${getCursorMcpPath()}`);
-  console.log(`    Claude Desktop: ${getClaudeDesktopMcpPath()}`);
+  console.log(`    VS Code:          ${getVscodeMcpPath()}`);
+  console.log(`    VS Code Insiders: ${getVscodeInsidersMcpPath()}`);
+  console.log(`    Cursor:           ${getCursorMcpPath()}`);
+  console.log(`    Windsurf:         ${getWindsurfMcpPath()}`);
+  console.log(`    Claude Code:      ${getClaudeCodeSettingsPath()}`);
+  console.log(`    Claude Desktop:   ${getClaudeDesktopMcpPath()}`);
   console.log("");
   console.log("  Or register via Claude Code CLI:");
   console.log("    claude mcp add kanbodev -- npx @kanbodev/mcp");
 }
-var SERVER_NAME = "kanbodev", MCP_SERVER_ENTRY;
+var SERVER_NAME = "kanbodev", MCP_SERVER_ENTRY, shellOpt;
 var init_register = __esm(() => {
   MCP_SERVER_ENTRY = {
     type: "stdio",
     command: "npx",
     args: ["@kanbodev/mcp"]
   };
+  shellOpt = process.platform === "win32" ? { shell: true } : {};
 });
 
 // node_modules/is-docker/index.js
@@ -16434,7 +16726,6 @@ __export(exports_login, {
   login: () => login
 });
 import * as crypto2 from "node:crypto";
-import { createRequire as createRequire2 } from "node:module";
 async function login() {
   console.log(`
   Kanbo CLI Login
@@ -16520,16 +16811,16 @@ async function login() {
   printRegistrationResults(registrationResults);
   console.log("");
 }
-var KANBO_WEB_URL, DEFAULT_API_URL, PORT_RANGE, require2, CLI_VERSION;
+var KANBO_WEB_URL, DEFAULT_API_URL, PORT_RANGE, CLI_VERSION;
 var init_login = __esm(() => {
   init_callback_server();
   init_config();
   init_register();
+  init_constants();
   KANBO_WEB_URL = process.env.KANBO_WEB_URL || "https://kanbo.dev";
   DEFAULT_API_URL = process.env.KANBO_API_URL || "https://api.kanbo.dev";
   PORT_RANGE = { start: 9876, end: 9899 };
-  require2 = createRequire2(import.meta.url);
-  CLI_VERSION = require2("../../package.json").version;
+  CLI_VERSION = SERVER_INFO.version;
 });
 
 // src/cli/logout.ts
@@ -16622,20 +16913,19 @@ async function install() {
   Kanbo MCP — Install
 `);
   const config3 = loadConfig();
-  if (!config3) {
-    console.log("  You are not logged in. Please authenticate first:");
-    console.log("    npx @kanbodev/mcp login");
-    console.log("");
-    console.log("  Or register the MCP server manually:");
-    console.log("");
-    printManualInstructions();
-    console.log("");
-    return;
+  if (config3) {
+    console.log(`  Logged in as ${config3.userEmail} (${config3.orgName})`);
+  } else {
+    console.log("  Not logged in yet — registering MCP server entry.");
+    console.log('  Run "npx @kanbodev/mcp login" to authenticate after install.');
   }
-  console.log(`  Logged in as ${config3.userEmail} (${config3.orgName})`);
   console.log("");
   const results = registerMcpServer();
-  printRegistrationResults(results);
+  const anySuccess = printRegistrationResults(results);
+  if (!anySuccess) {
+    console.log("");
+    printManualInstructions();
+  }
   console.log("");
 }
 var init_install = __esm(() => {
@@ -16643,243 +16933,8 @@ var init_install = __esm(() => {
   init_register();
 });
 
-// src/config/constants.ts
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-
-// src/lib/errors.ts
-var ERROR_CODES = {
-  INTERNAL_ERROR: "INTERNAL_ERROR",
-  VALIDATION_ERROR: "VALIDATION_ERROR",
-  NOT_FOUND: "NOT_FOUND",
-  UNAUTHORIZED: "UNAUTHORIZED",
-  FORBIDDEN: "FORBIDDEN",
-  BAD_REQUEST: "BAD_REQUEST",
-  CONFLICT: "CONFLICT",
-  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
-  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
-  INVALID_ARGUMENTS: "INVALID_ARGUMENTS",
-  API_ERROR: "API_ERROR",
-  API_TIMEOUT: "API_TIMEOUT",
-  API_RATE_LIMITED: "API_RATE_LIMITED",
-  API_UNAVAILABLE: "API_UNAVAILABLE",
-  API_NOT_CONFIGURED: "API_NOT_CONFIGURED",
-  INVALID_API_KEY: "INVALID_API_KEY",
-  API_KEY_REQUIRED: "API_KEY_REQUIRED",
-  API_KEY_REVOKED: "API_KEY_REVOKED",
-  API_KEY_EXPIRED: "API_KEY_EXPIRED",
-  NO_ORG_SELECTED: "NO_ORG_SELECTED",
-  PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
-  NOT_PROJECT_MEMBER: "NOT_PROJECT_MEMBER",
-  TICKET_NOT_FOUND: "TICKET_NOT_FOUND",
-  INVALID_STATUS_TRANSITION: "INVALID_STATUS_TRANSITION",
-  STATUS_NOT_FOUND: "STATUS_NOT_FOUND",
-  COMMENT_NOT_FOUND: "COMMENT_NOT_FOUND",
-  NOT_COMMENT_CREATOR: "NOT_COMMENT_CREATOR",
-  TAG_NOT_FOUND: "TAG_NOT_FOUND",
-  TAG_ALREADY_EXISTS: "TAG_ALREADY_EXISTS",
-  BATCH_SIZE_EXCEEDED: "BATCH_SIZE_EXCEEDED",
-  BATCH_PARTIAL_FAILURE: "BATCH_PARTIAL_FAILURE"
-};
-
-class AppError extends Error {
-  code;
-  statusCode;
-  details;
-  isRetryable;
-  constructor(code, message, statusCode = 500, details, isRetryable = false) {
-    super(message);
-    this.name = "AppError";
-    this.code = code;
-    this.statusCode = statusCode;
-    this.details = details;
-    this.isRetryable = isRetryable;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      statusCode: this.statusCode,
-      details: this.details,
-      isRetryable: this.isRetryable
-    };
-  }
-}
-class ValidationError extends AppError {
-  constructor(message, details) {
-    super(ERROR_CODES.VALIDATION_ERROR, message, 400, details);
-  }
-}
-class KanboAPIError extends AppError {
-  originalError;
-  constructor(message, statusCode = 500, originalError, details) {
-    const code = KanboAPIError.statusToErrorCode(statusCode);
-    const isRetryable = KanboAPIError.isStatusRetryable(statusCode);
-    super(code, message, statusCode, details, isRetryable);
-    this.name = "KanboAPIError";
-    this.originalError = originalError;
-  }
-  static statusToErrorCode(status) {
-    switch (status) {
-      case 400:
-        return ERROR_CODES.BAD_REQUEST;
-      case 401:
-        return ERROR_CODES.UNAUTHORIZED;
-      case 403:
-        return ERROR_CODES.FORBIDDEN;
-      case 404:
-        return ERROR_CODES.NOT_FOUND;
-      case 409:
-        return ERROR_CODES.CONFLICT;
-      case 422:
-        return ERROR_CODES.VALIDATION_ERROR;
-      case 429:
-        return ERROR_CODES.API_RATE_LIMITED;
-      case 503:
-        return ERROR_CODES.API_UNAVAILABLE;
-      default:
-        return ERROR_CODES.API_ERROR;
-    }
-  }
-  static isStatusRetryable(status) {
-    return status >= 500 || status === 429;
-  }
-}
-
-class APITimeoutError extends AppError {
-  constructor(timeoutMs) {
-    super(ERROR_CODES.API_TIMEOUT, `API request timed out after ${timeoutMs}ms`, 408, { timeoutMs }, true);
-  }
-}
-
-class APINotConfiguredError extends AppError {
-  constructor(message = "API client not configured") {
-    super(ERROR_CODES.API_NOT_CONFIGURED, message, 500);
-  }
-}
-class InvalidAPIKeyError extends AppError {
-  constructor(message = 'Invalid API key. Keys should start with "kanbo_pat_".') {
-    super(ERROR_CODES.INVALID_API_KEY, message, 401);
-  }
-}
-class APIKeyRevokedError extends AppError {
-  constructor() {
-    super(ERROR_CODES.API_KEY_REVOKED, "This API key has been revoked. Please generate a new key from the Kanbo web app.", 401);
-  }
-}
-
-class APIKeyExpiredError extends AppError {
-  constructor() {
-    super(ERROR_CODES.API_KEY_EXPIRED, "This API key has expired. Please generate a new key from the Kanbo web app.", 401);
-  }
-}
-function isAppError(error) {
-  return error instanceof AppError;
-}
-function isKanboAPIError(error) {
-  return error instanceof KanboAPIError;
-}
-function getErrorCode(error) {
-  if (isAppError(error)) {
-    return error.code;
-  }
-  return ERROR_CODES.INTERNAL_ERROR;
-}
-
-// src/config/constants.ts
-function loadConfigFile() {
-  try {
-    const configPath = path.join(os.homedir(), ".kanbo", "config.json");
-    if (!fs.existsSync(configPath)) {
-      return null;
-    }
-    const content = fs.readFileSync(configPath, "utf-8");
-    const config = JSON.parse(content);
-    if (config.version !== 1 || !config.apiKey) {
-      return null;
-    }
-    return config;
-  } catch {
-    return null;
-  }
-}
-function getApiKey() {
-  if (process.env.KANBO_API_KEY) {
-    return process.env.KANBO_API_KEY;
-  }
-  const config = loadConfigFile();
-  return config?.apiKey;
-}
-function getApiUrl() {
-  if (process.env.KANBO_API_URL) {
-    return process.env.KANBO_API_URL;
-  }
-  const config = loadConfigFile();
-  return config?.apiUrl || "https://api.kanbo.dev";
-}
-function getOrgId() {
-  if (process.env.KANBO_ORG_ID) {
-    return process.env.KANBO_ORG_ID;
-  }
-  const config = loadConfigFile();
-  return config?.orgId;
-}
-var CONFIG = {
-  KANBO_API_URL: getApiUrl(),
-  KANBO_API_KEY: getApiKey(),
-  TRANSPORT: process.env.TRANSPORT || "stdio",
-  PORT: parseInt(process.env.PORT || "8081", 10),
-  KANBO_ORG_ID: getOrgId(),
-  USE_OIDC_AUTH: process.env.USE_OIDC_AUTH === "true"
-};
-var SERVER_INFO = {
-  name: "kanbo-mcp",
-  version: "1.1.5",
-  description: "MCP server for Kanbo project management"
-};
-var PAT_CONFIG = {
-  PREFIX: "kanbo_pat_",
-  TOKEN_LENGTH: 58
-};
-var LIMITS = {
-  TITLE_MIN: 1,
-  TITLE_MAX: 200,
-  DESCRIPTION_MAX: 5000,
-  ACCEPTANCE_CRITERIA_MAX: 1e4,
-  COMMENT_MAX: 2000,
-  NAME_MIN: 1,
-  NAME_MAX: 100,
-  TAG_NAME_MAX: 30,
-  PAGE_SIZE_DEFAULT: 20,
-  PAGE_SIZE_MAX: 100,
-  BATCH_SIZE_MAX: 50
-};
-var TICKET_LOCATIONS = ["board", "backlog", "completed", "abandoned"];
-var TICKET_PRIORITIES = ["critical", "high", "medium", "low"];
-var TICKET_SIZES = ["xs", "s", "m", "l", "xl"];
-var TAG_COLORS = [
-  "gray",
-  "sky",
-  "blue",
-  "indigo",
-  "emerald",
-  "green",
-  "teal",
-  "cyan",
-  "amber",
-  "yellow",
-  "orange",
-  "red",
-  "violet",
-  "purple",
-  "fuchsia",
-  "pink"
-];
+// src/index.ts
+init_constants();
 
 // node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
@@ -24020,9 +24075,18 @@ class StdioServerTransport {
   }
 }
 
+// src/server.ts
+init_constants();
+
 // src/lib/client/index.ts
+init_constants();
+init_errors();
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
+// src/lib/client/core.ts
+init_errors();
+init_constants();
+
 // src/config/endpoints.ts
 var EP = {
   AUTH: {
@@ -24207,7 +24271,7 @@ var baseLogger = import_pino.default({
   name: config2.appName,
   level: config2.level,
   redact: {
-    paths: REDACT_PATHS.map((p) => `*.${p}`),
+    paths: REDACT_PATHS.flatMap((p) => [p, `*.${p}`]),
     censor: "[REDACTED]"
   },
   serializers: {
@@ -24218,12 +24282,8 @@ var baseLogger = import_pino.default({
   base: {
     service: config2.appName,
     env: "development"
-  },
-  transport: {
-    target: "pino/file",
-    options: { destination: 2 }
   }
-});
+}, import_pino.default.destination(2));
 function createLogger(bindings = {}) {
   const boundLogger = Object.keys(bindings).length > 0 ? baseLogger.child(bindings) : baseLogger;
   const createBoundLogFn = (level) => {
@@ -24329,6 +24389,8 @@ class KanboClient {
   orgId;
   useOidcAuth;
   authContext;
+  authContextCachedAt;
+  static AUTH_CONTEXT_TTL_MS = 60 * 60 * 1000;
   authContextPromise;
   constructor(config3) {
     this.apiUrl = config3.apiUrl.replace(/\/$/, "");
@@ -24352,7 +24414,7 @@ class KanboClient {
     return this._request(method, path2, body, options);
   }
   async _request(method, path2, body, options) {
-    if (path2.includes("..") || path2.includes("%2F") || path2.includes("%2f") || path2.includes("%00")) {
+    if (path2.includes("..") || path2.includes("%2F") || path2.includes("%2f") || path2.includes("%00") || path2.includes("%25")) {
       throw new ValidationError(`Invalid path: contains forbidden characters`);
     }
     let url = `${this.apiUrl}/api${path2}`;
@@ -24468,8 +24530,13 @@ class KanboClient {
     return this.orgId;
   }
   async validateAndGetContext() {
-    if (this.authContext) {
-      return this.authContext;
+    if (this.authContext && this.authContextCachedAt) {
+      const age = Date.now() - this.authContextCachedAt;
+      if (age < KanboClient.AUTH_CONTEXT_TTL_MS) {
+        return this.authContext;
+      }
+      this.authContext = undefined;
+      this.authContextCachedAt = undefined;
     }
     if (this.authContextPromise) {
       return this.authContextPromise;
@@ -24477,6 +24544,7 @@ class KanboClient {
     this.authContextPromise = this.fetchAuthContext();
     try {
       const context = await this.authContextPromise;
+      this.authContextPromise = undefined;
       return context;
     } catch (error2) {
       this.authContextPromise = undefined;
@@ -24504,6 +24572,7 @@ class KanboClient {
         organizations: org ? [org] : [],
         currentOrg: org || undefined
       };
+      this.authContextCachedAt = Date.now();
       if (!this.orgId && this.authContext.organizations.length > 0) {
         this.orgId = this.authContext.organizations[0].id;
       }
@@ -24581,6 +24650,7 @@ KanboClient.prototype.removeProjectMember = async function(projectId, userId) {
 };
 
 // src/lib/client/tickets.ts
+init_errors();
 KanboClient.prototype.listTickets = async function(projectId, params) {
   return this.get(EP.TICKETS.LIST(projectId), params);
 };
@@ -24591,17 +24661,19 @@ KanboClient.prototype.getMyTickets = async function(projectId, params) {
     return this.listTickets(projectId, { ...params, assigneeId });
   }
   const projects = await this.listProjects();
-  const allTickets = [];
   const perProjectLimit = params?.limit ?? 20;
-  for (const project of projects.data) {
-    try {
-      const result = await this.listTickets(project.id, {
-        ...params,
-        assigneeId,
-        limit: perProjectLimit
-      });
-      allTickets.push(...result.data);
-    } catch {}
+  const results = await Promise.allSettled(projects.data.map((project) => this.listTickets(project.id, {
+    ...params,
+    assigneeId,
+    limit: perProjectLimit
+  })));
+  const allTickets = [];
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      allTickets.push(...result.value.data);
+    } else if (isKanboAPIError(result.reason) && result.reason.statusCode === 401) {
+      throw result.reason;
+    }
   }
   return { data: allTickets };
 };
@@ -24974,9 +25046,12 @@ function getKanboClient() {
   if (requestClient) {
     return requestClient;
   }
+  if (CONFIG.TRANSPORT === "http") {
+    throw new APINotConfiguredError("No request-scoped client available. In HTTP mode, all tool calls must run within runWithClient().");
+  }
   if (!clientInstance) {
     if (!CONFIG.KANBO_API_KEY) {
-      throw new APINotConfiguredError("No API key available. In HTTP mode, include Authorization header. " + "In stdio mode, set KANBO_API_KEY environment variable.");
+      throw new APINotConfiguredError('No API key available. Set KANBO_API_KEY environment variable or run "kanbo-mcp login".');
     }
     clientInstance = new KanboClient({
       apiKey: CONFIG.KANBO_API_KEY,
@@ -24986,7 +25061,11 @@ function getKanboClient() {
   }
   return clientInstance;
 }
+// src/server.ts
+init_errors();
+
 // src/tools/types.ts
+init_errors();
 function successResult(data) {
   return { success: true, data };
 }
@@ -25007,6 +25086,47 @@ function errorResultFromError(error2) {
   const details = isAppError(error2) ? error2.details : undefined;
   return errorResult(code, message, details);
 }
+var JSON_TYPE_CHECKS = {
+  string: (v) => typeof v === "string",
+  number: (v) => typeof v === "number",
+  integer: (v) => typeof v === "number" && Number.isInteger(v),
+  boolean: (v) => typeof v === "boolean",
+  array: (v) => Array.isArray(v),
+  object: (v) => typeof v === "object" && v !== null && !Array.isArray(v)
+};
+function validateToolArgs(args, schema) {
+  if (!schema || schema.type !== "object")
+    return null;
+  const properties = schema.properties ?? {};
+  const required2 = schema.required ?? [];
+  for (const key of required2) {
+    if (args[key] === undefined || args[key] === null) {
+      return errorResult(ERROR_CODES.INVALID_ARGUMENTS, `Missing required argument: ${key}`);
+    }
+  }
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    const prop = properties[key];
+    if (!prop?.type)
+      continue;
+    const checker = JSON_TYPE_CHECKS[prop.type];
+    if (checker && !checker(value)) {
+      return errorResult(ERROR_CODES.INVALID_ARGUMENTS, `Argument '${key}' must be of type ${prop.type}, got ${typeof value}`);
+    }
+  }
+  return null;
+}
+function withArgValidation(tool, handler) {
+  if (!tool.inputSchema)
+    return handler;
+  return async (args) => {
+    const validationError = validateToolArgs(args, tool.inputSchema);
+    if (validationError)
+      return validationError;
+    return handler(args);
+  };
+}
 function formatToolResult(result) {
   return JSON.stringify(result, null, 2);
 }
@@ -25339,6 +25459,8 @@ var projectTools = [
 ];
 
 // src/tools/tickets.ts
+init_errors();
+init_constants();
 var listTicketsTool = {
   tool: {
     name: "list_tickets",
@@ -25457,6 +25579,12 @@ var getTicketByKeyTool = {
       const client = getKanboClient();
       const authContext = client.getAuthContext();
       let orgSlug = args.orgSlug;
+      if (orgSlug && authContext?.organizations?.length) {
+        const isAuthorized = authContext.organizations.some((o) => o.slug === orgSlug);
+        if (!isAuthorized) {
+          return errorResult(ERROR_CODES.NO_ORG_SELECTED, "You do not have access to the specified organization.");
+        }
+      }
       if (!orgSlug && authContext?.currentOrg) {
         orgSlug = authContext.currentOrg.slug;
       }
@@ -26658,6 +26786,7 @@ var workflowTools = [
 ];
 
 // src/tools/comments.ts
+init_constants();
 var listCommentsTool = {
   tool: {
     name: "list_comments",
@@ -26837,6 +26966,7 @@ var commentTools = [
 ];
 
 // src/tools/tags.ts
+init_constants();
 var listTagsTool = {
   tool: {
     name: "list_tags",
@@ -28823,6 +28953,7 @@ var usageTools = [
 ];
 
 // src/tools/organization.ts
+init_errors();
 var listOrganizationsTool = {
   tool: {
     name: "list_organizations",
@@ -29051,6 +29182,8 @@ var watcherTools = [
 ];
 
 // src/tools/batch.ts
+init_errors();
+init_constants();
 var BATCH_CONCURRENCY_LIMIT = 5;
 async function mapWithConcurrency(items, fn, concurrency = BATCH_CONCURRENCY_LIMIT) {
   const results = new Array(items.length);
@@ -29527,8 +29660,33 @@ var TOOL_INDEX = {
     "Usage & Billing": {
       tools: ["get_mcp_usage", "get_ai_usage"],
       description: "Check MCP request and AI token quotas."
+    },
+    Git: {
+      tools: ["get_commit_prefix"],
+      description: "Git commit conventions. Use get_commit_prefix to generate properly formatted commit message prefixes from ticket keys."
     }
   },
+  git_conventions: {
+    description: "IMPORTANT: Follow these conventions when committing code related to Kanbo tickets. This ensures commits appear in the Git tab of each ticket in the Kanbo UI.",
+    commit_message_format: {
+      single_ticket: "<TICKET_KEY>: <description>",
+      multiple_tickets: "<TICKET_KEY_1> <TICKET_KEY_2>: <description>",
+      examples: [
+        "WHLZ-59: implement Google OAuth login flow",
+        "WHLZ-59 WHLZ-60: add shared auth middleware for OAuth providers",
+        "UNO-12: fix pagination bug in ticket list"
+      ]
+    },
+    rules: [
+      "ALWAYS prefix commit messages with the ticket key(s) you are working on",
+      "The ticket key format is PROJECT_PREFIX-NUMBER (e.g., WHLZ-59, UNO-12)",
+      "Use get_commit_prefix tool to generate the correct prefix for one or more tickets",
+      "The prefix links commits to tickets in the Kanbo UI Git tab — without it, commits are invisible to the ticket",
+      'Use lowercase description after the prefix, starting with a verb (e.g., "add", "fix", "update", "refactor")',
+      "Keep the first line under 72 characters"
+    ],
+    workflow: "get_ticket or get_ticket_by_key (note the ticket key) → do the work → get_commit_prefix(ticketKeys) → git commit with the returned prefix"
+  },
   common_workflows: {
     "Create a high-quality ticket": "list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags (cache IDs) → find_similar_tickets (ALWAYS check for duplicates/related tickets — link via parentId if related) → create_ticket (with description, acceptanceCriteria [REQUIRED], typeSlug) → set_ticket_tags (add 2-5 tags)",
     "AI-assisted ticket creation": "find_similar_tickets (check duplicates/related first) → check_clarity → polish_title → generate_description → suggest_attributes → create_ticket (ALWAYS include acceptanceCriteria + parentId if related ticket found) → set_ticket_tags",
@@ -29537,7 +29695,8 @@ var TOOL_INDEX = {
     "Daily standup": "get_my_tickets + get_overdue_tickets + get_tickets_due_soon",
     "Release shipping": "get_release_tickets (verify all complete) → mark_release_shipped",
     "Bulk cleanup": "list_tickets (filter) → batch_complete_tickets or batch_move_tickets",
-    "Team workload review": "get_member_analytics + get_distribution_analytics"
+    "Team workload review": "get_member_analytics + get_distribution_analytics",
+    "Committing code for a ticket": 'get_ticket_by_key (note ticket key) → implement changes → get_commit_prefix(ticketKeys: ["PROJ-123"]) → git commit -m "<prefix> <description>"'
   }
 };
 var helpTools = [
@@ -29576,6 +29735,54 @@ var helpTools = [
     }
   }
 ];
+
+// src/tools/git.ts
+init_errors();
+var TICKET_KEY_PATTERN = /^[A-Z][A-Z0-9]+-\d+$/;
+var getCommitPrefixTool = {
+  tool: {
+    name: "get_commit_prefix",
+    description: "Generate a properly formatted git commit message prefix from one or more Kanbo ticket keys. " + "IMPORTANT: Always use this before committing code related to Kanbo tickets. " + "The prefix ensures commits appear in the Git tab of each ticket in the Kanbo UI. " + "Without the prefix, commits will not be linked to tickets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ticketKeys: {
+          type: "array",
+          items: { type: "string" },
+          description: 'One or more ticket keys (e.g., ["WHLZ-59"] or ["WHLZ-59", "WHLZ-60"]). ' + "Use the ticket key format: PROJECT_PREFIX-NUMBER."
+        }
+      },
+      required: ["ticketKeys"]
+    }
+  },
+  handler: async (args) => {
+    const ticketKeys = args.ticketKeys;
+    if (!Array.isArray(ticketKeys) || ticketKeys.length === 0) {
+      return errorResult(ERROR_CODES.INVALID_ARGUMENTS, 'ticketKeys must be a non-empty array of ticket keys (e.g., ["WHLZ-59"])');
+    }
+    const invalidKeys = ticketKeys.filter((key) => !TICKET_KEY_PATTERN.test(key));
+    if (invalidKeys.length > 0) {
+      return errorResult(ERROR_CODES.INVALID_ARGUMENTS, `Invalid ticket key format: ${invalidKeys.join(", ")}. Expected format: PROJECT_PREFIX-NUMBER (e.g., WHLZ-59, UNO-12)`);
+    }
+    const uniqueKeys = [...new Set(ticketKeys)];
+    const prefix = uniqueKeys.join(" ");
+    return successResult({
+      prefix: `${prefix}:`,
+      example: `${prefix}: <describe your change>`,
+      format_rules: [
+        "Use lowercase description after the prefix",
+        "Start with a verb: add, fix, update, refactor, remove, implement",
+        "Keep the first line under 72 characters"
+      ],
+      examples: [
+        `${prefix}: implement the feature`,
+        `${prefix}: fix validation bug`,
+        `${prefix}: update error handling`
+      ]
+    });
+  }
+};
+var gitTools = [getCommitPrefixTool];
 // src/tools/index.ts
 var allToolDefinitions = [
   ...helpTools,
@@ -29597,7 +29804,8 @@ var allToolDefinitions = [
   ...analyticsTools,
   ...notificationTools,
   ...aiTools,
-  ...usageTools
+  ...usageTools,
+  ...gitTools
 ];
 
 class ToolRegistryImpl {
@@ -29610,7 +29818,7 @@ class ToolRegistryImpl {
   }
   register(definition) {
     this.tools.push(definition.tool);
-    this.handlers.set(definition.tool.name, definition.handler);
+    this.handlers.set(definition.tool.name, withArgValidation(definition.tool, definition.handler));
   }
   getTool(name) {
     return this.tools.find((t) => t.name === name);
@@ -43942,6 +44150,9 @@ var _Elysia = class _Elysia2 {
 };
 var Elysia = _Elysia;
 
+// src/server-http.ts
+init_constants();
+
 // src/config/routes.ts
 var ROUTES = {
   HEALTH: {
@@ -43959,6 +44170,7 @@ var ROUTES = {
 };
 
 // src/server-http.ts
+init_errors();
 var httpLogger = logger.withCategory(LogCategory.SYSTEM);
 function extractApiKey(request) {
   const apiKeyHeader = request.headers.get("x-kanbo-api-key");
@@ -43977,6 +44189,12 @@ function extractApiKey(request) {
   }
   return null;
 }
+function jsonErrorResponse(status2, code, message) {
+  return new Response(JSON.stringify({
+    success: false,
+    error: { code, message, timestamp: new Date().toISOString() }
+  }), { status: status2, headers: { "Content-Type": "application/json" } });
+}
 function unauthorizedResponse(message) {
   return new Response(JSON.stringify({
     success: false,
@@ -43992,7 +44210,36 @@ function unauthorizedResponse(message) {
 }
 async function startHttpServer() {
   httpLogger.info("Starting in HTTP mode with per-request authentication");
-  const app = new Elysia().get(ROUTES.HEALTH.INDEX, () => ({
+  const app = new Elysia().onRequest(({ request }) => {
+    const origin = request.headers.get("origin");
+    if (request.method === "OPTIONS") {
+      const headers = {
+        "Access-Control-Max-Age": "86400",
+        "Access-Control-Allow-Methods": "GET, POST",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Kanbo-API-Key"
+      };
+      if (origin && CONFIG.CORS_ORIGINS.includes(origin)) {
+        headers["Access-Control-Allow-Origin"] = origin;
+        headers["Vary"] = "Origin";
+      }
+      return new Response(null, { status: 204, headers });
+    }
+  }).onAfterHandle(({ request, response }) => {
+    const origin = request.headers.get("origin");
+    if (origin && CONFIG.CORS_ORIGINS.includes(origin) && response instanceof Response) {
+      response.headers.set("Access-Control-Allow-Origin", origin);
+      response.headers.set("Vary", "Origin");
+    }
+  }).onParse(({ request }) => {
+    const contentLength = parseInt(request.headers.get("content-length") || "0", 10);
+    if (contentLength > CONFIG.MAX_BODY_SIZE) {
+      throw new Error(`PAYLOAD_TOO_LARGE`);
+    }
+  }).onError(({ error: error2 }) => {
+    if (error2.message === "PAYLOAD_TOO_LARGE") {
+      return jsonErrorResponse(413, ERROR_CODES.VALIDATION_ERROR, `Request body too large. Maximum size is ${CONFIG.MAX_BODY_SIZE} bytes.`);
+    }
+  }).get(ROUTES.HEALTH.INDEX, () => ({
     status: "ok",
     server: SERVER_INFO.name,
     version: SERVER_INFO.version

package/docs/GIT_CONVENTIONS.md

@@ -0,0 +1,139 @@
+# Git Commit Conventions
+
+> **Purpose**: Ensures git commits are linked to Kanbo tickets and appear in the **Git tab** of the Kanbo UI. Any AI agent using the Kanbo MCP server should follow these conventions when committing code.
+>
+> **Last Updated**: 2026-03-12
+
+---
+
+## Overview
+
+Kanbo's Git tab tracks commits associated with a ticket by matching the **ticket key prefix** in commit messages. When a commit message starts with a ticket key (e.g., `WHLZ-59:`), that commit is automatically linked to the ticket and displayed in its Git tab.
+
+Without the correct prefix, commits are **invisible** to the ticket — there is no way to retroactively link them.
+
+---
+
+## Commit Message Format
+
+### Single Ticket
+
+```
+<TICKET_KEY>: <description>
+```
+
+**Examples:**
+
+```
+WHLZ-59: implement Google OAuth login flow
+UNO-12: fix pagination bug in ticket list
+KANBO-7: add rate limiting middleware
+```
+
+### Multiple Tickets
+
+When a single commit applies to more than one ticket, include all keys separated by spaces:
+
+```
+<TICKET_KEY_1> <TICKET_KEY_2>: <description>
+```
+
+**Examples:**
+
+```
+WHLZ-59 WHLZ-60: add shared auth middleware for OAuth providers
+UNO-12 UNO-15: refactor validation logic for both endpoints
+```
+
+---
+
+## Rules
+
+| Rule | Details |
+|------|---------|
+| **Always prefix** | Every commit related to a Kanbo ticket MUST start with the ticket key(s) |
+| **Key format** | `PROJECT_PREFIX-NUMBER` — uppercase letters followed by a dash and number (e.g., `WHLZ-59`) |
+| **Description style** | Lowercase, starting with a verb (`add`, `fix`, `update`, `refactor`, `remove`, `implement`) |
+| **Line length** | Keep the first line under 72 characters |
+| **No prefix = no link** | Commits without the ticket key prefix will NOT appear in the Kanbo Git tab |
+
+---
+
+## MCP Tool: `get_commit_prefix`
+
+The Kanbo MCP server provides a `get_commit_prefix` tool that generates properly formatted commit message prefixes.
+
+### Usage
+
+```json
+{
+  "tool": "get_commit_prefix",
+  "arguments": {
+    "ticketKeys": ["WHLZ-59"]
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "prefix": "WHLZ-59:",
+    "example": "WHLZ-59: <describe your change>",
+    "format_rules": [
+      "Use lowercase description after the prefix",
+      "Start with a verb: add, fix, update, refactor, remove, implement",
+      "Keep the first line under 72 characters"
+    ],
+    "examples": [
+      "WHLZ-59: implement the feature",
+      "WHLZ-59: fix validation bug",
+      "WHLZ-59: update error handling"
+    ]
+  }
+}
+```
+
+### Multiple Tickets
+
+```json
+{
+  "tool": "get_commit_prefix",
+  "arguments": {
+    "ticketKeys": ["WHLZ-59", "WHLZ-60"]
+  }
+}
+```
+
+Returns prefix: `WHLZ-59 WHLZ-60:`
+
+### Validation
+
+The tool validates that each key matches the expected format (`PROJECT_PREFIX-NUMBER`). Invalid keys like `whlz-59`, `WHLZ59`, or `59` will return an error with guidance on the correct format.
+
+---
+
+## Agent Workflow
+
+The recommended workflow for an AI agent working on a Kanbo ticket:
+
+```
+1. get_ticket_by_key("WHLZ-59")     — Retrieve ticket details
+2. Implement the changes              — Write code
+3. get_commit_prefix(["WHLZ-59"])    — Get the formatted prefix
+4. git commit -m "WHLZ-59: ..."      — Commit with the prefix
+```
+
+This workflow is also documented in the `get_help` tool under `common_workflows` → "Committing code for a ticket" and in the `git_conventions` section.
+
+---
+
+## Discovery
+
+Agents discover these conventions through:
+
+1. **`get_help` tool** — The `git_conventions` section describes the format, rules, and workflow
+2. **`get_commit_prefix` tool** — The tool description itself explains why the prefix is required
+3. **`common_workflows`** — The "Committing code for a ticket" workflow guides agents step-by-step

package/docs/SETUP.md

@@ -18,7 +18,7 @@ This will:
 1. Open your browser to sign in with your Kanbo account
 2. Let you select which organization to use
 3. Automatically create and store an API key
-4. **Auto-register the MCP server** with detected editors (VS Code, Cursor, Claude Desktop, Claude Code CLI)
+4. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)
 
 You'll see output like:
 
@@ -129,7 +129,7 @@ This means you can:
 
 ## Using with Other AI Tools
 
-> **Note:** `npx @kanbodev/mcp login` auto-registers with VS Code, Cursor, Claude Desktop, and Claude Code CLI. The manual configs below are only needed if auto-registration didn't detect your editor.
+> **Note:** `npx @kanbodev/mcp login` auto-registers with VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, and Claude Code CLI. The manual configs below are only needed if auto-registration didn't detect your editor.
 
 ### Cursor
 
@@ -151,6 +151,38 @@ Add to `~/.cursor/mcp.json`:
 
 See the full [VS Code setup guide](VSCODE.md) for native MCP support (v1.99+), Claude Code extension, and Cursor/Windsurf.
 
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (VS Code Extension)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "kanbodev": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@kanbodev/mcp"]
+    }
+  }
+}
+```
+
 ### Claude Code CLI
 
 ```bash

package/docs/VSCODE.md

@@ -94,7 +94,7 @@ Open the terminal in VS Code and run:
 claude mcp add kanbo -- npx @kanbodev/mcp
 ```
 
-This writes the config to `~/.claude.json` (global) by default.
+This writes the config to `~/.claude.json` (global) by default. The `login` command also auto-registers in `~/.claude/settings.json`.
 
 ### Via config file
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanbodev/mcp",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "MCP (Model Context Protocol) server for Kanbo - AI-native project management",
   "type": "module",
   "main": "dist/index.js",