@omnicoreos/planka-mcp 0.2.0 → 0.3.0

package/dist/operations/verify.js

@@ -0,0 +1,124 @@
+/**
+ * Verified writes — the one place that decides whether a write LANDED.
+ *
+ * A 200 from Planka proves that the request was accepted, not that the change
+ * is in the database: `PATCH /api/cards/:id {isSubscribed:true}` answers 200
+ * with `isSubscribed: null`, and a `DELETE` that returns the deleted item is
+ * still worth re-reading. So every write in this server writes, re-reads, and
+ * reports what the re-read says — never what was asked for.
+ *
+ * The pattern was written twice by hand (setCardLabels, add_attachment); this
+ * module is that pattern, once.
+ */
+import { PlankaError } from "../errors.js";
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Run a write, re-read the entity, and report whether the change is really there.
+ *
+ * `landed` gets the re-read state and the write's own result; it answers the
+ * only question that matters: is what we asked for true now?
+ */
+export async function verifiedWrite(opts) {
+    const result = await opts.write();
+    let after;
+    try {
+        after = await opts.reread(result);
+    }
+    catch (error) {
+        return {
+            result,
+            verified: false,
+            verificationError: `the write was sent but could not be re-read: ${describe(error)}`,
+        };
+    }
+    return { result, verified: opts.landed(after, result), after };
+}
+/**
+ * Run a delete and confirm the entity is really gone.
+ *
+ * `confirmGone` returns true (gone), false (still there) or null (could not
+ * check — e.g. the parent id needed for the re-read is unknown).
+ */
+export async function verifiedDelete(opts) {
+    const result = await opts.del();
+    let gone;
+    try {
+        gone = await opts.confirmGone(result);
+    }
+    catch (error) {
+        return {
+            result,
+            verified: false,
+            verificationError: `the delete was sent but could not be confirmed: ${describe(error)}`,
+        };
+    }
+    if (gone === null) {
+        return {
+            result,
+            verified: false,
+            verificationUnavailable: opts.unknownReason ?? "the entity's parent is unknown, so the delete could not be confirmed",
+        };
+    }
+    return { result, verified: gone };
+}
+/**
+ * Confirmation helper for entities that have their own GET: a 404 on re-read
+ * is the proof of deletion. Any other failure propagates.
+ */
+export async function goneOn404(reread) {
+    try {
+        await reread();
+        return false;
+    }
+    catch (error) {
+        if (error instanceof PlankaError && error.status === 404)
+            return true;
+        throw error;
+    }
+}
+/**
+ * Standard tool payload for a write.
+ *
+ * `success` mirrors `verified` and nothing else. "I could not check" is not a
+ * success: a payload that says `success: true` next to `verified: false` and
+ * "delete not confirmed" is read by the model as done, and the model moves on.
+ *
+ * - verified            → success, no isError
+ * - unavailable         → success:false, verified:false, isError, and a
+ *                         `verificationUnavailable` that names the parameter
+ *                         which would have made the check possible
+ * - anything else       → isError, because the write cannot be claimed
+ */
+export function writeResult(payload, v) {
+    const body = {
+        success: v.verified,
+        verified: v.verified,
+        ...(v.verificationError ? { verificationError: v.verificationError } : {}),
+        ...(v.verificationUnavailable && !v.verificationError
+            ? { verificationUnavailable: v.verificationUnavailable }
+            : {}),
+        ...payload,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(body) }],
+        ...(v.verified ? {} : { isError: true }),
+    };
+}
+/**
+ * The "nothing to do" guard shared by the update tools: a PATCH with only an
+ * id is a no-op that Planka happily answers 200 to.
+ */
+export function nothingToDo(fields, extra) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error: nothing to do — pass at least one field to change (${fields}).${extra ? ` ${extra}` : ""}`,
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/operations/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/operations/verify.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP prompts: three ways to start, all of them cheap.
+ *
+ * A prompt costs nothing until it is invoked — Claude Code surfaces them as
+ * `/mcp__planka__<name>`, Cursor from its prompt picker — so this is where the
+ * "how do I open / close / triage" procedures live instead of in `instructions`.
+ * They deliberately do NOT restate what tool descriptions already say; they
+ * order the calls and say what to look at in the answers.
+ *
+ * Codex supports neither prompts nor resources, so nothing here is required for
+ * correct use of the server.
+ *
+ * The three overlap with the workflow skills on purpose: the skills are the long
+ * form for a repo that adopted the board workflow, these are the short form for
+ * everyone else.
+ */
+export interface PromptArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface PromptDefinition {
+    name: string;
+    title: string;
+    description: string;
+    arguments: PromptArgument[];
+    render: (args: Record<string, string>) => string;
+}
+export declare const PROMPTS: readonly PromptDefinition[];
+/** What `prompts/list` answers. Deterministic order, cacheable by the client. */
+export declare function listPrompts(): {
+    name: string;
+    title: string;
+    description: string;
+    arguments: PromptArgument[];
+}[];
+/** What `prompts/get` answers. Unknown name throws; a missing required argument too. */
+export declare function getPrompt(name: string, args?: Record<string, string>): {
+    description: string;
+    messages: {
+        role: "user";
+        content: {
+            type: "text";
+            text: string;
+        };
+    }[];
+};
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;CAClD;AAqBD,eAAO,MAAM,OAAO,EAAE,SAAS,gBAAgB,EA+F9C,CAAC;AAIF,iFAAiF;AACjF,wBAAgB,WAAW;;;;;IAO1B;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;;;;;;;;;EA2BxE"}

package/dist/prompts.js

@@ -0,0 +1,155 @@
+/**
+ * MCP prompts: three ways to start, all of them cheap.
+ *
+ * A prompt costs nothing until it is invoked — Claude Code surfaces them as
+ * `/mcp__planka__<name>`, Cursor from its prompt picker — so this is where the
+ * "how do I open / close / triage" procedures live instead of in `instructions`.
+ * They deliberately do NOT restate what tool descriptions already say; they
+ * order the calls and say what to look at in the answers.
+ *
+ * Codex supports neither prompts nor resources, so nothing here is required for
+ * correct use of the server.
+ *
+ * The three overlap with the workflow skills on purpose: the skills are the long
+ * form for a repo that adopted the board workflow, these are the short form for
+ * everyone else.
+ */
+const boardArgument = {
+    name: "boardId",
+    description: "Board to work on. Optional: omit it when PLANKA_DEFAULT_BOARD_ID is configured, or let the summary resolve it.",
+    required: false,
+};
+/** "on board <id>" or "" — keeps the rendered text readable either way. */
+function onBoard(args) {
+    const boardId = args.boardId?.trim();
+    return boardId ? ` on board ${boardId}` : "";
+}
+function boardIdNote(args) {
+    return args.boardId?.trim()
+        ? ""
+        : " If no board is configured as the default, call planka_get_structure once to get its ID and say which board you picked.";
+}
+export const PROMPTS = [
+    {
+        name: "planka-open-session",
+        title: "Open a Planka session",
+        description: "Read the board the cheap way and report where it stands: columns, counts, what moved recently, what is waiting on a human.",
+        arguments: [
+            boardArgument,
+            {
+                name: "since",
+                description: "ISO date to measure recent movement from (defaults to the last 24 hours).",
+                required: false,
+            },
+        ],
+        render: (args) => {
+            const since = args.since?.trim();
+            return [
+                `Open the Planka board${onBoard(args)} and tell me where it stands.${boardIdNote(args)}`,
+                "",
+                "1. planka_board_summary first: it returns every column with its card count and every label with its ID in one call. Do not call planka_get_board.",
+                `2. planka_board_activity ${since ? `since ${since}` : "for the last 24 hours"}: what moved and who moved it. Planka logs card creation, moves, member changes and task completion only — comments and edits do not appear there.`,
+                "3. planka_find_cards with the listId of any column that looks decisive (blocked, waiting on a decision, ready to review): with a listId it reads a whole column in one request, nothing clipped.",
+                "",
+                "Then report, in this order: the shape of the board (columns and counts), what moved since the cutoff, the cards waiting on a human, and anything that looks stale or contradictory. Do not open individual cards yet — say which ones you would open and why.",
+            ].join("\n");
+        },
+    },
+    {
+        name: "planka-close-card",
+        title: "Close a Planka card",
+        description: "Record a closing comment with real evidence, move the card, and prove both landed.",
+        arguments: [
+            {
+                name: "cardId",
+                description: "Card to close.",
+                required: true,
+            },
+            {
+                name: "listId",
+                description: "Column to move the card to. Optional: without it, propose the destination and ask before moving.",
+                required: false,
+            },
+        ],
+        render: (args) => {
+            const cardId = args.cardId?.trim() || "<cardId>";
+            const listId = args.listId?.trim();
+            return [
+                `Close Planka card ${cardId}.`,
+                "",
+                `1. Read it whole first: planka_get_card ${cardId} with withComments, and keep paging planka_get_comments while hasMore is true. The description says how the card was born; the comments say where it stands today, and the last one usually wins. Never act on a card you have not read to the end.`,
+                "2. State the evidence you actually have: what changed, where to check it, the one step that proves it, what could regress nearby, and what you could NOT verify. If a claim has no evidence, say so instead of implying it.",
+                "3. planka_add_comment with that closing note.",
+                listId
+                    ? `4. planka_move_card to list ${listId}.`
+                    : "4. Propose the destination column (from planka_board_summary) and ask me before moving the card.",
+                "5. Check the `verified` field of both writes. A write that comes back without it confirmed nothing — re-read the card before telling me it is closed.",
+                "",
+                "Do not apply a human-only label (decided, tested-ok or the equivalent on this board) on my behalf.",
+            ].join("\n");
+        },
+    },
+    {
+        name: "planka-board-triage",
+        title: "Triage the decision columns",
+        description: "Walk the columns that are waiting on a person and turn each card into one concrete question or next step.",
+        arguments: [
+            boardArgument,
+            {
+                name: "lists",
+                description: "Comma-separated names of the columns to walk. Defaults to whatever the summary shows as waiting on a human.",
+                required: false,
+            },
+        ],
+        render: (args) => {
+            const lists = args.lists?.trim();
+            return [
+                `Triage the Planka cards that are waiting on a person${onBoard(args)}.${boardIdNote(args)}`,
+                "",
+                "1. planka_board_summary to get the columns and their label IDs.",
+                lists
+                    ? `2. Walk these columns, in order: ${lists}. Use planka_find_cards with each listId — one request per column, nothing clipped.`
+                    : "2. Pick the columns that are waiting on a human (a decision queue, a review queue, anything blocked) and walk them with planka_find_cards by listId — one request per column, nothing clipped.",
+                "3. For each card, read every comment (planka_get_card with withComments, paging planka_get_comments while hasMore). A card whose thread you did not finish is a card you cannot triage.",
+                "",
+                "For every card report one line: what it is waiting for, who owes the next move, and how long it has been sitting there. Then rank them: what is blocking other work first, what is stale and probably dead last. Flag any card whose comments contradict its description or its column, and say which side you believe.",
+                "",
+                "Do not move cards or apply labels during triage. Propose; I decide.",
+            ].join("\n");
+        },
+    },
+];
+const byName = new Map(PROMPTS.map((prompt) => [prompt.name, prompt]));
+/** What `prompts/list` answers. Deterministic order, cacheable by the client. */
+export function listPrompts() {
+    return PROMPTS.map(({ name, title, description, arguments: args }) => ({
+        name,
+        title,
+        description,
+        arguments: args,
+    }));
+}
+/** What `prompts/get` answers. Unknown name throws; a missing required argument too. */
+export function getPrompt(name, args = {}) {
+    const prompt = byName.get(name);
+    if (!prompt) {
+        throw new Error(`Unknown prompt: ${name}. Available: ${PROMPTS.map((p) => p.name).join(", ")}`);
+    }
+    const missing = prompt.arguments
+        .filter((argument) => argument.required)
+        .filter((argument) => !args[argument.name]?.trim())
+        .map((argument) => argument.name);
+    if (missing.length > 0) {
+        throw new Error(`Prompt ${name} needs: ${missing.join(", ")}.`);
+    }
+    return {
+        description: prompt.description,
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text: prompt.render(args) },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,38 @@
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    /** Path inside the package, relative to its root. Absent = generated. */
+    file?: string;
+    /** Generated resources build their own body. */
+    generate?: () => string;
+}
+/** The valid Planka label colors, straight from the schema the tools validate with. */
+export declare function labelColorsDocument(): string;
+/**
+ * The catalogue. Order is fixed on purpose: `resources/list` should be
+ * deterministic so clients can cache it and prompt caches keep hitting.
+ */
+export declare const RESOURCES: readonly ResourceDefinition[];
+/** Everything `resources/list` answers. Shape matches the MCP `Resource` type. */
+export declare function listResources(): {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+}[];
+/**
+ * Body of one resource. Unknown URIs throw: a resource read that silently
+ * answers empty is the same false green as a write that never re-reads.
+ */
+export declare function readResource(uri: string): Promise<{
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,IAAI,MAAM,CAW5C;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,kBAAkB,EAuDlD,CAAC;AAgBF,kFAAkF;AAClF,wBAAgB,aAAa;;;;;;IAQ5B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D,CAAC,CAsBD"}

package/dist/resources.js

@@ -0,0 +1,127 @@
+/**
+ * MCP resources: the guides that travel in the tarball, served over the wire.
+ *
+ * Why resources and not more `instructions`: a resource costs nothing until
+ * someone reads it. `instructions` is a fixed per-session cost paid on top of
+ * `tools/list`, so it holds only what every session needs; everything longer —
+ * the workflow guide, the board template, the two skills, the Planka 2.x
+ * gotchas — lives here and is pulled on demand (Claude Code by `@`-mention,
+ * Cursor from its resource picker). Codex does not support resources; that is
+ * why nothing here is load-bearing for correctness.
+ *
+ * Files are read from the published package at runtime, resolved from
+ * `import.meta.url`, so `dist/resources.js` and `src/resources.ts` both sit one
+ * level under the package root and find `workflow/` and `docs/` the same way.
+ * A missing file is not an error: an install that trimmed the tarball gets a
+ * short note pointing at the repository instead of a broken read.
+ */
+import { readFile } from "node:fs/promises";
+import { LabelColorSchema } from "./schemas/entities.js";
+const REPO_URL = "https://github.com/omnicoreos/planka-mcp";
+/** The valid Planka label colors, straight from the schema the tools validate with. */
+export function labelColorsDocument() {
+    return JSON.stringify({
+        description: "Valid values for the `color` field of planka_create_label and planka_update_label. Planka rejects anything else with a validation error.",
+        colors: LabelColorSchema.options,
+        count: LabelColorSchema.options.length,
+    }, null, 2);
+}
+/**
+ * The catalogue. Order is fixed on purpose: `resources/list` should be
+ * deterministic so clients can cache it and prompt caches keep hitting.
+ */
+export const RESOURCES = [
+    {
+        uri: "planka://workflow/readme",
+        name: "workflow-readme",
+        title: "Planka agent workflow",
+        description: "The optional board workflow: columns, labels, who moves what, and the director/worker split. Read it before running cards in parallel.",
+        mimeType: "text/markdown",
+        file: "workflow/README.md",
+    },
+    {
+        uri: "planka://workflow/board-template",
+        name: "workflow-board-template",
+        title: "Workflow board template",
+        description: "The columns and labels the workflow expects, ready to create on a fresh board.",
+        mimeType: "text/markdown",
+        file: "workflow/board-template.md",
+    },
+    {
+        uri: "planka://workflow/skills/orchestrator",
+        name: "skill-orchestrator",
+        title: "Skill: planka-orchestrator",
+        description: "Director role: select cards, dispatch one worker per card, audit evidence, merge. Same text the plugin installs as a skill.",
+        mimeType: "text/markdown",
+        file: "workflow/skills/planka-orchestrator/SKILL.md",
+    },
+    {
+        uri: "planka://workflow/skills/close-card",
+        name: "skill-close-card",
+        title: "Skill: planka-close-card",
+        description: "Closing a card honestly: required evidence, the closing comment template, and which transition each role owns.",
+        mimeType: "text/markdown",
+        file: "workflow/skills/planka-close-card/SKILL.md",
+    },
+    {
+        uri: "planka://gotchas/planka-2x",
+        name: "planka-2x-gotchas",
+        title: "Planka 2.x gotchas",
+        description: "How Planka 2.x actually behaves: HTML-with-200 on unknown GETs, 404 that means 403, fixed page sizes, archive lists. Read this when a call answers something that makes no sense.",
+        mimeType: "text/markdown",
+        file: "docs/planka-2x-gotchas.md",
+    },
+    {
+        uri: "planka://labels/colors",
+        name: "label-colors",
+        title: "Valid label colors",
+        description: "Every color planka_create_label and planka_update_label accept, as JSON. Generated from the schema, so it can never drift from what the server validates.",
+        mimeType: "application/json",
+        generate: labelColorsDocument,
+    },
+];
+const byUri = new Map(RESOURCES.map((resource) => [resource.uri, resource]));
+/** Package root: this module lives one level under it in both src/ and dist/. */
+function packageRoot() {
+    return new URL("../", import.meta.url);
+}
+function missingFileNote(resource) {
+    return (`${resource.title} is not present in this installation ` +
+        `(expected ${resource.file}). Read it at ${REPO_URL}/blob/main/${resource.file}.`);
+}
+/** Everything `resources/list` answers. Shape matches the MCP `Resource` type. */
+export function listResources() {
+    return RESOURCES.map(({ uri, name, title, description, mimeType }) => ({
+        uri,
+        name,
+        title,
+        description,
+        mimeType,
+    }));
+}
+/**
+ * Body of one resource. Unknown URIs throw: a resource read that silently
+ * answers empty is the same false green as a write that never re-reads.
+ */
+export async function readResource(uri) {
+    const resource = byUri.get(uri);
+    if (!resource) {
+        throw new Error(`Unknown resource: ${uri}. Available: ${RESOURCES.map((r) => r.uri).join(", ")}`);
+    }
+    let text;
+    if (resource.generate) {
+        text = resource.generate();
+    }
+    else {
+        try {
+            text = await readFile(new URL(resource.file, packageRoot()), "utf8");
+        }
+        catch {
+            text = missingFileNote(resource);
+        }
+    }
+    return {
+        contents: [{ uri: resource.uri, mimeType: resource.mimeType, text }],
+    };
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}