karajan-code 1.2.0

package/src/mcp/server-handlers.js

@@ -0,0 +1,259 @@
+/**
+ * MCP server handler logic.
+ * Extracted from server.js for testability.
+ */
+
+import { EventEmitter } from "node:events";
+import { runKjCommand } from "./run-kj.js";
+import { normalizePlanArgs } from "./tool-arg-normalizers.js";
+import { buildProgressHandler, buildProgressNotifier } from "./progress.js";
+import { runFlow, resumeFlow } from "../orchestrator.js";
+import { loadConfig, applyRunOverrides, validateConfig, resolveRole } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+
+export function asObject(value) {
+  if (value && typeof value === "object") return value;
+  return {};
+}
+
+export function responseText(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+
+export function failPayload(message, details = {}) {
+  return {
+    ok: false,
+    error: message,
+    ...details
+  };
+}
+
+export function classifyError(error) {
+  const msg = error?.message || String(error);
+  const lower = msg.toLowerCase();
+
+  if (lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running"))) {
+    return {
+      category: "sonar_unavailable",
+      suggestion: "SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube."
+    };
+  }
+
+  if (lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token")) {
+    return {
+      category: "auth_error",
+      suggestion: "Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token."
+    };
+  }
+
+  if (lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid"))) {
+    return {
+      category: "config_error",
+      suggestion: "Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config."
+    };
+  }
+
+  if (lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider"))) {
+    return {
+      category: "agent_missing",
+      suggestion: "Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions."
+    };
+  }
+
+  if (lower.includes("timed out") || lower.includes("timeout")) {
+    return {
+      category: "timeout",
+      suggestion: "The operation timed out. Try increasing timeoutMs or maxIterationMinutes. If a scan timed out, check SonarQube health."
+    };
+  }
+
+  if (lower.includes("not a git repository")) {
+    return {
+      category: "git_error",
+      suggestion: "Current directory is not a git repository. Navigate to your project root or initialize git with 'git init'."
+    };
+  }
+
+  return { category: "unknown", suggestion: null };
+}
+
+export function enrichedFailPayload(error, toolName) {
+  const msg = error?.message || String(error);
+  const { category, suggestion } = classifyError(error);
+  const payload = {
+    ok: false,
+    error: msg,
+    tool: toolName,
+    category
+  };
+  if (suggestion) payload.suggestion = suggestion;
+  return payload;
+}
+
+export async function buildConfig(options) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, options || {});
+  validateConfig(merged, "run");
+  return merged;
+}
+
+export function buildAskQuestion(server) {
+  return async (question) => {
+    try {
+      const result = await server.elicitInput({
+        message: question,
+        requestedSchema: {
+          type: "object",
+          properties: {
+            answer: { type: "string", description: "Your response" }
+          },
+          required: ["answer"]
+        }
+      });
+      return result.action === "accept" ? result.content?.answer || null : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+export async function handleRunDirect(a, server, extra) {
+  const config = await buildConfig(a);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const requiredProviders = [
+    resolveRole(config, "coder").provider,
+    config.reviewer_options?.fallback_reviewer
+  ];
+  if (config.pipeline?.reviewer?.enabled !== false) {
+    requiredProviders.push(resolveRole(config, "reviewer").provider);
+  }
+  if (config.pipeline?.triage?.enabled) requiredProviders.push(resolveRole(config, "triage").provider);
+  if (config.pipeline?.planner?.enabled) requiredProviders.push(resolveRole(config, "planner").provider);
+  if (config.pipeline?.refactorer?.enabled) requiredProviders.push(resolveRole(config, "refactorer").provider);
+  if (config.pipeline?.researcher?.enabled) requiredProviders.push(resolveRole(config, "researcher").provider);
+  if (config.pipeline?.tester?.enabled) requiredProviders.push(resolveRole(config, "tester").provider);
+  if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
+  await assertAgentsAvailable(requiredProviders);
+
+  const emitter = new EventEmitter();
+  emitter.on("progress", buildProgressHandler(server));
+  const progressNotifier = buildProgressNotifier(extra);
+  if (progressNotifier) emitter.on("progress", progressNotifier);
+
+  const askQuestion = buildAskQuestion(server);
+  const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion });
+  return { ok: !result.paused && (result.approved !== false), ...result };
+}
+
+export async function handleResumeDirect(a, server, extra) {
+  const config = await buildConfig(a);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const emitter = new EventEmitter();
+  emitter.on("progress", buildProgressHandler(server));
+  const progressNotifier = buildProgressNotifier(extra);
+  if (progressNotifier) emitter.on("progress", progressNotifier);
+
+  const askQuestion = buildAskQuestion(server);
+  const result = await resumeFlow({
+    sessionId: a.sessionId,
+    answer: a.answer || null,
+    config,
+    logger,
+    flags: a,
+    emitter,
+    askQuestion
+  });
+  return { ok: true, ...result };
+}
+
+export async function handleToolCall(name, args, server, extra) {
+  const a = asObject(args);
+
+  if (name === "kj_init") {
+    return runKjCommand({ command: "init", options: a });
+  }
+
+  if (name === "kj_doctor") {
+    return runKjCommand({ command: "doctor", options: a });
+  }
+
+  if (name === "kj_config") {
+    return runKjCommand({
+      command: "config",
+      commandArgs: a.json ? ["--json"] : [],
+      options: a
+    });
+  }
+
+  if (name === "kj_scan") {
+    return runKjCommand({ command: "scan", options: a });
+  }
+
+  if (name === "kj_roles") {
+    const action = a.action || "list";
+    const commandArgs = [action];
+    if (action === "show" && a.roleName) commandArgs.push(a.roleName);
+    return runKjCommand({
+      command: "roles",
+      commandArgs,
+      options: a
+    });
+  }
+
+  if (name === "kj_report") {
+    const commandArgs = [];
+    if (a.list) commandArgs.push("--list");
+    if (a.sessionId) commandArgs.push("--session-id", String(a.sessionId));
+    if (a.format) commandArgs.push("--format", String(a.format));
+    if (a.trace) commandArgs.push("--trace");
+    if (a.currency) commandArgs.push("--currency", String(a.currency));
+    return runKjCommand({
+      command: "report",
+      commandArgs,
+      options: a
+    });
+  }
+
+  if (name === "kj_resume") {
+    if (!a.sessionId) {
+      return failPayload("Missing required field: sessionId");
+    }
+    return handleResumeDirect(a, server, extra);
+  }
+
+  if (name === "kj_run") {
+    if (!a.task) {
+      return failPayload("Missing required field: task");
+    }
+    return handleRunDirect(a, server, extra);
+  }
+
+  if (name === "kj_code") {
+    if (!a.task) {
+      return failPayload("Missing required field: task");
+    }
+    return runKjCommand({ command: "code", commandArgs: [a.task], options: a });
+  }
+
+  if (name === "kj_review") {
+    if (!a.task) {
+      return failPayload("Missing required field: task");
+    }
+    return runKjCommand({ command: "review", commandArgs: [a.task], options: a });
+  }
+
+  if (name === "kj_plan") {
+    if (!a.task) {
+      return failPayload("Missing required field: task");
+    }
+    const options = normalizePlanArgs(a);
+    return runKjCommand({ command: "plan", commandArgs: [a.task], options });
+  }
+
+  return failPayload(`Unknown tool: ${name}`);
+}

package/src/mcp/server.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { tools } from "./tools.js";
+import { handleToolCall, responseText, enrichedFailPayload } from "./server-handlers.js";
+
+const server = new Server(
+  {
+    name: "karajan-mcp",
+    version: "1.0.0"
+  },
+  {
+    capabilities: {
+      tools: {},
+      logging: {},
+      elicitation: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const name = request.params?.name;
+  const args = request.params?.arguments || {};
+
+  try {
+    const result = await handleToolCall(name, args, server, extra);
+    return responseText(result);
+  } catch (error) {
+    return responseText(enrichedFailPayload(error, name));
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/mcp/tool-arg-normalizers.js

@@ -0,0 +1,16 @@
+export function normalizePlanArgs(args = {}) {
+  const normalized = { ...args };
+
+  if (!normalized.planner && normalized.coder) {
+    normalized.planner = normalized.coder;
+  }
+
+  if (!normalized.plannerModel && normalized.coderModel) {
+    normalized.plannerModel = normalized.coderModel;
+  }
+
+  delete normalized.coder;
+  delete normalized.coderModel;
+
+  return normalized;
+}

package/src/mcp/tools.js

@@ -0,0 +1,184 @@
+export const tools = [
+  {
+    name: "kj_init",
+    description: "Initialize karajan-code config, review rules, and SonarQube",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string", description: "Optional KJ_HOME directory" },
+        timeoutMs: { type: "number", description: "Optional command timeout in ms" }
+      }
+    }
+  },
+  {
+    name: "kj_doctor",
+    description: "Check system dependencies and agent CLIs",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_config",
+    description: "Show kj configuration",
+    inputSchema: {
+      type: "object",
+      properties: {
+        json: { type: "boolean" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_scan",
+    description: "Run SonarQube scan for current project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kjHome: { type: "string" },
+        sonarToken: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_run",
+    description:
+      "Run full coder -> sonar -> reviewer loop. Sends real-time progress notifications via MCP logging. May return paused state with a question if fail-fast is triggered.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
+        pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },
+        planner: { type: "string" },
+        coder: { type: "string" },
+        reviewer: { type: "string" },
+        refactorer: { type: "string" },
+        plannerModel: { type: "string" },
+        coderModel: { type: "string" },
+        reviewerModel: { type: "string" },
+        refactorerModel: { type: "string" },
+        enablePlanner: { type: "boolean" },
+        enableReviewer: { type: "boolean" },
+        enableRefactorer: { type: "boolean" },
+        enableResearcher: { type: "boolean" },
+        enableTester: { type: "boolean" },
+        enableSecurity: { type: "boolean" },
+        enableTriage: { type: "boolean" },
+        enableSerena: { type: "boolean" },
+        reviewerFallback: { type: "string" },
+        reviewerRetries: { type: "number" },
+        mode: { type: "string" },
+        maxIterations: { type: "number" },
+        maxIterationMinutes: { type: "number" },
+        maxTotalMinutes: { type: "number" },
+        baseBranch: { type: "string" },
+        baseRef: { type: "string" },
+        methodology: { type: "string", enum: ["tdd", "standard"] },
+        autoCommit: { type: "boolean" },
+        autoPush: { type: "boolean" },
+        autoPr: { type: "boolean" },
+        autoRebase: { type: "boolean" },
+        branchPrefix: { type: "string" },
+        noSonar: { type: "boolean" },
+        kjHome: { type: "string" },
+        sonarToken: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_resume",
+    description:
+      "Resume a paused session by ID. Provide an answer to the question that caused the pause. Sends real-time progress notifications via MCP logging.",
+    inputSchema: {
+      type: "object",
+      required: ["sessionId"],
+      properties: {
+        sessionId: { type: "string", description: "Session ID to resume" },
+        answer: { type: "string", description: "Answer to the question that caused the pause" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_report",
+    description: "Read latest or list session reports. Use trace=true for chronological stage-by-stage breakdown with timing and token usage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        list: { type: "boolean" },
+        sessionId: { type: "string" },
+        format: { type: "string", enum: ["text", "json"] },
+        trace: { type: "boolean", description: "Show chronological trace of all pipeline stages" },
+        currency: { type: "string", enum: ["usd", "eur"], description: "Display costs in this currency" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_roles",
+    description: "List pipeline roles or show the template instructions for a specific role. Use action='list' to see all roles with their provider and status. Use action='show' with roleName to read the .md template.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "show"], description: "Action: list all roles or show a specific role template" },
+        roleName: { type: "string", description: "Role name to show (e.g. coder, reviewer, triage, reviewer-paranoid)" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_code",
+    description: "Run coder-only mode",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string" },
+        coder: { type: "string" },
+        coderModel: { type: "string" },
+        kjHome: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_review",
+    description: "Run reviewer-only mode against current diff",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string" },
+        reviewer: { type: "string" },
+        reviewerModel: { type: "string" },
+        baseRef: { type: "string" },
+        kjHome: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "kj_plan",
+    description: "Generate implementation plan for a task",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string" },
+        planner: { type: "string" },
+        plannerModel: { type: "string" },
+        coder: { type: "string", description: "Legacy alias for planner" },
+        coderModel: { type: "string", description: "Legacy alias for plannerModel" },
+        kjHome: { type: "string" },
+        timeoutMs: { type: "number" }
+      }
+    }
+  }
+];