@gzmagyari/kanbanboard 1.0.0

package/kanban-mcp-server.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+/**
+ * Kanban MCP Server — exposes KanbanDashboard REST API as MCP tools.
+ *
+ * Protocol: JSON-RPC 2.0 over stdio (one JSON message per line).
+ * No external dependencies — uses only Node.js built-ins.
+ *
+ * Env vars:
+ *   KANBAN_BASE_URL  — base URL for the Kanban API (default: http://localhost:3000)
+ */
+
+import { createInterface } from 'node:readline';
+import http from 'node:http';
+
+const BASE_URL = process.env.KANBAN_BASE_URL || 'http://localhost:3000';
+
+// ─── HTTP helper ────────────────────────────────────────────────────────────
+
+function apiRequest(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, BASE_URL);
+    const payload = body ? JSON.stringify(body) : null;
+    const opts = {
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method,
+      headers: { 'Accept': 'application/json' }
+    };
+    if (payload) {
+      opts.headers['Content-Type'] = 'application/json';
+      opts.headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+    const req = http.request(opts, (res) => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString();
+        let json;
+        try { json = JSON.parse(text); } catch { json = { raw: text }; }
+        if (res.statusCode >= 400) {
+          const err = new Error(json.error || `HTTP ${res.statusCode}`);
+          err.statusCode = res.statusCode;
+          err.body = json;
+          return reject(err);
+        }
+        resolve(json);
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+// ─── Tool definitions ───────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'get_task',
+    description: 'Get task details by ID, including comments and progress updates',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID' }
+      },
+      required: ['task_id']
+    }
+  },
+  {
+    name: 'list_tasks',
+    description: 'List tasks, optionally filtered by project, status, or parent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Filter by project ID' },
+        status: { type: 'string', description: 'Filter by status (ideas, todo, in_progress, review, testing, done)' },
+        parent_id: { type: 'string', description: 'Filter by parent task ID. Use "null" for root tasks.' }
+      }
+    }
+  },
+  {
+    name: 'update_task_status',
+    description: 'Move a task to a new status',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID' },
+        status: { type: 'string', description: 'New status (ideas, todo, in_progress, review, testing, done)' }
+      },
+      required: ['task_id', 'status']
+    }
+  },
+  {
+    name: 'update_task_fields',
+    description: 'Update task fields (title, description, detail_text, assigned_agent_id)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID' },
+        title: { type: 'string', description: 'New title' },
+        description: { type: 'string', description: 'New description' },
+        detail_text: { type: 'string', description: 'New detail text' },
+        assigned_agent_id: { type: ['string', 'null'], description: 'Agent ID to assign, or null to unassign' }
+      },
+      required: ['task_id']
+    }
+  },
+  {
+    name: 'create_task',
+    description: 'Create a new task in a project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Project ID' },
+        title: { type: 'string', description: 'Task title' },
+        description: { type: 'string', description: 'Task description' },
+        status: { type: 'string', description: 'Initial status (default: todo)' },
+        parent_id: { type: 'string', description: 'Parent task ID (optional)' },
+        milestone_id: { type: 'string', description: 'Milestone ID (optional)' }
+      },
+      required: ['project_id', 'title']
+    }
+  },
+  {
+    name: 'add_comment',
+    description: 'Add a comment to a task',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID' },
+        text: { type: 'string', description: 'Comment text' },
+        author: { type: 'string', description: 'Author name (default: Agent)' }
+      },
+      required: ['task_id', 'text']
+    }
+  },
+  {
+    name: 'delete_comment',
+    description: 'Delete a comment by its ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        comment_id: { type: 'number', description: 'The comment ID to delete' }
+      },
+      required: ['comment_id']
+    }
+  },
+  {
+    name: 'add_progress_update',
+    description: 'Add a progress update to a task',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID' },
+        text: { type: 'string', description: 'Progress update text' },
+        author: { type: 'string', description: 'Author name (default: Agent)' }
+      },
+      required: ['task_id', 'text']
+    }
+  },
+  {
+    name: 'get_project',
+    description: 'Get project details',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'The project ID' }
+      },
+      required: ['project_id']
+    }
+  },
+  {
+    name: 'list_agents',
+    description: 'List agents for a project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'The project ID' }
+      },
+      required: ['project_id']
+    }
+  },
+  {
+    name: 'get_agent_by_role',
+    description: 'Find an agent by role within a project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'The project ID' },
+        role: { type: 'string', description: 'Agent role (e.g. qa_engineer, developer)' }
+      },
+      required: ['project_id', 'role']
+    }
+  },
+  {
+    name: 'run_agent_on_ticket',
+    description: 'Trigger an agent run against a specific ticket. Returns job_id for polling.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent_id: { type: 'string', description: 'Agent ID' },
+        task_id: { type: 'string', description: 'Task/ticket ID' },
+        fresh_chrome: { type: 'boolean', description: 'Restart Chrome before running (default: false)' },
+        new_session: { type: 'boolean', description: 'Start fresh Claude session (default: false)' }
+      },
+      required: ['agent_id', 'task_id']
+    }
+  }
+];
+
+// ─── Tool handlers ──────────────────────────────────────────────────────────
+
+async function handleToolCall(name, args) {
+  switch (name) {
+    case 'get_task': {
+      const data = await apiRequest('GET', `/api/tasks/${args.task_id}`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'list_tasks': {
+      const params = new URLSearchParams();
+      if (args.project_id) params.set('project_id', args.project_id);
+      if (args.status) params.set('status', args.status);
+      if (args.parent_id !== undefined) params.set('parent_id', args.parent_id);
+      const data = await apiRequest('GET', `/api/tasks?${params}`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'update_task_status': {
+      const data = await apiRequest('PATCH', `/api/tasks/${args.task_id}`, { status: args.status });
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'update_task_fields': {
+      const body = {};
+      if (args.title !== undefined) body.title = args.title;
+      if (args.description !== undefined) body.description = args.description;
+      if (args.detail_text !== undefined) body.detail_text = args.detail_text;
+      if (args.assigned_agent_id !== undefined) body.assigned_agent_id = args.assigned_agent_id;
+      const data = await apiRequest('PATCH', `/api/tasks/${args.task_id}`, body);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'create_task': {
+      const body = {
+        title: args.title,
+        project_id: args.project_id,
+        status: args.status || 'todo'
+      };
+      if (args.description) body.description = args.description;
+      if (args.parent_id) body.parent_id = args.parent_id;
+      if (args.milestone_id) body.milestone_id = args.milestone_id;
+      const data = await apiRequest('POST', '/api/tasks', body);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'add_comment': {
+      const body = { text: args.text };
+      if (args.author) body.author = args.author;
+      const data = await apiRequest('POST', `/api/tasks/${args.task_id}/comments`, body);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'delete_comment': {
+      const data = await apiRequest('DELETE', `/api/comments/${args.comment_id}`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'add_progress_update': {
+      const body = { text: args.text };
+      if (args.author) body.author = args.author;
+      const data = await apiRequest('POST', `/api/tasks/${args.task_id}/updates`, body);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'get_project': {
+      const data = await apiRequest('GET', `/api/projects/${args.project_id}`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'list_agents': {
+      const data = await apiRequest('GET', `/api/projects/${args.project_id}/agents`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'get_agent_by_role': {
+      const data = await apiRequest('GET', `/api/projects/${args.project_id}/agents/by-role/${args.role}`);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'run_agent_on_ticket': {
+      const body = { task_id: args.task_id };
+      if (args.fresh_chrome) body.fresh_chrome = true;
+      if (args.new_session) body.new_session = true;
+      const data = await apiRequest('POST', `/api/agents/${args.agent_id}/run-on-ticket`, body);
+      return JSON.stringify(data, null, 2);
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// ─── JSON-RPC / MCP protocol ───────────────────────────────────────────────
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function makeResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function makeError(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case 'initialize':
+      send(makeResult(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'kanban', version: '1.0.0' }
+      }));
+      break;
+
+    case 'notifications/initialized':
+      // No response needed for notifications
+      break;
+
+    case 'tools/list':
+      send(makeResult(id, { tools: TOOLS }));
+      break;
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const args = params?.arguments || {};
+      try {
+        const text = await handleToolCall(toolName, args);
+        send(makeResult(id, {
+          content: [{ type: 'text', text }]
+        }));
+      } catch (e) {
+        send(makeResult(id, {
+          content: [{ type: 'text', text: `Error: ${e.message}` }],
+          isError: true
+        }));
+      }
+      break;
+    }
+
+    default:
+      if (id !== undefined) {
+        send(makeError(id, -32601, `Method not found: ${method}`));
+      }
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  try {
+    const msg = JSON.parse(line);
+    await handleMessage(msg);
+  } catch (e) {
+    // Parse error
+    send(makeError(null, -32700, `Parse error: ${e.message}`));
+  }
+});
+
+process.stderr.write(`[kanban-mcp] Server started, base URL: ${BASE_URL}\n`);

package/kanban.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * KanbanDashboard server manager CLI.
+ *
+ * Usage:
+ *   node kanban.mjs start   — Start the server in the background
+ *   node kanban.mjs stop    — Stop the running server
+ *   node kanban.mjs restart — Stop then start
+ *   node kanban.mjs status  — Show whether the server is running
+ *
+ * The server PID is stored in .kanban.pid so we can target exactly the
+ * right process without killing unrelated node processes.
+ */
+
+import { spawn, execSync } from 'child_process';
+import fs from 'fs';
+import { getPidFile, getLogFile, getServerScript, getHome } from './lib/paths.mjs';
+
+const PID_FILE = getPidFile();
+const LOG_FILE = getLogFile();
+const SERVER_SCRIPT = getServerScript();
+
+function readPid() {
+  try {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessRunning(pid) {
+  try {
+    // On Windows, tasklist filtered by PID. Exit code 0 = found.
+    const out = execSync(`tasklist /FI "PID eq ${pid}" /NH`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return out.includes(String(pid));
+  } catch {
+    return false;
+  }
+}
+
+function stopServer() {
+  const pid = readPid();
+  if (!pid) {
+    console.log('No PID file found — server is not running (or was not started with this tool).');
+    return false;
+  }
+  if (!isProcessRunning(pid)) {
+    console.log(`PID ${pid} is not running. Cleaning up stale PID file.`);
+    try { fs.unlinkSync(PID_FILE); } catch {}
+    return false;
+  }
+  try {
+    execSync(`taskkill /PID ${pid} /T /F`, { stdio: 'pipe' });
+    console.log(`Stopped server (PID ${pid}).`);
+  } catch (e) {
+    console.error(`Failed to stop PID ${pid}: ${e.message}`);
+    return false;
+  }
+  try { fs.unlinkSync(PID_FILE); } catch {}
+  return true;
+}
+
+function startServer() {
+  const existingPid = readPid();
+  if (existingPid && isProcessRunning(existingPid)) {
+    console.log(`Server is already running (PID ${existingPid}). Use 'restart' to bounce it.`);
+    return;
+  }
+
+  // Clean up stale PID file
+  if (existingPid) {
+    try { fs.unlinkSync(PID_FILE); } catch {}
+  }
+
+  const out = fs.openSync(LOG_FILE, 'a');
+  const err = fs.openSync(LOG_FILE, 'a');
+
+  const child = spawn('node', [SERVER_SCRIPT], {
+    cwd: getHome(),
+    detached: true,
+    stdio: ['ignore', out, err],
+    env: { ...process.env }
+  });
+
+  child.unref();
+  fs.writeFileSync(PID_FILE, String(child.pid), 'utf8');
+  console.log(`Server started (PID ${child.pid}). Logs: ${LOG_FILE}`);
+}
+
+function showStatus() {
+  const pid = readPid();
+  if (!pid) {
+    console.log('Server is NOT running (no PID file).');
+    return;
+  }
+  if (isProcessRunning(pid)) {
+    console.log(`Server is RUNNING (PID ${pid}).`);
+  } else {
+    console.log(`Server is NOT running (stale PID ${pid}). Cleaning up.`);
+    try { fs.unlinkSync(PID_FILE); } catch {}
+  }
+}
+
+// ── CLI ──
+const command = (process.argv[2] || '').toLowerCase();
+
+switch (command) {
+  case 'start':
+    startServer();
+    break;
+  case 'stop':
+    stopServer();
+    break;
+  case 'restart':
+    stopServer();
+    // Brief pause to let the port free up
+    await new Promise(r => setTimeout(r, 1000));
+    startServer();
+    break;
+  case 'status':
+    showStatus();
+    break;
+  default:
+    console.log(`Usage: node kanban.mjs <start|stop|restart|status>`);
+    process.exit(1);
+}

package/lib/paths.mjs

@@ -0,0 +1,136 @@
+/**
+ * Centralized path resolution for KanbanBoard.
+ *
+ * Two modes:
+ *   1. Development — CWD is the repo directory (detected automatically)
+ *   2. Installed   — uses ~/.kanbanboard/ for all runtime data
+ *
+ * Override with KANBANBOARD_HOME env var.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Package root is one level up from lib/
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Detect whether we are running from the source repo directory.
+ * Check: CWD has a package.json with our package name AND server.mjs exists.
+ */
+function isDevMode() {
+  try {
+    const cwdPkg = path.join(process.cwd(), 'package.json');
+    const raw = fs.readFileSync(cwdPkg, 'utf8');
+    const pkg = JSON.parse(raw);
+    if (pkg.name === '@gzmagyari/kanbanboard' || pkg.name === 'kanbanboard' || pkg.name === 'kanban-dashboard') {
+      return fs.existsSync(path.join(process.cwd(), 'server.mjs'));
+    }
+  } catch {
+    // No package.json or not parseable — not dev mode
+  }
+  return false;
+}
+
+/**
+ * Resolve the "home" directory where all runtime data lives.
+ *
+ * Priority:
+ *   1. KANBANBOARD_HOME env var (explicit override)
+ *   2. Dev mode (CWD is repo) → CWD
+ *   3. Installed mode → ~/.kanbanboard/
+ */
+function resolveHome() {
+  const envHome = process.env.KANBANBOARD_HOME;
+  if (envHome) return path.resolve(envHome);
+  if (isDevMode()) return process.cwd();
+  return path.join(os.homedir(), '.kanbanboard');
+}
+
+// Computed once at import time
+const _home = resolveHome();
+const _isDev = isDevMode();
+
+export function getHome()       { return _home; }
+export function isDevelopment()  { return _isDev; }
+export function getPackageRoot() { return PACKAGE_ROOT; }
+
+// ── Specific path accessors ──
+
+/** Directory containing kanban.db */
+export function getDataDir()      { return path.join(_home, 'data'); }
+
+/** Full path to kanban.db */
+export function getDbPath()       { return path.join(getDataDir(), 'kanban.db'); }
+
+/** Directory for Chrome pid, profile, etc. */
+export function getRuntimeDir()   { return path.join(_home, 'runtime'); }
+
+/** Path to .env file */
+export function getEnvPath()      { return path.join(_home, '.env'); }
+
+/** Path to .mcp.json */
+export function getMcpJsonPath()  { return path.join(_home, '.mcp.json'); }
+
+/** Path to PID file */
+export function getPidFile()      { return path.join(_home, '.kanban.pid'); }
+
+/** Path to log file */
+export function getLogFile()      { return path.join(_home, 'kanban.log'); }
+
+/** Path to agent queue log */
+export function getQueueLogPath() { return path.join(getDataDir(), 'agent-queue.log'); }
+
+/**
+ * The public/ directory containing index.html.
+ * Always from the PACKAGE root (ships with the package, not user data).
+ */
+export function getPublicDir()    { return path.join(PACKAGE_ROOT, 'public'); }
+
+/**
+ * The server.mjs script path (for process manager to spawn).
+ * Always from the package root.
+ */
+export function getServerScript() { return path.join(PACKAGE_ROOT, 'server.mjs'); }
+
+/**
+ * Load .env from the resolved home directory.
+ * Must be called BEFORE any module reads process.env for app config.
+ */
+export async function loadEnv() {
+  const envPath = getEnvPath();
+  if (fs.existsSync(envPath)) {
+    const dotenv = await import('dotenv');
+    dotenv.config({ path: envPath });
+  }
+}
+
+/**
+ * Ensure the home directory structure exists.
+ * Called by `kanbanboard init` and lazily by the server on startup.
+ */
+export function ensureDirectories() {
+  fs.mkdirSync(getDataDir(), { recursive: true });
+  fs.mkdirSync(getRuntimeDir(), { recursive: true });
+}
+
+/**
+ * Print a summary of resolved paths (for debugging / doctor).
+ */
+export function printPathSummary() {
+  console.log(`Mode:        ${_isDev ? 'development (repo)' : 'installed'}`);
+  console.log(`Home:        ${_home}`);
+  console.log(`Package:     ${PACKAGE_ROOT}`);
+  console.log(`Data dir:    ${getDataDir()}`);
+  console.log(`Database:    ${getDbPath()}`);
+  console.log(`Runtime dir: ${getRuntimeDir()}`);
+  console.log(`Env file:    ${getEnvPath()}`);
+  console.log(`Public dir:  ${getPublicDir()}`);
+  console.log(`PID file:    ${getPidFile()}`);
+  console.log(`Log file:    ${getLogFile()}`);
+}