@thehammer/danx-dashboard-mcp 0.1.314 → 0.1.315

package/README.md

@@ -51,6 +51,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
 | `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Shown to a key holding `cards.edit` (DX-4523); a dispatch profile still receives it only when its catalog selection names it (`slack-agent` and `work`, DX-4386, through `extraTools`). A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
 | `design_publish` | `{target, note, dir, card_id, design_no | design_title}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of one of an existing card's designs, or as a new design on it (DX-4077, DX-5164, DX-5193): a card holds several designs, so pass exactly one of `design_no` (add a revision to that design, `POST /api/issues/<card>/designs/<no>/revisions`) or `design_title` (start a new design, `POST /api/issues/<card>/designs`; the title is fixed for good), both-or-neither is refused before anything is built; the answer carries `{card_id, design_no, revision_no, dashboard_url, local_html_path, screenshot}`. `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), in a short-lived `node` child process that exits when the build ends, so the server never holds the design's worktree files open and no esbuild outlives the publish (DX-4727), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). `card_id` is required and names an existing card (any but an Epic or Feature); the tool never creates a card, and a refused revision comes back verbatim with the `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
+| `plugin_publish` | `{dir, plugin, note, name?}` — builds a card-type plugin project with its own `npm run build` in a short-lived child process, archives its source (`source.tar.gz`: git-tracked plus untracked-unignored files, else what the top-level `.gitignore` leaves, minus `node_modules`, `.git`, `dist`; never `.env*`; a lockfile is required) and uploads both as a new revision of the plugin `plugin` (created on the first publish), `POST /api/plugins/<id>/revisions` (DX-5237). The build, archive and upload are `@danxbot/plugin-sdk/publish`, the code `danx-plugin publish` runs too. The answer carries `{plugin, plugin_id, revision_id, revision_no, approval_url, screenshot}`; `approval_url` is Settings > Plugins, where a team admin approves the revision. A 1280x800 screenshot of the project's `preview.html` is taken when it has one and Playwright resolves from the project or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). A refused upload comes back verbatim with the `step` refused. Shown to a key holding `plugins.publish`; opt-in like `design_publish`. |
 | `request_permission` | `{permissions, reason}` — asks a person to grant this key ONE MORE permission (see "Asking for one more permission" above). Answers at once with the approval URL and confirm code; the grant is picked up in the background. |
 
 There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.

package/dist/index.js

@@ -105,6 +105,7 @@ import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
 import { designPublish } from "./design-publish.js";
+import { pluginPublish } from "./plugin-publish.js";
 import { boundedResultText } from "./result-limit.js";
 import { bodyValueSchema, queryValueSchema } from "./types.js";
 import { termsAcceptanceCallHalt, termsHaltFor } from "./terms-halt.js";
@@ -671,6 +672,20 @@ strictTool("design_publish", "Build a design against this repo's REAL components
     design_no: z.number().int().positive().optional().describe("Add a revision to this existing design of the card (its `designs` relation). Not with `design_title`."),
     design_title: z.string().min(1).optional().describe("Start a NEW design on the card with this title, fixed for good. Not with `design_no`."),
 }, async (args) => guardedJson(() => designPublish(client, args, { baseUrl: config.baseUrl, cwd: process.cwd() })));
+// ---------------- plugin_publish (DX-5237, parent DX-4679) ----------------
+//
+// Agent-specific like design_publish: it builds in the agent's OWN checkout (`npm run build` in a short-lived child process) and uploads the
+// result, which the dashboard cannot do. The build, archive and upload are `@danxbot/plugin-sdk/publish`, shared with the `danx-plugin`
+// CLI; the screenshot is this tool's alone. Opt-in for the same reason as design_publish (`tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`).
+strictTool("plugin_publish", "Build a card-type plugin project (Vite, `danxPlugin()` from `@danxbot/plugin-sdk/vite`, a lockfile) with its own `npm run build` and publish it as a new revision of the team's plugin " +
+    "`plugin` (a new key creates it): uploads `dist/`, the source `.tar.gz` and a screenshot of the project's `preview.html` when it has one. " +
+    "Returns `{ok: true, status, body: {plugin, plugin_id, revision_id, revision_no, approval_url, screenshot}}`: `approval_url` is Settings > Plugins, where a team admin approves the revision; you cannot. " +
+    "`screenshot` is `captured` or `none: <reason>` (the publish still succeeds). A build error throws with the build's output; a refused upload comes back verbatim as `{ok: false, status, body, plugin, step}`.", {
+    dir: z.string().min(1).describe("The project directory: absolute, or relative to this server's cwd."),
+    plugin: z.string().min(1).describe("The plugin's key: lowercase letters, digits, - and _, at most 64."),
+    note: z.string().min(1).describe("What this revision changes, shown to the approver."),
+    name: z.string().min(1).optional().describe("Display name for a plugin this call creates; default: the key."),
+}, async (args) => guardedJson(() => pluginPublish(client, args, { baseUrl: config.baseUrl, cwd: process.cwd() })));
 // ---------------- request_permission (DX-4434, parent DX-4432) ----------------
 strictTool("request_permission", "Ask a person to grant this key ONE MORE permission. Call it when a call was refused `403 forbidden` naming a " +
     "`permission`, or when you know you need one more. It returns AT ONCE with `{state, approvalUrl, confirmCode, " +

package/dist/plugin-publish.js

@@ -0,0 +1,55 @@
+/**
+ * DX-5237 (DX-4679 section 6) - the `plugin_publish` flow: build a card-type plugin project with its own `npm run build`, archive its source,
+ * take a screenshot, and upload all of it as a revision of one of the team's plugins (created on the first publish).
+ *
+ * The build, the archive and the upload are `@danxbot/plugin-sdk/publish`, the same code the `danx-plugin publish` CLI runs; this module adds
+ * what only an agent's tool has: the dashboard client it already holds (its credential, trace and session headers) as the transport, and the
+ * screenshot. The screenshot machinery is `design-screenshot.ts`, for the one page a plugin can show without the app around it: the project's
+ * optional `preview.html` (a plugin's own bundle imports the app's React and kit, so it cannot render alone). No preview page, no browser, or a
+ * failed capture publishes WITHOUT a screenshot and says why in the result (`none: <reason>`), the same stated degraded mode as `design_publish`.
+ *
+ * ORDER, so a failure leaves as little behind as it can: the arguments (a blank note is refused here, before the build), then the build (a failed build uploads nothing), the archive, the
+ * screenshot, and only then the upload. The dashboard is the only validator; its refusal comes back verbatim with the step it refused.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { archiveSource, assertNote, buildPlugin, uploadRevision, withScreenshot } from "@danxbot/plugin-sdk/publish";
+import { captureScreenshot } from "./design-screenshot.js";
+/** The page in a plugin project's root that is screenshotted at publish. */
+export const PREVIEW_FILE = "preview.html";
+/** The agent's authenticated dashboard client as the publish flow's transport. */
+function clientTransport(client) {
+    return { request: ({ method, path: route, query, body }) => client.request({ method, path: route, basePath: "", query, body }) };
+}
+async function readPreview(projectDir) {
+    try {
+        return await readFile(path.join(projectDir, PREVIEW_FILE), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function pluginPublish(client, args, deps) {
+    assertNote(args.note);
+    const projectDir = path.resolve(deps.cwd, args.dir);
+    const built = await buildPlugin(projectDir);
+    const source = await archiveSource(projectDir);
+    const preview = await readPreview(projectDir);
+    const shot = preview === null
+        ? { png_base64: null, screenshot: `none: the project has no ${PREVIEW_FILE}` }
+        : await captureScreenshot(preview, { rootAbs: projectDir, cwd: deps.cwd });
+    const toUpload = shot.png_base64 === null ? built : withScreenshot(built, Buffer.from(shot.png_base64, "base64"));
+    const result = await uploadRevision(clientTransport(client), {
+        plugin: args.plugin,
+        name: args.name,
+        note: args.note,
+        built: toUpload,
+        source,
+        dashboardUrl: deps.baseUrl,
+    });
+    if (!result.ok)
+        return { ok: false, status: result.status, body: result.body, plugin: args.plugin, step: result.step };
+    return { ok: true, status: result.status, body: { ...result.body, screenshot: shot.screenshot } };
+}

package/dist/tool-access.js

@@ -46,6 +46,10 @@ export const TOOL_ACCESS = {
     // reads on the way (`GET /api/boards/:id`, `GET /api/repos/:id`, `GET /api/issues/:id`) and the card it creates are separate
     // checks on the dashboard whose refusals come back verbatim.
     design_publish: needs("cards.edit"),
+    // DX-5237 - builds in the agent's own checkout, then `GET /api/plugins` (to find the plugin by key), `POST /api/plugins` (a new key) and
+    // `POST /api/plugins/:id/revisions`; both writes are `plugins.publish`, which the default agent role holds. The lookup is a read the key's
+    // role already has (`boards.view`); a refusal of any step comes back verbatim.
+    plugin_publish: needs("plugins.publish"),
     // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
     // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
     // DX-4667 - not operator-session-only: an orchestrator's dispatch calls it too, through a background waiter sub-agent that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.314",
+  "version": "0.1.315",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@danxbot/plugin-sdk": "0.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@thehammer/danx-session-telemetry": "0.1.52",
     "zod": "^3.25.76"