@omnicoreos/planka-mcp 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +20 -0
- package/.claude-plugin/marketplace.json +26 -0
- package/.claude-plugin/plugin.json +45 -0
- package/.codex-plugin/mcp.json +16 -0
- package/.codex-plugin/plugin.json +27 -0
- package/.mcp.json +17 -0
- package/CHANGELOG.md +510 -0
- package/README.es.md +294 -55
- package/README.md +293 -55
- package/dist/cli/init.d.ts +101 -0
- package/dist/cli/init.d.ts.map +1 -0
- package/dist/cli/init.js +481 -0
- package/dist/cli/init.js.map +1 -0
- package/dist/client.d.ts +32 -4
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +106 -32
- package/dist/client.js.map +1 -1
- package/dist/config/policy.d.ts +82 -0
- package/dist/config/policy.d.ts.map +1 -0
- package/dist/config/policy.js +226 -0
- package/dist/config/policy.js.map +1 -0
- package/dist/errors.d.ts +5 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +62 -5
- package/dist/errors.js.map +1 -1
- package/dist/identity.generated.d.ts +2 -1
- package/dist/identity.generated.d.ts.map +1 -1
- package/dist/identity.generated.js +2 -1
- package/dist/identity.generated.js.map +1 -1
- package/dist/index.js +85 -10
- package/dist/index.js.map +1 -1
- package/dist/instructions.d.ts +21 -0
- package/dist/instructions.d.ts.map +1 -0
- package/dist/instructions.js +37 -0
- package/dist/instructions.js.map +1 -0
- package/dist/operations/actions.d.ts +654 -0
- package/dist/operations/actions.d.ts.map +1 -0
- package/dist/operations/actions.js +154 -0
- package/dist/operations/actions.js.map +1 -0
- package/dist/operations/archive.d.ts +28 -0
- package/dist/operations/archive.d.ts.map +1 -0
- package/dist/operations/archive.js +74 -0
- package/dist/operations/archive.js.map +1 -0
- package/dist/operations/attachments.d.ts +1 -1
- package/dist/operations/attachments.d.ts.map +1 -1
- package/dist/operations/attachments.js +3 -1
- package/dist/operations/attachments.js.map +1 -1
- package/dist/operations/board-id.d.ts +1 -1
- package/dist/operations/board-id.d.ts.map +1 -1
- package/dist/operations/board-id.js +13 -7
- package/dist/operations/board-id.js.map +1 -1
- package/dist/operations/boards.d.ts +96 -19
- package/dist/operations/boards.d.ts.map +1 -1
- package/dist/operations/boards.js +377 -93
- package/dist/operations/boards.js.map +1 -1
- package/dist/operations/card-brief.d.ts +91 -0
- package/dist/operations/card-brief.d.ts.map +1 -0
- package/dist/operations/card-brief.js +79 -0
- package/dist/operations/card-brief.js.map +1 -0
- package/dist/operations/cards.d.ts +34 -9
- package/dist/operations/cards.d.ts.map +1 -1
- package/dist/operations/cards.js +60 -14
- package/dist/operations/cards.js.map +1 -1
- package/dist/operations/comments.d.ts +61 -4
- package/dist/operations/comments.d.ts.map +1 -1
- package/dist/operations/comments.js +91 -8
- package/dist/operations/comments.js.map +1 -1
- package/dist/operations/duplicate.d.ts +16 -0
- package/dist/operations/duplicate.d.ts.map +1 -0
- package/dist/operations/duplicate.js +43 -0
- package/dist/operations/duplicate.js.map +1 -0
- package/dist/operations/labels.d.ts +1 -1
- package/dist/operations/labels.d.ts.map +1 -1
- package/dist/operations/labels.js +7 -4
- package/dist/operations/labels.js.map +1 -1
- package/dist/operations/lists.d.ts +63 -1
- package/dist/operations/lists.d.ts.map +1 -1
- package/dist/operations/lists.js +97 -2
- package/dist/operations/lists.js.map +1 -1
- package/dist/operations/members.d.ts +39 -0
- package/dist/operations/members.d.ts.map +1 -0
- package/dist/operations/members.js +107 -0
- package/dist/operations/members.js.map +1 -0
- package/dist/operations/projects.d.ts +16 -0
- package/dist/operations/projects.d.ts.map +1 -1
- package/dist/operations/projects.js +54 -9
- package/dist/operations/projects.js.map +1 -1
- package/dist/operations/tasks.d.ts +1 -1
- package/dist/operations/tasks.d.ts.map +1 -1
- package/dist/operations/tasks.js +5 -3
- package/dist/operations/tasks.js.map +1 -1
- package/dist/operations/users.d.ts +123 -0
- package/dist/operations/users.d.ts.map +1 -0
- package/dist/operations/users.js +180 -0
- package/dist/operations/users.js.map +1 -0
- package/dist/operations/verify.d.ts +84 -0
- package/dist/operations/verify.d.ts.map +1 -0
- package/dist/operations/verify.js +124 -0
- package/dist/operations/verify.js.map +1 -0
- package/dist/prompts.d.ts +48 -0
- package/dist/prompts.d.ts.map +1 -0
- package/dist/prompts.js +155 -0
- package/dist/prompts.js.map +1 -0
- package/dist/resources.d.ts +38 -0
- package/dist/resources.d.ts.map +1 -0
- package/dist/resources.js +127 -0
- package/dist/resources.js.map +1 -0
- package/dist/schemas/entities.d.ts +115 -24
- package/dist/schemas/entities.d.ts.map +1 -1
- package/dist/schemas/entities.js +48 -0
- package/dist/schemas/entities.js.map +1 -1
- package/dist/schemas/requests.d.ts +121 -46
- package/dist/schemas/requests.d.ts.map +1 -1
- package/dist/schemas/requests.js +57 -12
- package/dist/schemas/requests.js.map +1 -1
- package/dist/schemas/responses.d.ts +541 -186
- package/dist/schemas/responses.d.ts.map +1 -1
- package/dist/schemas/responses.js +13 -2
- package/dist/schemas/responses.js.map +1 -1
- package/dist/tools/activity.d.ts +150 -0
- package/dist/tools/activity.d.ts.map +1 -0
- package/dist/tools/activity.js +198 -0
- package/dist/tools/activity.js.map +1 -0
- package/dist/tools/annotations.d.ts +52 -0
- package/dist/tools/annotations.d.ts.map +1 -0
- package/dist/tools/annotations.js +214 -0
- package/dist/tools/annotations.js.map +1 -0
- package/dist/tools/attachments.d.ts +28 -4
- package/dist/tools/attachments.d.ts.map +1 -1
- package/dist/tools/attachments.js +53 -34
- package/dist/tools/attachments.js.map +1 -1
- package/dist/tools/card-ops.d.ts +232 -0
- package/dist/tools/card-ops.d.ts.map +1 -0
- package/dist/tools/card-ops.js +333 -0
- package/dist/tools/card-ops.js.map +1 -0
- package/dist/tools/cards.d.ts +90 -8
- package/dist/tools/cards.d.ts.map +1 -1
- package/dist/tools/cards.js +411 -128
- package/dist/tools/cards.js.map +1 -1
- package/dist/tools/comments.d.ts +226 -22
- package/dist/tools/comments.d.ts.map +1 -1
- package/dist/tools/comments.js +163 -134
- package/dist/tools/comments.js.map +1 -1
- package/dist/tools/dispatch.d.ts +47 -0
- package/dist/tools/dispatch.d.ts.map +1 -0
- package/dist/tools/dispatch.js +63 -0
- package/dist/tools/dispatch.js.map +1 -0
- package/dist/tools/guard.d.ts +9 -0
- package/dist/tools/guard.d.ts.map +1 -0
- package/dist/tools/guard.js +20 -0
- package/dist/tools/guard.js.map +1 -0
- package/dist/tools/index.d.ts +748 -450
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +136 -17
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/labels.d.ts +213 -18
- package/dist/tools/labels.d.ts.map +1 -1
- package/dist/tools/labels.js +218 -203
- package/dist/tools/labels.js.map +1 -1
- package/dist/tools/lists.d.ts +222 -15
- package/dist/tools/lists.d.ts.map +1 -1
- package/dist/tools/lists.js +175 -156
- package/dist/tools/lists.js.map +1 -1
- package/dist/tools/members.d.ts +128 -0
- package/dist/tools/members.d.ts.map +1 -0
- package/dist/tools/members.js +150 -0
- package/dist/tools/members.js.map +1 -0
- package/dist/tools/navigation.d.ts +22 -2
- package/dist/tools/navigation.d.ts.map +1 -1
- package/dist/tools/navigation.js +60 -15
- package/dist/tools/navigation.js.map +1 -1
- package/dist/tools/queries.d.ts +196 -166
- package/dist/tools/queries.d.ts.map +1 -1
- package/dist/tools/queries.js +125 -155
- package/dist/tools/queries.js.map +1 -1
- package/dist/tools/tasks.d.ts +26 -6
- package/dist/tools/tasks.d.ts.map +1 -1
- package/dist/tools/tasks.js +110 -55
- package/dist/tools/tasks.js.map +1 -1
- package/dist/tools/users.d.ts +130 -0
- package/dist/tools/users.d.ts.map +1 -0
- package/dist/tools/users.js +165 -0
- package/dist/tools/users.js.map +1 -0
- package/docs/planka-2x-gotchas.md +121 -5
- package/docs/tools.md +771 -187
- package/docs/troubleshooting.md +137 -5
- package/hooks/hooks.json +15 -0
- package/hooks/preflight.mjs +100 -0
- package/package.json +6 -1
- package/scripts/setup.sh +8 -26
- package/scripts/sync-identity.mjs +55 -1
- package/server.json +87 -6
- package/tests/smoke/planka-smoke.mjs +512 -72
- package/workflow/skills/planka-close-card/SKILL.md +18 -5
- package/workflow/skills/planka-orchestrator/SKILL.md +36 -7
package/dist/errors.js
CHANGED
|
@@ -21,8 +21,8 @@ export class PlankaAuthError extends PlankaError {
|
|
|
21
21
|
}
|
|
22
22
|
}
|
|
23
23
|
export class PlankaNotFoundError extends PlankaError {
|
|
24
|
-
constructor(resource, id) {
|
|
25
|
-
super(`${resource} not found: ${id}`, "NOT_FOUND", 404);
|
|
24
|
+
constructor(resource, id, hint) {
|
|
25
|
+
super(`${resource} not found: ${id}${hint ? ` — ${hint}` : ""}`, "NOT_FOUND", 404);
|
|
26
26
|
this.name = "PlankaNotFoundError";
|
|
27
27
|
}
|
|
28
28
|
}
|
|
@@ -56,6 +56,56 @@ export class PlankaNetworkError extends PlankaError {
|
|
|
56
56
|
* @param body Response body (parsed JSON or null)
|
|
57
57
|
* @param context Optional context (e.g., "GET /api/cards/123")
|
|
58
58
|
*/
|
|
59
|
+
/**
|
|
60
|
+
* Which kind of ID the last path segment of a request is supposed to be.
|
|
61
|
+
* `/api/labels/123` -> labelId. Every Planka ID is a string of digits, so
|
|
62
|
+
* passing the wrong one is invisible until this 404 comes back.
|
|
63
|
+
*/
|
|
64
|
+
const ID_KIND_BY_COLLECTION = {
|
|
65
|
+
cards: "cardId",
|
|
66
|
+
lists: "listId",
|
|
67
|
+
boards: "boardId",
|
|
68
|
+
projects: "projectId",
|
|
69
|
+
labels: "labelId",
|
|
70
|
+
comments: "commentId",
|
|
71
|
+
tasks: "taskId",
|
|
72
|
+
"task-lists": "taskListId",
|
|
73
|
+
attachments: "attachmentId",
|
|
74
|
+
users: "userId",
|
|
75
|
+
"custom-field-groups": "customFieldGroupId",
|
|
76
|
+
};
|
|
77
|
+
/** The ID kind a context like "PATCH /api/labels/123" was addressing. */
|
|
78
|
+
export function idKindFromContext(context) {
|
|
79
|
+
if (!context)
|
|
80
|
+
return undefined;
|
|
81
|
+
const path = context.split(" ").pop() ?? context;
|
|
82
|
+
const match = /\/api\/([a-z-]+)\/([^/?]+)/.exec(path);
|
|
83
|
+
if (!match)
|
|
84
|
+
return undefined;
|
|
85
|
+
// `/api/users/me` is a literal route, not an id: every Planka id is a string
|
|
86
|
+
// of digits, so anything else in that slot is a named endpoint and telling
|
|
87
|
+
// the caller "this has to be a userId" would be wrong.
|
|
88
|
+
if (!/^\d+$/.test(match[2]))
|
|
89
|
+
return undefined;
|
|
90
|
+
return ID_KIND_BY_COLLECTION[match[1]];
|
|
91
|
+
}
|
|
92
|
+
/** What a 404 on this request most likely means, in the order to check it. */
|
|
93
|
+
function notFoundHint(context) {
|
|
94
|
+
const kind = idKindFromContext(context);
|
|
95
|
+
const wrongType = kind
|
|
96
|
+
? `the ID in this path has to be a ${kind}; every Planka ID is a string of digits, so a labelId passed as a listId (or a listId as a cardId) answers exactly this. `
|
|
97
|
+
: "";
|
|
98
|
+
return (`${wrongType}Planka also answers 404 where it means 403: if the ID read fine a moment ago, the agent user is probably not a member of that board. ` +
|
|
99
|
+
`Confirm the ID with planka_board_summary or planka_get_structure before assuming the entity is gone.`);
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Factory function to create typed errors from API responses.
|
|
103
|
+
*
|
|
104
|
+
* Every branch answers "what should the agent do now?", not just "what broke".
|
|
105
|
+
* @param status HTTP status code
|
|
106
|
+
* @param body Response body (parsed JSON or null)
|
|
107
|
+
* @param context Optional context (e.g., "GET /api/cards/123")
|
|
108
|
+
*/
|
|
59
109
|
export function createPlankaError(status, body, context) {
|
|
60
110
|
const message = typeof body === "object" && body !== null && "message" in body
|
|
61
111
|
? String(body.message)
|
|
@@ -63,11 +113,18 @@ export function createPlankaError(status, body, context) {
|
|
|
63
113
|
const contextSuffix = context ? ` (${context})` : "";
|
|
64
114
|
switch (status) {
|
|
65
115
|
case 401:
|
|
66
|
-
|
|
116
|
+
// The client already retried once with a fresh token, so reaching here
|
|
117
|
+
// means the credentials themselves are the problem.
|
|
118
|
+
return new PlankaAuthError(`${message}${contextSuffix}. Planka rejected the credentials even after a fresh login — ` +
|
|
119
|
+
"the token is renegotiated automatically, so this is not an expired session. " +
|
|
120
|
+
"Check PLANKA_API_KEY, or PLANKA_AGENT_EMAIL / PLANKA_AGENT_PASSWORD.");
|
|
67
121
|
case 403:
|
|
68
|
-
return new PlankaPermissionError(message +
|
|
122
|
+
return new PlankaPermissionError(`${message}${contextSuffix}. Forbidden: the agent user is probably not a member of this board, ` +
|
|
123
|
+
"or is a viewer where an editor is needed. Planka may also answer 404 for this same cause.");
|
|
69
124
|
case 404:
|
|
70
|
-
|
|
125
|
+
// The body's own message is worth keeping: Planka distinguishes
|
|
126
|
+
// E_NOT_FOUND from "Card not found" and the like.
|
|
127
|
+
return new PlankaNotFoundError("Resource", context || "unknown", `${message !== "Unknown error" ? `Planka said "${message}". ` : ""}${notFoundHint(context)}`);
|
|
71
128
|
case 422:
|
|
72
129
|
return new PlankaValidationError(message + contextSuffix, body);
|
|
73
130
|
default:
|
package/dist/errors.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGlB;IACA;IACA;IAJlB,YACE,OAAe,EACC,IAAY,EACZ,MAAc,EACd,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,YAAY,OAAO,GAAG,uBAAuB;QAC3C,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAClD,YAAY,QAAgB,EAAE,EAAU;
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export declare const SERVER_NAME = "io.github.omnicoreos/planka-mcp";
|
|
2
|
-
export declare const
|
|
2
|
+
export declare const PACKAGE_NAME = "@omnicoreos/planka-mcp";
|
|
3
|
+
export declare const SERVER_VERSION = "0.3.0";
|
|
3
4
|
//# sourceMappingURL=identity.generated.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.generated.d.ts","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,oCAAoC,CAAC;AAC7D,eAAO,MAAM,cAAc,UAAU,CAAC"}
|
|
1
|
+
{"version":3,"file":"identity.generated.d.ts","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,oCAAoC,CAAC;AAC7D,eAAO,MAAM,YAAY,2BAA2B,CAAC;AACrD,eAAO,MAAM,cAAc,UAAU,CAAC"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
// Generated by scripts/sync-identity.mjs. Edit project.identity.json instead.
|
|
2
2
|
export const SERVER_NAME = "io.github.omnicoreos/planka-mcp";
|
|
3
|
-
export const
|
|
3
|
+
export const PACKAGE_NAME = "@omnicoreos/planka-mcp";
|
|
4
|
+
export const SERVER_VERSION = "0.3.0";
|
|
4
5
|
//# sourceMappingURL=identity.generated.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"identity.generated.js","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,iCAAiC,CAAC;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC"}
|
|
1
|
+
{"version":3,"file":"identity.generated.js","sourceRoot":"","sources":["../src/identity.generated.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,iCAAiC,CAAC;AAC7D,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -7,10 +7,13 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
9
9
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
10
|
-
import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
|
|
11
|
-
import { getToolDefinitions, getTool, allTools, findMissingRequiredArgs, } from "./tools/index.js";
|
|
10
|
+
import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
|
|
11
|
+
import { getToolDefinitions, getTool, allTools, effectiveInputSchema, findMissingRequiredArgs, } from "./tools/index.js";
|
|
12
12
|
import { PlankaError, PlankaConfigError, PlankaInputError, formatInputError, formatMissingArgsError, formatResponseShapeError, isZodError, } from "./errors.js";
|
|
13
13
|
import { SERVER_NAME, SERVER_VERSION } from "./identity.generated.js";
|
|
14
|
+
import { SERVER_INSTRUCTIONS } from "./instructions.js";
|
|
15
|
+
import { listResources, readResource } from "./resources.js";
|
|
16
|
+
import { getPrompt, listPrompts } from "./prompts.js";
|
|
14
17
|
/** Standard error response back to the model. */
|
|
15
18
|
function errorResult(text) {
|
|
16
19
|
return {
|
|
@@ -29,7 +32,14 @@ async function main() {
|
|
|
29
32
|
}, {
|
|
30
33
|
capabilities: {
|
|
31
34
|
tools: {},
|
|
35
|
+
// Both are read-only catalogues that never change while the process
|
|
36
|
+
// lives, so neither declares listChanged.
|
|
37
|
+
resources: {},
|
|
38
|
+
prompts: {},
|
|
32
39
|
},
|
|
40
|
+
// Sent back in the initialize handshake. Claude Code puts it in the system
|
|
41
|
+
// prompt, Codex reads it alongside the tool list.
|
|
42
|
+
instructions: SERVER_INSTRUCTIONS,
|
|
33
43
|
});
|
|
34
44
|
// Handler for listing available tools
|
|
35
45
|
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
@@ -37,6 +47,18 @@ async function main() {
|
|
|
37
47
|
tools: getToolDefinitions(),
|
|
38
48
|
};
|
|
39
49
|
});
|
|
50
|
+
// The guides that ship in the tarball, served on demand. Cost is zero until
|
|
51
|
+
// a client actually reads one, which is why they hold what does not fit in
|
|
52
|
+
// `instructions`.
|
|
53
|
+
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
|
|
54
|
+
resources: listResources(),
|
|
55
|
+
}));
|
|
56
|
+
server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
|
|
57
|
+
// Slash-command shaped entry points (Claude Code: /mcp__planka__…).
|
|
58
|
+
server.setRequestHandler(ListPromptsRequestSchema, async () => ({
|
|
59
|
+
prompts: listPrompts(),
|
|
60
|
+
}));
|
|
61
|
+
server.setRequestHandler(GetPromptRequestSchema, async (request) => getPrompt(request.params.name, request.params.arguments ?? {}));
|
|
40
62
|
// Handler for tool calls
|
|
41
63
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
42
64
|
const { name, arguments: args } = request.params;
|
|
@@ -48,9 +70,10 @@ async function main() {
|
|
|
48
70
|
}
|
|
49
71
|
// Presence check before entering the handler: a missing required field has
|
|
50
72
|
// to name the tool and the field, not die somewhere inside.
|
|
73
|
+
const schema = effectiveInputSchema(tool);
|
|
51
74
|
const missing = findMissingRequiredArgs(tool, args);
|
|
52
75
|
if (missing.length > 0) {
|
|
53
|
-
return errorResult(formatMissingArgsError(name, missing, args,
|
|
76
|
+
return errorResult(formatMissingArgsError(name, missing, args, schema));
|
|
54
77
|
}
|
|
55
78
|
try {
|
|
56
79
|
const result = await tool.handler(args || {});
|
|
@@ -59,7 +82,7 @@ async function main() {
|
|
|
59
82
|
catch (error) {
|
|
60
83
|
// INPUT validation: name the tool, the field and what arrived.
|
|
61
84
|
if (error instanceof PlankaInputError) {
|
|
62
|
-
return errorResult(formatInputError(name, error,
|
|
85
|
+
return errorResult(formatInputError(name, error, schema));
|
|
63
86
|
}
|
|
64
87
|
// A loose ZodError means Planka's RESPONSE did not match the schema.
|
|
65
88
|
// Name it separately so the model does not assume it got the args wrong.
|
|
@@ -68,7 +91,7 @@ async function main() {
|
|
|
68
91
|
}
|
|
69
92
|
// Handle configuration errors specifically
|
|
70
93
|
if (error instanceof PlankaConfigError) {
|
|
71
|
-
return errorResult(`Configuration error: ${error.message}\n\nRequired
|
|
94
|
+
return errorResult(`Configuration error: ${error.message}\n\nRequired: PLANKA_BASE_URL, plus EITHER PLANKA_API_KEY (recommended) OR PLANKA_AGENT_EMAIL + PLANKA_AGENT_PASSWORD.`);
|
|
72
95
|
}
|
|
73
96
|
// Handle other PLANKA errors
|
|
74
97
|
if (error instanceof PlankaError) {
|
|
@@ -85,9 +108,61 @@ async function main() {
|
|
|
85
108
|
// Log startup (to stderr so it doesn't interfere with MCP protocol)
|
|
86
109
|
console.error("PLANKA MCP server started");
|
|
87
110
|
}
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
111
|
+
/**
|
|
112
|
+
* The binary has two jobs. Started by an MCP client it speaks stdio and must
|
|
113
|
+
* never print to stdout; run by a human as `planka-mcp init` it configures that
|
|
114
|
+
* client instead. The subcommand is dispatched before anything MCP is loaded so
|
|
115
|
+
* a missing PLANKA_BASE_URL cannot break the setup command that exists to fix it.
|
|
116
|
+
*/
|
|
117
|
+
const subcommand = process.argv[2];
|
|
118
|
+
if (subcommand === "init") {
|
|
119
|
+
const { runInit } = await import("./cli/init.js");
|
|
120
|
+
const { createInterface } = await import("node:readline/promises");
|
|
121
|
+
const interactive = process.stdin.isTTY && process.stdout.isTTY;
|
|
122
|
+
const rl = interactive
|
|
123
|
+
? createInterface({ input: process.stdin, output: process.stdout })
|
|
124
|
+
: null;
|
|
125
|
+
try {
|
|
126
|
+
const code = await runInit(process.argv.slice(3), {
|
|
127
|
+
// Secrets must not echo: readline has no password mode, so its output
|
|
128
|
+
// writer is muted for the duration of the answer (the same trick the
|
|
129
|
+
// shell installer got from `read -s`).
|
|
130
|
+
ask: rl
|
|
131
|
+
? async (question, secret = false) => {
|
|
132
|
+
if (!secret)
|
|
133
|
+
return (await rl.question(`${question}: `)).trim();
|
|
134
|
+
const iface = rl;
|
|
135
|
+
const previous = iface._writeToOutput;
|
|
136
|
+
iface._writeToOutput = (text) => {
|
|
137
|
+
if (text.includes(question))
|
|
138
|
+
previous.call(iface, text);
|
|
139
|
+
};
|
|
140
|
+
try {
|
|
141
|
+
const answer = await rl.question(`${question}: `);
|
|
142
|
+
process.stdout.write("\n");
|
|
143
|
+
return answer.trim();
|
|
144
|
+
}
|
|
145
|
+
finally {
|
|
146
|
+
iface._writeToOutput = previous;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
: undefined,
|
|
150
|
+
});
|
|
151
|
+
process.exitCode = code;
|
|
152
|
+
}
|
|
153
|
+
catch (error) {
|
|
154
|
+
console.error(`init failed: ${error instanceof Error ? error.message : error}`);
|
|
155
|
+
process.exitCode = 1;
|
|
156
|
+
}
|
|
157
|
+
finally {
|
|
158
|
+
rl?.close();
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
else {
|
|
162
|
+
// Run the server
|
|
163
|
+
main().catch((error) => {
|
|
164
|
+
console.error("Fatal error:", error);
|
|
165
|
+
process.exit(1);
|
|
166
|
+
});
|
|
167
|
+
}
|
|
93
168
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server instructions sent in the `initialize` handshake
|
|
3
|
+
* (`InitializeResult.instructions`).
|
|
4
|
+
*
|
|
5
|
+
* Both runtimes we care about read this field: Claude Code injects it into the
|
|
6
|
+
* session system prompt, Codex CLI uses it as guidance alongside the tool list.
|
|
7
|
+
* It is therefore a FIXED per-session cost, paid on top of `tools/list`.
|
|
8
|
+
*
|
|
9
|
+
* Two constraints drive the shape of the text:
|
|
10
|
+
*
|
|
11
|
+
* 1. The spec says instructions "should not duplicate information already in
|
|
12
|
+
* tool descriptions". So the prose shared by many tools lives here once, and
|
|
13
|
+
* each `description` keeps only what is specific to that tool.
|
|
14
|
+
* 2. Some clients truncate. The first paragraph (< 512 chars) must stand on its
|
|
15
|
+
* own: what the server is, how to open a session, where IDs come from.
|
|
16
|
+
*
|
|
17
|
+
* Budget: 1500-2500 chars, hard ceiling 3000. Anything longer belongs in docs
|
|
18
|
+
* or in an MCP resource, not here. `tests/unit/instructions.test.ts` enforces it.
|
|
19
|
+
*/
|
|
20
|
+
export declare const SERVER_INSTRUCTIONS = "Planka MCP reads and writes a Planka 2.x kanban board. Open every session with planka_board_summary: one call returns each column with its card count and every label. planka_get_board is DEPRECATED \u2014 never call it. Narrow from the summary with planka_find_cards: with a listId it reads one whole column in a single request (nothing clipped), without it it searches the board by text, label or member. planka_get_card for one card. Every ID is a string of digits and is never guessed.\n\nIDs come from planka_get_structure or planka_board_summary. They look alike, so passing a label ID where a list ID belongs answers \"Resource not found\" rather than a type error.\n\nBefore acting on a card, read ALL of its comments: planka_get_comments, or planka_get_card with withComments (get_card returns a digest and NO comments unless asked). The description says how the card was born; the comments say where it stands today, and the last one usually wins. Comments page 50 at a time: trust hasMore and nextBeforeId, not the count in one answer.\n\nReads return digests, not full records: descriptions are off unless you ask (descriptionChars), results are capped (limit, offset), and every scoped read reports total/returned/hasMore/nextOffset so a clipped answer is never mistaken for a complete one. Ask for the detail only once you know which card you want.\n\nText search (query/search) matches card name and description, case- and accent-insensitive. Several tokens are ANDed, all must match. A leading \"/\" makes the rest a regular expression.\n\nResuming work you did not start: planka_board_activity says what moved on the board and who moved it since a given date. Planka logs only card creation, moves, member changes and task completion, so comments and edits leave no trace there.\n\nWrites are one tool per action: planka_create_/update_/delete_ label, list and comment. The planka_manage_* names and planka_add_comment still work but are DEPRECATED aliases.\n\nWrites re-read what they touched and report what actually landed. Trust the verified and finalLabelIds fields of the response, not the arguments you sent; a request that returns without them did not confirm anything.\n\nPlanka answers 404 where it means 403. A \"not found\" on a write, with an ID that read fine a moment ago, is almost always a missing permission for the agent user, not a wrong ID.";
|
|
21
|
+
//# sourceMappingURL=instructions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,80EAgBmJ,CAAC"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server instructions sent in the `initialize` handshake
|
|
3
|
+
* (`InitializeResult.instructions`).
|
|
4
|
+
*
|
|
5
|
+
* Both runtimes we care about read this field: Claude Code injects it into the
|
|
6
|
+
* session system prompt, Codex CLI uses it as guidance alongside the tool list.
|
|
7
|
+
* It is therefore a FIXED per-session cost, paid on top of `tools/list`.
|
|
8
|
+
*
|
|
9
|
+
* Two constraints drive the shape of the text:
|
|
10
|
+
*
|
|
11
|
+
* 1. The spec says instructions "should not duplicate information already in
|
|
12
|
+
* tool descriptions". So the prose shared by many tools lives here once, and
|
|
13
|
+
* each `description` keeps only what is specific to that tool.
|
|
14
|
+
* 2. Some clients truncate. The first paragraph (< 512 chars) must stand on its
|
|
15
|
+
* own: what the server is, how to open a session, where IDs come from.
|
|
16
|
+
*
|
|
17
|
+
* Budget: 1500-2500 chars, hard ceiling 3000. Anything longer belongs in docs
|
|
18
|
+
* or in an MCP resource, not here. `tests/unit/instructions.test.ts` enforces it.
|
|
19
|
+
*/
|
|
20
|
+
export const SERVER_INSTRUCTIONS = `Planka MCP reads and writes a Planka 2.x kanban board. Open every session with planka_board_summary: one call returns each column with its card count and every label. planka_get_board is DEPRECATED — never call it. Narrow from the summary with planka_find_cards: with a listId it reads one whole column in a single request (nothing clipped), without it it searches the board by text, label or member. planka_get_card for one card. Every ID is a string of digits and is never guessed.
|
|
21
|
+
|
|
22
|
+
IDs come from planka_get_structure or planka_board_summary. They look alike, so passing a label ID where a list ID belongs answers "Resource not found" rather than a type error.
|
|
23
|
+
|
|
24
|
+
Before acting on a card, read ALL of its comments: planka_get_comments, or planka_get_card with withComments (get_card returns a digest and NO comments unless asked). The description says how the card was born; the comments say where it stands today, and the last one usually wins. Comments page 50 at a time: trust hasMore and nextBeforeId, not the count in one answer.
|
|
25
|
+
|
|
26
|
+
Reads return digests, not full records: descriptions are off unless you ask (descriptionChars), results are capped (limit, offset), and every scoped read reports total/returned/hasMore/nextOffset so a clipped answer is never mistaken for a complete one. Ask for the detail only once you know which card you want.
|
|
27
|
+
|
|
28
|
+
Text search (query/search) matches card name and description, case- and accent-insensitive. Several tokens are ANDed, all must match. A leading "/" makes the rest a regular expression.
|
|
29
|
+
|
|
30
|
+
Resuming work you did not start: planka_board_activity says what moved on the board and who moved it since a given date. Planka logs only card creation, moves, member changes and task completion, so comments and edits leave no trace there.
|
|
31
|
+
|
|
32
|
+
Writes are one tool per action: planka_create_/update_/delete_ label, list and comment. The planka_manage_* names and planka_add_comment still work but are DEPRECATED aliases.
|
|
33
|
+
|
|
34
|
+
Writes re-read what they touched and report what actually landed. Trust the verified and finalLabelIds fields of the response, not the arguments you sent; a request that returns without them did not confirm anything.
|
|
35
|
+
|
|
36
|
+
Planka answers 404 where it means 403. A "not found" on a write, with an ID that read fine a moment ago, is almost always a missing permission for the agent user, not a wrong ID.`;
|
|
37
|
+
//# sourceMappingURL=instructions.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;mLAgBgJ,CAAC"}
|