@omnicoreos/planka-mcp 0.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,138 @@
+# Troubleshooting
+
+Match the symptom first. Each entry gives the observed behavior, the real cause, and
+the fix.
+
+## “The agent says the card has no comments, but I can see comments”
+
+**Cause:** the old MCP reads `included.comments` from the card response. Planka 2.x
+does not populate it, so HTTP succeeds with zero items.
+
+**Fix:** make sure Claude Code runs this fork, restart Claude Code, and call
+`planka_get_comments` again. Run the opt-in smoke test if the result is still
+suspicious; it compares MCP output to `GET /api/cards/:id/comments`.
+
+## “It says the label was added, but the card has no label”
+
+**Cause:** the old tool schema knows `addLabelIds` but silently drops `labelIds`.
+
+**Fix:** use this fork. It accepts both names and re-reads the card. Treat any result
+with a non-empty `failed` array as an error.
+
+## “Removing a label returns 404, or the label remains”
+
+**Cause:** Planka 2.x deletes by `labelId:<labelId>` criteria, not by the ID of the
+card-label junction record.
+
+**Fix:** upgrade to this fork and pass the board label ID in `removeLabelIds`:
+
+```json
+{
+  "cardId": "<CARD_ID>",
+  "removeLabelIds": ["<LABEL_ID>"]
+}
+```
+
+## “`planka_get_board` fails because one color is invalid”
+
+**Cause:** the old response schema has a closed color enum. One newer Planka color
+causes Zod to reject the entire board.
+
+**Fix:** use this fork. Read paths accept backend color strings. Write paths still
+validate known colors.
+
+## “My credential is expired,” but the password works in the browser
+
+**Cause:** `http://` redirects to `https://`. The authentication POST body can be
+lost in the redirect, and the final response is HTML instead of the expected JSON
+token.
+
+**Fix:** set `PLANKA_BASE_URL` to the final HTTPS origin:
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+```
+
+Run `./scripts/setup.sh` again. It validates `POST /api/access-tokens` before writing
+anything and calls out redirect/HTML responses directly.
+
+## “Board not found” while creating a card, list, or label
+
+**Cause:** Planka can answer 404 when the agent user lacks write permission. Instance
+administrator access alone is not the same as board write access.
+
+**Fix:** give the agent user both:
+
+1. project manager access when it must create boards or manage project-level state;
+2. board membership with role `editor` for card, list, label, task, and comment
+   writes.
+
+The board-membership route in Planka 2.x is:
+
+```text
+POST /api/boards/<BOARD_ID>/board-memberships
+```
+
+with a body containing `userId` and `role: "editor"`.
+
+## “Creating a list returns `E_MISSING_OR_INVALID_PARAMS`”
+
+**Cause:** Planka 2.x requires `type` as well as `name` and `position`. Older MCP
+builds omit it.
+
+**Fix:** use this fork. `planka_manage_lists` sends `type: "active"` by default and
+also accepts `closed`.
+
+## “The MCP tools do not appear in Claude Code”
+
+**Cause:** MCP configuration is loaded at session startup. A project-scoped
+`.mcp.json` may also be waiting for workspace trust and explicit approval.
+
+**Fix:** close and restart Claude Code, approve the project when prompted, then run:
+
+```bash
+claude mcp list
+claude mcp get planka
+```
+
+Inside Claude Code, `/mcp` shows connection details. A project server waiting for
+approval appears as pending rather than connected.
+
+## “`claude mcp add` says the server already exists”
+
+**Cause:** a previous local or user-scoped entry has the same name.
+
+**Fix:** `setup.sh` removes and recreates the user-scoped `planka` entry
+idempotently. To do it manually:
+
+```bash
+claude mcp remove planka --scope user
+claude mcp add --scope user --transport stdio planka -- \
+  "$HOME/.local/bin/planka-mcp"
+```
+
+## “The smoke test says it was skipped”
+
+**Cause:** the real smoke test is opt-in and one of its four environment variables is
+missing.
+
+**Fix:** set all required values and choose a writable board:
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+export PLANKA_AGENT_EMAIL="agent@example.com"
+export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
+export PLANKA_SMOKE_BOARD_ID="<BOARD_ID>"
+npm run test:smoke
+```
+
+The test creates and deletes a temporary card. Do not point it at a board where the
+agent user must be read-only.
+
+## “Authentication returns HTTP 502 or another HTML error page”
+
+**Cause:** the reverse proxy or Planka service is unavailable. This is different from
+an invalid JSON token response even though both can look like HTML to a client.
+
+**Fix:** restore the Planka service, verify the final HTTPS URL in a browser, and
+rerun setup. The setup script does not write configuration after failed validation.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@omnicoreos/planka-mcp",
+  "version": "0.2.0",
+  "description": "A Planka 2.x MCP server with verified writes and an optional agent workflow",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "planka-mcp": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "scripts",
+    "tests/smoke",
+    "workflow",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "CREDITS.md",
+    "README.md",
+    "README.es.md",
+    "project.identity.json",
+    "server.json"
+  ],
+  "scripts": {
+    "sync:identity": "node scripts/sync-identity.mjs",
+    "check:identity": "node scripts/sync-identity.mjs --check",
+    "build": "npm run check:identity && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke": "npm run build && node tests/smoke/planka-smoke.mjs",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "planka",
+    "kanban",
+    "claude-code",
+    "ai-agent"
+  ],
+  "author": "planka-mcp contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omnicoreos/planka-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/omnicoreos/planka-mcp/issues"
+  },
+  "homepage": "https://github.com/omnicoreos/planka-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.130",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "mcpName": "io.github.omnicoreos/planka-mcp"
+}

package/project.identity.json

@@ -0,0 +1,7 @@
+{
+  "repositoryName": "planka-mcp",
+  "packageName": "@omnicoreos/planka-mcp",
+  "binName": "planka-mcp",
+  "mcpServerName": "io.github.omnicoreos/planka-mcp",
+  "repositoryUrl": "https://github.com/omnicoreos/planka-mcp"
+}

package/scripts/bootstrap-board.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import {
+  PlankaApi,
+  PlankaApiError,
+  boardEntities,
+} from "./lib/planka-api.mjs";
+import {
+  WORKFLOW_LABELS,
+  WORKFLOW_LISTS,
+  nextPosition,
+} from "./lib/workflow-template.mjs";
+
+function parseArgs(argv) {
+  const args = { force: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--force") args.force = true;
+    else if (arg === "--json") args.json = true;
+    else if (arg === "--board-id") args.boardId = argv[++index];
+    else if (arg === "--project-id") args.projectId = argv[++index];
+    else if (arg === "--board-name") args.boardName = argv[++index];
+    else if (arg === "--help" || arg === "-h") args.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return args;
+}
+
+function usage() {
+  return `Usage:
+  node scripts/bootstrap-board.mjs --board-id <id>
+  node scripts/bootstrap-board.mjs --project-id <id> --board-name "Agent Work"
+
+Environment:
+  PLANKA_BASE_URL, PLANKA_AGENT_EMAIL, PLANKA_AGENT_PASSWORD
+
+Options:
+  --force   Add the template even when the board already has unrelated content
+  --json    Print the result as JSON`;
+}
+
+export async function bootstrapBoard(
+  api,
+  { boardId, projectId, boardName = "Agent Work", force = false } = {}
+) {
+  let createdBoard = false;
+  if (!boardId) {
+    if (!projectId) {
+      throw new Error("Pass either boardId or projectId");
+    }
+    const created = await api.createBoard(projectId, boardName);
+    boardId = created?.item?.id;
+    if (!boardId) throw new Error("Planka did not return the new board id");
+    createdBoard = true;
+  }
+
+  let state = boardEntities(await api.getBoard(boardId));
+  const templateListNames = new Set(WORKFLOW_LISTS.map((item) => item.name));
+  const matchingLists = state.lists.filter((item) =>
+    templateListNames.has(item.name)
+  );
+  const unrelatedLists = state.lists.filter(
+    (item) => item.name && !templateListNames.has(item.name)
+  );
+
+  if (
+    !force &&
+    matchingLists.length === 0 &&
+    (unrelatedLists.length > 0 || state.cards.length > 0)
+  ) {
+    throw new Error(
+      "This board is not empty and does not look bootstrapped. Use --force only if you intentionally want to add the workflow alongside existing content."
+    );
+  }
+
+  const createdLists = [];
+  const existingListNames = new Set(state.lists.map((item) => item.name));
+  for (const [index, definition] of WORKFLOW_LISTS.entries()) {
+    if (existingListNames.has(definition.name)) continue;
+    const response = await api.createList(
+      boardId,
+      definition.name,
+      nextPosition(index),
+      definition.type
+    );
+    createdLists.push(response.item);
+  }
+
+  state = boardEntities(await api.getBoard(boardId));
+  const createdLabels = [];
+  const existingLabelNames = new Set(state.labels.map((item) => item.name));
+  for (const [index, definition] of WORKFLOW_LABELS.entries()) {
+    if (existingLabelNames.has(definition.name)) continue;
+    const response = await api.createLabel(
+      boardId,
+      definition.name,
+      definition.color,
+      nextPosition(index)
+    );
+    createdLabels.push(response.item);
+  }
+
+  const verified = boardEntities(await api.getBoard(boardId));
+  const missingLists = WORKFLOW_LISTS.filter(
+    (definition) =>
+      !verified.lists.some(
+        (item) =>
+          item.name === definition.name &&
+          (!item.type || item.type === definition.type)
+      )
+  );
+  const missingLabels = WORKFLOW_LABELS.filter(
+    (definition) =>
+      !verified.labels.some((item) => item.name === definition.name)
+  );
+  if (missingLists.length || missingLabels.length) {
+    throw new Error(
+      `Bootstrap verification failed. Missing lists: ${missingLists.map((item) => item.name).join(", ") || "none"}; missing labels: ${missingLabels.map((item) => item.name).join(", ") || "none"}`
+    );
+  }
+
+  return {
+    boardId,
+    boardName: verified.board?.name || boardName,
+    createdBoard,
+    createdLists: createdLists.map((item) => item.id),
+    createdLabels: createdLabels.map((item) => item.id),
+    listCount: WORKFLOW_LISTS.length,
+    labelCount: WORKFLOW_LABELS.length,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+
+  const api = await PlankaApi.fromCredentials({
+    baseUrl: process.env.PLANKA_BASE_URL,
+    email: process.env.PLANKA_AGENT_EMAIL,
+    password: process.env.PLANKA_AGENT_PASSWORD,
+  });
+  const result = await bootstrapBoard(api, args);
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`Workflow ready on board: ${result.boardName} (${result.boardId})`);
+    console.log(`Created ${result.createdLists.length} list(s) and ${result.createdLabels.length} label(s).`);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    const prefix = error instanceof PlankaApiError ? "Planka API error" : "Error";
+    console.error(`${prefix}: ${error.message}`);
+    process.exit(1);
+  });
+}

package/scripts/lib/planka-api.mjs

@@ -0,0 +1,244 @@
+export class PlankaApiError extends Error {
+  constructor(message, { status = 0, body = null } = {}) {
+    super(message);
+    this.name = "PlankaApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new PlankaApiError(`Invalid Planka URL: ${value}`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new PlankaApiError("PLANKA_BASE_URL must use http:// or https://");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+async function parseResponse(response, context) {
+  const text = await response.text();
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      const looksLikeHtml = /<\s*(?:!doctype|html|head|body)\b/i.test(text);
+      const hint = looksLikeHtml
+        ? " The server returned HTML instead of JSON. If the URL starts with http://, configure the final https:// URL directly; redirects can drop an authentication POST body."
+        : " The response was not valid JSON.";
+      throw new PlankaApiError(`${context} failed.${hint}`, {
+        status: response.status,
+      });
+    }
+  }
+
+  if (!response.ok) {
+    const detail =
+      body && typeof body === "object"
+        ? body.message || body.code || JSON.stringify(body)
+        : response.statusText;
+    throw new PlankaApiError(
+      `${context} failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}`,
+      { status: response.status, body }
+    );
+  }
+  return body;
+}
+
+export async function login({ baseUrl, email, password, fetchImpl = fetch }) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  let response;
+  try {
+    response = await fetchImpl(`${normalized}/api/access-tokens`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ emailOrUsername: email, password }),
+      redirect: "manual",
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (error) {
+    if (error instanceof PlankaApiError) throw error;
+    throw new PlankaApiError(
+      `Could not connect to Planka at ${normalized}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  if (response.status >= 300 && response.status < 400) {
+    const destination = response.headers.get("location");
+    throw new PlankaApiError(
+      `Authentication was redirected${destination ? ` to ${destination}` : ""}. Use the final https:// Planka URL directly; a 301/302 can drop the POST body.` ,
+      { status: response.status }
+    );
+  }
+
+  const body = await parseResponse(response, "Authentication");
+  if (!body || typeof body.item !== "string") {
+    throw new PlankaApiError(
+      "Authentication returned JSON, but not a Planka access token. Check the base URL and credentials."
+    );
+  }
+  return { baseUrl: normalized, token: body.item };
+}
+
+export class PlankaApi {
+  constructor({ baseUrl, token, fetchImpl = fetch }) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.token = token;
+    this.fetchImpl = fetchImpl;
+  }
+
+  static async fromCredentials(credentials) {
+    const session = await login(credentials);
+    return new PlankaApi({
+      ...session,
+      fetchImpl: credentials.fetchImpl,
+    });
+  }
+
+  async request(method, path, body) {
+    const headers = { Authorization: `Bearer ${this.token}` };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "manual",
+        signal: AbortSignal.timeout(30000),
+      });
+    } catch (error) {
+      throw new PlankaApiError(
+        `${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    if (response.status >= 300 && response.status < 400) {
+      throw new PlankaApiError(
+        `${method} ${path} was redirected. Configure the final https:// URL directly.`,
+        { status: response.status }
+      );
+    }
+    if (response.status === 204) return null;
+    return parseResponse(response, `${method} ${path}`);
+  }
+
+  get(path) {
+    return this.request("GET", path);
+  }
+
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+
+  getProjects() {
+    return this.get("/api/projects");
+  }
+
+  getBoard(boardId) {
+    return this.get(`/api/boards/${boardId}`);
+  }
+
+  createBoard(projectId, name, position = 65536) {
+    return this.post(`/api/projects/${projectId}/boards`, { name, position });
+  }
+
+  createList(boardId, name, position, type = "active") {
+    return this.post(`/api/boards/${boardId}/lists`, {
+      name,
+      position,
+      type,
+    });
+  }
+
+  createLabel(boardId, name, color, position) {
+    return this.post(`/api/boards/${boardId}/labels`, {
+      name,
+      color,
+      position,
+    });
+  }
+
+  deleteLabel(labelId) {
+    return this.delete(`/api/labels/${labelId}`);
+  }
+
+  createCard(listId, name, description = "") {
+    return this.post(`/api/lists/${listId}/cards`, {
+      name,
+      description,
+      position: 65536,
+      type: "project",
+    });
+  }
+
+  deleteCard(cardId) {
+    return this.delete(`/api/cards/${cardId}`);
+  }
+
+  getComments(cardId) {
+    return this.get(`/api/cards/${cardId}/comments`);
+  }
+
+  getCard(cardId) {
+    return this.get(`/api/cards/${cardId}`);
+  }
+
+  deleteList(listId) {
+    return this.delete(`/api/lists/${listId}`);
+  }
+
+  deleteAttachment(attachmentId) {
+    return this.delete(`/api/attachments/${attachmentId}`);
+  }
+
+  /**
+   * Authenticated binary download. Planka 2.0 serves attachment contents with
+   * the token as a Bearer header or as an `accessToken` cookie depending on
+   * the deployment, so send both. Accepts an absolute URL or a relative path.
+   */
+  async getBinary(urlOrPath) {
+    const url = urlOrPath.startsWith("http")
+      ? urlOrPath
+      : `${this.baseUrl}${urlOrPath}`;
+    const response = await this.fetchImpl(url, {
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Cookie: `accessToken=${this.token}`,
+      },
+      redirect: "manual",
+      signal: AbortSignal.timeout(30000),
+    });
+    if (!response.ok) {
+      throw new PlankaApiError(`GET ${url} failed: HTTP ${response.status}`, {
+        status: response.status,
+      });
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+}
+
+export function boardEntities(payload) {
+  const included = payload?.included || {};
+  return {
+    board: payload?.item,
+    lists: Array.isArray(included.lists) ? included.lists : [],
+    cards: Array.isArray(included.cards) ? included.cards : [],
+    labels: Array.isArray(included.labels) ? included.labels : [],
+    cardLabels: Array.isArray(included.cardLabels) ? included.cardLabels : [],
+  };
+}

package/scripts/lib/workflow-template.mjs

@@ -0,0 +1,26 @@
+export const WORKFLOW_LISTS = [
+  { name: "Pending", type: "active" },
+  { name: "Needs your decision", type: "active" },
+  { name: "In worktree", type: "active" },
+  { name: "Test it", type: "active" },
+  { name: "Review in main", type: "active" },
+  { name: "Merged", type: "closed" },
+];
+
+export const WORKFLOW_LABELS = [
+  { name: "needs-decision", color: "apricot-red" },
+  { name: "decided", color: "modern-green" },
+  { name: "tested-ok", color: "french-coast" },
+  { name: "fast-track", color: "sunny-grass" },
+  { name: "standard", color: "morning-sky" },
+  { name: "serial", color: "red-burgundy" },
+  { name: "zone:frontend", color: "pink-tulip" },
+  { name: "zone:backend", color: "lagoon-blue" },
+  { name: "zone:data", color: "egg-yellow" },
+  { name: "zone:infra", color: "dark-granite" },
+  { name: "zone:shared-ui", color: "sweet-lilac" },
+];
+
+export function nextPosition(index) {
+  return (index + 1) * 65536;
+}