@omnicoreos/planka-mcp 0.2.0 → 0.3.0

package/docs/troubleshooting.md

@@ -8,7 +8,7 @@ the fix.
 **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
+**Fix:** make sure Claude Code runs planka-mcp, 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`.
 
@@ -16,7 +16,7 @@ suspicious; it compares MCP output to `GET /api/cards/:id/comments`.
 
 **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
+**Fix:** use planka-mcp. 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”
@@ -24,7 +24,7 @@ with a non-empty `failed` array as an error.
 **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`:
+**Fix:** upgrade to planka-mcp and pass the board label ID in `removeLabelIds`:
 
 ```json
 {
@@ -38,7 +38,7 @@ card-label junction record.
 **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
+**Fix:** use planka-mcp. Read paths accept backend color strings. Write paths still
 validate known colors.
 
 ## “My credential is expired,” but the password works in the browser
@@ -80,7 +80,7 @@ with a body containing `userId` and `role: "editor"`.
 **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
+**Fix:** use planka-mcp. `planka_create_list` sends `type: "active"` by default and
 also accepts `closed`.
 
 ## “The MCP tools do not appear in Claude Code”
@@ -136,3 +136,135 @@ 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.
+
+## “Conflicting Planka credentials”
+
+`PLANKA_API_KEY` is set **and** so is `PLANKA_AGENT_EMAIL` / `PLANKA_AGENT_PASSWORD`.
+This is refused on purpose rather than guessed: Planka reads `Authorization`
+first and ignores `x-api-key` whenever both headers arrive, so a stale password
+would keep working and the key you thought was in use would be dead weight.
+
+Pick one. Keep `PLANKA_API_KEY` and delete the email/password pair from the
+client configuration — that is the whole point of moving to a key.
+
+## “Missing Planka credentials”
+
+The server has a `PLANKA_BASE_URL` but nothing to authenticate with. Set either
+`PLANKA_API_KEY` (see *Authentication* in the README) **or** both
+`PLANKA_AGENT_EMAIL` and `PLANKA_AGENT_PASSWORD`.
+
+If you meant to use a key: it can only be issued by a Planka **admin**, with
+`POST /api/users/<USER_ID>/api-key`, and the plaintext value appears exactly
+once in `included.apiKey` of that response. There is no way to read it back
+afterwards — Planka stores only the hash and the prefix. Issue a new one.
+
+## “boardId X is not in PLANKA_ALLOWED_BOARD_IDS”
+
+The board allowlist is doing its job. Either the agent picked the wrong id, or
+the board legitimately belongs in scope and the operator should add it to
+`PLANKA_ALLOWED_BOARD_IDS` (ids, comma-separated — names are not accepted, since
+any editor can rename a board).
+
+Remember the allowlist also filters `planka_get_structure`: if a board is missing
+from the structure, it is either outside the allowlist or outside the Planka
+user's board memberships. The second one is checked by Planka and answers 404.
+
+## “boardId is required … PLANKA_DEFAULT_BOARD_ID is not set”
+
+A tool was called without `boardId` and there is no default configured. Either
+pass the id, or set `PLANKA_DEFAULT_BOARD_ID` — with it, `boardId` disappears
+from every tool's `required` list and the default is used whenever the argument
+is omitted.
+
+## “Tool … is disabled / this server runs in read-only mode”
+
+`PLANKA_DISABLED_TOOLS` or `PLANKA_READ_ONLY=true` switched that tool off. The
+tool is also absent from `tools/list`, so an agent hitting this error is usually
+working from a cached tool list or from a skill that names the tool by hand:
+restarting the client resyncs the list.
+
+Do not retry the call — it will be refused identically. Either the operator
+re-enables the tool, or the change gets reported to a human instead of attempted.
+
+## “list … is protected by PLANKA_PROTECTED_LIST_IDS”
+
+A card was about to be created in, or moved into, a column the operator marked as
+protected — or the column itself was about to be edited or deleted. This is a
+client-side guard-rail, not a Planka permission (Planka has no per-list rights):
+it exists so an agent does not close its own work. A human can still do it in the
+Planka UI.
+
+## “No project with id … is visible to this account”
+
+`planka_get_structure` was given a `projectId` that this account cannot see. The
+error lists the projects that *are* visible. Two causes, in order of likelihood:
+the id belongs to a board rather than a project, or the Planka user has no board
+membership inside that project. `PLANKA_ALLOWED_PROJECT_IDS` produces a different
+message that names the variable.
+
+## “`planka_get_card` no longer returns the comments”
+
+Not a bug: comments are **off by default** since the card read became a digest.
+They were the biggest and least predictable part of the answer, and most reads do
+not need them.
+
+Ask for them: `withComments: 10` for the ten most recent, `withComments: "all"`
+to page through every one. The digest still tells you how many exist —
+`commentsTotal`, Planka's own counter — and the placeholder in the `comments`
+field says exactly this.
+
+Same story for the description: the digest carries `descriptionPreview` (200
+chars, with `descriptionChars` and `descriptionTruncated`). `detail: "full"`
+returns the whole record — description, task items, attachments, custom fields.
+
+## “The comment count does not match what I see in Planka”
+
+`planka_get_comments` returns **one page**. Planka serves comments 50 at a time
+and ignores `?limit`/`?page`, so `commentCount` is what that response carries,
+never the card's total.
+
+- the card's real total: `commentsTotal` from `planka_get_card`;
+- more comments to read: `hasMore: true` and a `nextBeforeId` to pass back as
+  `beforeId`;
+- everything at once: `all: true`, which reports `truncated: true` if the card
+  has more than 10 pages (500 comments).
+
+## “Forbidden: the agent user is probably not a member of this board”
+
+A 403 from Planka on a card, list, or label that reads fine in the browser. The
+agent user is a different user: either it is not a member of that board at all,
+or it is a **viewer** where an **editor** is needed.
+
+Fix it in Planka: open the board, add the agent user to the board members, and
+give it the editor role. Note that Planka answers **404** for this same cause
+often enough that a “not found” on an ID that worked a moment ago should be read
+as a permission problem first.
+
+## “Resource not found”, on an ID that exists
+
+The 404 now says which kind of ID the path expected (`labelId`, `listId`,
+`cardId`…). Three causes, in order:
+
+1. **the wrong kind of ID** — they are all strings of digits, so a `labelId`
+   passed as a `listId` looks perfectly valid until the request goes out. Get the
+   right one from `planka_board_summary` (labels and lists, with their IDs);
+2. **no permission** — see the entry above; Planka disguises 403 as 404;
+3. the entity really is gone.
+
+## “Returned HTML instead of JSON: this route does not exist in Planka 2.x”
+
+Every unknown `GET /api/...` falls through to the single-page app, which answers
+**200 with HTML**. The client detects it instead of parsing garbage.
+
+If it happened on a **write**, the message says so: the write may have landed.
+Re-read the entity before retrying, or you risk a duplicate. If it happened on a
+read, either the route genuinely does not exist in Planka 2.x (see
+`docs/planka-2x-gotchas.md`), or `PLANKA_BASE_URL` points at a proxy or an
+`http://` URL that redirects.
+
+## “Network error … could not reach Planka at `<url>`”
+
+The base URL is now part of the message, so the first check is whether that URL
+is the one you meant. Then: DNS, VPN/Tailscale, and whether the instance is up.
+A **POST** that fails this way may still have been received — re-read before
+retrying an upload.

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/preflight.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/preflight.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * SessionStart preflight for the Planka plugin.
+ *
+ * Cheap on purpose: it answers "is this server going to be able to start?"
+ * without touching the network and without spawning the server, so it never
+ * adds latency to a session. It checks the two things that actually break the
+ * install — a Node too old for the package, and missing/contradictory
+ * credentials — and stays silent when everything is in place.
+ *
+ * Set PLANKA_MCP_PREFLIGHT=full to also spawn the server binary and wait for
+ * its stdio banner (adds an npx download on a cold cache; opt-in only).
+ *
+ * It NEVER exits non-zero: a broken preflight must not block a session.
+ */
+import { spawn } from "node:child_process";
+
+const option = (key) => {
+  const raw =
+    process.env[`CLAUDE_PLUGIN_OPTION_${key.toUpperCase()}`] ??
+    process.env[key.toUpperCase()];
+  const value = typeof raw === "string" ? raw.trim() : "";
+  return value || undefined;
+};
+
+const notes = [];
+
+const major = Number(process.versions.node.split(".")[0]);
+if (Number.isFinite(major) && major < 18) {
+  notes.push(
+    `Node ${process.versions.node} is too old for @omnicoreos/planka-mcp (needs >= 18).`
+  );
+}
+
+const baseUrl = option("PLANKA_BASE_URL");
+const apiKey = option("PLANKA_API_KEY");
+const email = option("PLANKA_AGENT_EMAIL");
+const password = option("PLANKA_AGENT_PASSWORD");
+
+if (!baseUrl) {
+  notes.push(
+    "PLANKA_BASE_URL is not configured: run /plugin and set the plugin's Planka base URL, or export PLANKA_BASE_URL."
+  );
+} else if (baseUrl.startsWith("http://")) {
+  notes.push(
+    `PLANKA_BASE_URL is http:// (${baseUrl}). A redirect to https:// drops POST bodies — configure the final https:// URL.`
+  );
+}
+
+if (!apiKey && !(email && password)) {
+  notes.push(
+    "No Planka credentials: set the plugin's API key (recommended), or export PLANKA_AGENT_EMAIL + PLANKA_AGENT_PASSWORD."
+  );
+} else if (apiKey && (email || password)) {
+  notes.push(
+    "Both PLANKA_API_KEY and email/password are set. The server refuses that combination — keep the API key and unset the pair."
+  );
+}
+
+async function spawnCheck() {
+  return new Promise((resolve) => {
+    const child = spawn(
+      process.env.PLANKA_MCP_COMMAND || "npx",
+      process.env.PLANKA_MCP_COMMAND ? [] : ["-y", "@omnicoreos/planka-mcp"],
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve("timed out before printing its startup banner");
+    }, 20000);
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+      if (stderr.includes("PLANKA MCP server started")) {
+        clearTimeout(timer);
+        child.kill();
+        resolve(null);
+      }
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve(`could not be spawned: ${error.message}`);
+    });
+    child.on("exit", () => {
+      clearTimeout(timer);
+      resolve(stderr.includes("PLANKA MCP server started") ? null : "exited without starting");
+    });
+  });
+}
+
+if (process.env.PLANKA_MCP_PREFLIGHT === "full") {
+  const failure = await spawnCheck();
+  if (failure) notes.push(`The Planka MCP server ${failure}.`);
+}
+
+if (notes.length > 0) {
+  console.log(
+    `Planka MCP preflight found ${notes.length} problem(s):\n- ${notes.join("\n- ")}`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicoreos/planka-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A Planka 2.x MCP server with verified writes and an optional agent workflow",
   "type": "module",
   "main": "dist/index.js",
@@ -12,8 +12,13 @@
     "access": "public"
   },
   "files": [
+    ".agents",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".mcp.json",
     "dist",
     "docs",
+    "hooks",
     "scripts",
     "tests/smoke",
     "workflow",

package/scripts/setup.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+#
+# Thin alias for `planka-mcp init --client claude`, kept because the README has
+# been pointing at it since 0.1. Everything it used to do by hand now lives in
+# the published binary, so a clone and an npx install take the same path.
+#
+# The interactive board picker and the full write smoke still live in
+# scripts/setup.mjs: run `node scripts/setup.mjs` for those.
 
 set -euo pipefail
 
@@ -15,34 +22,9 @@ if [[ "$NODE_MAJOR" -lt 18 ]]; then
   exit 1
 fi
 
-echo "Planka MCP setup"
-echo
-
-DEFAULT_URL="${PLANKA_BASE_URL:-https://planka.example.com}"
-read -r -p "Planka base URL [$DEFAULT_URL]: " INPUT_URL
-export PLANKA_BASE_URL="${INPUT_URL:-$DEFAULT_URL}"
-
-DEFAULT_EMAIL="${PLANKA_AGENT_EMAIL:-}"
-if [[ -n "$DEFAULT_EMAIL" ]]; then
-  read -r -p "Agent email or username [$DEFAULT_EMAIL]: " INPUT_EMAIL
-  export PLANKA_AGENT_EMAIL="${INPUT_EMAIL:-$DEFAULT_EMAIL}"
-else
-  read -r -p "Agent email or username: " PLANKA_AGENT_EMAIL
-  export PLANKA_AGENT_EMAIL
-fi
-
-if [[ -z "${PLANKA_AGENT_PASSWORD:-}" ]]; then
-  read -r -s -p "Agent password: " PLANKA_AGENT_PASSWORD
-  echo
-  export PLANKA_AGENT_PASSWORD
-else
-  echo "Using PLANKA_AGENT_PASSWORD from the environment."
-fi
-
 if [[ ! -f "$ROOT_DIR/dist/index.js" ]]; then
-  echo
   echo "Building the MCP server..."
   (cd "$ROOT_DIR" && npm ci && npm run build)
 fi
 
-exec node "$ROOT_DIR/scripts/setup.mjs"
+exec node "$ROOT_DIR/dist/index.js" init --client claude "$@"

package/scripts/sync-identity.mjs

@@ -26,12 +26,66 @@ serverJson.version = packageJson.version;
 serverJson.packages[0].identifier = identity.packageName;
 serverJson.packages[0].version = packageJson.version;
 
-const generatedIdentity = `// Generated by scripts/sync-identity.mjs. Edit project.identity.json instead.\nexport const SERVER_NAME = ${JSON.stringify(identity.mcpServerName)};\nexport const SERVER_VERSION = ${JSON.stringify(packageJson.version)};\n`;
+const generatedIdentity = `// Generated by scripts/sync-identity.mjs. Edit project.identity.json instead.\nexport const SERVER_NAME = ${JSON.stringify(identity.mcpServerName)};\nexport const PACKAGE_NAME = ${JSON.stringify(identity.packageName)};\nexport const SERVER_VERSION = ${JSON.stringify(packageJson.version)};\n`;
+
+// The plugin manifests pin the published package by exact version. A pin that
+// drifts installs the OLD server from a NEW plugin, silently — so the pin is
+// generated here and `npm run check:identity` fails the build when it is stale.
+const pinnedArgs = ["-y", `${identity.packageName}@${packageJson.version}`];
+
+const mcpJson = await readJson(".mcp.json");
+mcpJson.mcpServers.planka.args = pinnedArgs;
+
+const codexMcpJson = await readJson(".codex-plugin/mcp.json");
+codexMcpJson.mcp_servers.planka.args = pinnedArgs;
+
+const claudePlugin = await readJson(".claude-plugin/plugin.json");
+claudePlugin.version = packageJson.version;
+claudePlugin.homepage = `${identity.repositoryUrl}#readme`;
+claudePlugin.repository = identity.repositoryUrl;
+
+const codexPlugin = await readJson(".codex-plugin/plugin.json");
+codexPlugin.version = packageJson.version;
+codexPlugin.homepage = `${identity.repositoryUrl}#readme`;
+codexPlugin.repository = identity.repositoryUrl;
+
+const marketplace = await readJson(".claude-plugin/marketplace.json");
+marketplace.plugins[0].version = packageJson.version;
+marketplace.plugins[0].homepage = `${identity.repositoryUrl}#readme`;
+marketplace.plugins[0].repository = identity.repositoryUrl;
+
+// The two skills the plugin installs carry their own `metadata.version`. They
+// are not JSON, so they get a targeted rewrite of that one line: left out of
+// this map they went stale on every release and `check:identity` never saw it.
+const skillFiles = [
+  "workflow/skills/planka-close-card/SKILL.md",
+  "workflow/skills/planka-orchestrator/SKILL.md",
+];
+
+const skillOutputs = await Promise.all(
+  skillFiles.map(async (name) => {
+    const current = await readFile(resolve(root, name), "utf8");
+    const updated = current.replace(
+      /^(\s*version:\s*).*$/m,
+      `$1${packageJson.version}`
+    );
+    if (updated === current && !current.includes(`version: ${packageJson.version}`)) {
+      throw new Error(`${name} has no metadata.version line to synchronize`);
+    }
+    return [name, updated];
+  })
+);
 
 const outputs = new Map([
   ["package.json", `${JSON.stringify(packageJson, null, 2)}\n`],
   ["server.json", `${JSON.stringify(serverJson, null, 2)}\n`],
   ["src/identity.generated.ts", generatedIdentity],
+  [".mcp.json", `${JSON.stringify(mcpJson, null, 2)}\n`],
+  [".codex-plugin/mcp.json", `${JSON.stringify(codexMcpJson, null, 2)}\n`],
+  [".claude-plugin/plugin.json", `${JSON.stringify(claudePlugin, null, 2)}\n`],
+  [".codex-plugin/plugin.json", `${JSON.stringify(codexPlugin, null, 2)}\n`],
+  [".claude-plugin/marketplace.json", `${JSON.stringify(marketplace, null, 2)}\n`],
+  ...skillOutputs,
 ]);
 
 let stale = false;

package/server.json

@@ -1,17 +1,28 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.omnicoreos/planka-mcp",
+  "title": "Planka MCP",
   "description": "Planka 2.x MCP server with verified card, task, comment, label, and list operations.",
+  "websiteUrl": "https://github.com/omnicoreos/planka-mcp",
+  "icons": [
+    {
+      "src": "https://avatars.githubusercontent.com/u/265942793?v=4",
+      "mimeType": "image/png",
+      "sizes": [
+        "460x460"
+      ]
+    }
+  ],
   "repository": {
     "url": "https://github.com/omnicoreos/planka-mcp",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@omnicoreos/planka-mcp",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },
@@ -23,19 +34,89 @@
           "format": "string",
           "isSecret": false
         },
+        {
+          "name": "PLANKA_API_KEY",
+          "description": "Planka API key (X-Api-Key). Recommended: replaces the email/password login",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true
+        },
         {
           "name": "PLANKA_AGENT_EMAIL",
-          "description": "Email address or username for the Planka agent user",
-          "isRequired": true,
+          "description": "Email or username of the Planka agent user. Only needed when PLANKA_API_KEY is not set",
+          "isRequired": false,
           "format": "string",
           "isSecret": false
         },
         {
           "name": "PLANKA_AGENT_PASSWORD",
-          "description": "Password for the Planka agent user",
-          "isRequired": true,
+          "description": "Password of the Planka agent user. Only needed when PLANKA_API_KEY is not set",
+          "isRequired": false,
           "format": "string",
           "isSecret": true
+        },
+        {
+          "name": "PLANKA_DEFAULT_BOARD_ID",
+          "description": "Board id used when a tool call omits boardId",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_ALLOWED_BOARD_IDS",
+          "description": "Comma-separated board ids this server may see and touch. Everything else is hidden",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_ALLOWED_PROJECT_IDS",
+          "description": "Comma-separated project ids this server may see. Everything else is hidden",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_READ_ONLY",
+          "description": "Set to true to hide and refuse every write tool",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_DISABLED_TOOLS",
+          "description": "Comma-separated tool names to switch off, for example planka_get_board",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_PROTECTED_LIST_IDS",
+          "description": "Comma-separated list ids that must not receive cards nor be edited or deleted",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_HIDE_DEPRECATED",
+          "description": "Set to true to drop the deprecated tool aliases from tools/list. They stay callable",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_SUMMARY_HIGHLIGHT_LABEL",
+          "description": "Label planka_board_summary flags as unblocked/ready. Unset: no highlighting",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "PLANKA_SUMMARY_DECISION_LISTS",
+          "description": "Comma-separated columns planka_board_summary returns cards from when the call does not say",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }