feat: Kanban MCP — persistent boards with multi-session, semantic search, and web UI

packages/kanban/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@arvoretech/kanban-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for kanban boards — persistent task management with semantic search for AI-assisted development",
+  "main": "dist/index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kanban-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@modelcontextprotocol/sdk": "~1.22.0",
+    "@xenova/transformers": "^2.17.2",
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.0",
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.6.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kanban",
+    "task-management",
+    "arvore"
+  ],
+  "author": "Arvore",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

packages/kanban/src/embeddings.ts

@@ -0,0 +1,40 @@
+type Pipeline = (texts: string[], options?: Record<string, unknown>) => Promise<{ tolist: () => number[][] }>;
+
+const DEFAULT_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+
+export class EmbeddingEngine {
+  private pipeline: Pipeline | null = null;
+  private modelName: string;
+  private ready = false;
+
+  constructor(modelName?: string) {
+    this.modelName = modelName || process.env.KANBAN_EMBEDDING_MODEL || DEFAULT_MODEL;
+  }
+
+  async init(): Promise<void> {
+    try {
+      const { pipeline } = await import("@xenova/transformers");
+      this.pipeline = (await pipeline(
+        "feature-extraction",
+        this.modelName
+      )) as unknown as Pipeline;
+      this.ready = true;
+      console.error(`Embedding engine ready (model: ${this.modelName})`);
+    } catch (error) {
+      console.error(
+        `Failed to init embedding engine: ${error instanceof Error ? error.message : error}. Falling back to keyword search.`
+      );
+      this.ready = false;
+    }
+  }
+
+  isReady(): boolean {
+    return this.ready;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    if (!this.pipeline) throw new Error("Embedding engine not initialized");
+    const output = await this.pipeline([text], { pooling: "mean", normalize: true });
+    return output.tolist()[0];
+  }
+}

packages/kanban/src/http.ts

@@ -0,0 +1,131 @@
+import express from "express";
+import cors from "cors";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { KanbanStore } from "./store.js";
+
+export function startHttpServer(store: KanbanStore, port: number): void {
+  const app = express();
+  app.use(cors());
+  app.use(express.json());
+
+  app.get("/api/boards", async (_req, res) => {
+    try {
+      const result = await store.listBoards();
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards", async (req, res) => {
+    try {
+      const result = await store.createBoard(req.body);
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.get("/api/boards/:id", async (req, res) => {
+    try {
+      const includeArchived = req.query.include_archived === "true";
+      const result = await store.getBoard(req.params.id, includeArchived);
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.get("/api/boards/:boardId/cards/:cardId", async (req, res) => {
+    try {
+      const result = await store.getCard(req.params.boardId, req.params.cardId);
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards/:boardId/cards", async (req, res) => {
+    try {
+      const result = await store.createCard({ board_id: req.params.boardId, ...req.body });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.patch("/api/boards/:boardId/cards/:cardId", async (req, res) => {
+    try {
+      const result = await store.updateCard({ board_id: req.params.boardId, card_id: req.params.cardId, ...req.body });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards/:boardId/cards/:cardId/move", async (req, res) => {
+    try {
+      const result = await store.moveCard({ board_id: req.params.boardId, card_id: req.params.cardId, ...req.body });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards/:boardId/cards/:cardId/claim", async (req, res) => {
+    try {
+      const result = await store.claimCard({ board_id: req.params.boardId, card_id: req.params.cardId, ...req.body });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards/:boardId/cards/:cardId/release", async (req, res) => {
+    try {
+      const result = await store.releaseCard({ board_id: req.params.boardId, card_id: req.params.cardId, ...req.body });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/boards/:boardId/cards/:cardId/archive", async (req, res) => {
+    try {
+      const result = await store.archiveCard({ board_id: req.params.boardId, card_id: req.params.cardId });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.delete("/api/boards/:boardId/cards/:cardId", async (req, res) => {
+    try {
+      const result = await store.deleteCard({ board_id: req.params.boardId, card_id: req.params.cardId });
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  app.post("/api/search", async (req, res) => {
+    try {
+      const result = await store.searchCards(req.body);
+      res.json(result);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "Unknown error" });
+    }
+  });
+
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const uiPath = join(__dirname, "..", "ui", "dist");
+  app.use(express.static(uiPath));
+  app.get("*", (_req, res) => {
+    res.sendFile(join(uiPath, "index.html"));
+  });
+
+  app.listen(port, () => {
+    console.error(`Kanban UI available at http://localhost:${port}`);
+  });
+}

packages/kanban/src/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { resolve } from "node:path";
+import { KanbanMCPServer } from "./server.js";
+
+const kanbanPath = resolve(
+  process.env.KANBAN_PATH || process.cwd(),
+  process.env.KANBAN_PATH ? "" : "kanban"
+);
+const embeddingModel = process.env.KANBAN_EMBEDDING_MODEL;
+const defaultReleaseStatus = process.env.KANBAN_DEFAULT_RELEASE_STATUS || "review";
+
+const enableUi = process.env.KANBAN_UI === "true";
+const uiPort = parseInt(process.env.KANBAN_PORT || "4799", 10);
+
+try {
+  const server = new KanbanMCPServer(kanbanPath, embeddingModel, defaultReleaseStatus);
+  server.setupGracefulShutdown();
+  await server.start();
+
+  if (enableUi) {
+    const { startHttpServer } = await import("./http.js");
+    startHttpServer(server.getStore(), uiPort);
+  }
+} catch (error) {
+  console.error("Failed to start Kanban MCP Server:", error);
+  process.exit(1);
+}
+
+export { KanbanMCPServer } from "./server.js";
+export { KanbanStore } from "./store.js";
+export { EmbeddingEngine } from "./embeddings.js";
+export { KanbanMCPTools } from "./tools.js";
+export * from "./types.js";