plonk-mcp 0.3.0 → 0.3.2

package/dist/api.js

@@ -1,6 +1,8 @@
+import { notRunningMessage } from "./messages.js";
 export const BASE = "http://127.0.0.1:43917";
 const DEFAULT_TIMEOUT_MS = 15_000;
-const NOT_RUNNING = "Plonk menu bar app is not running. Ask the user to launch Plonk.app (its icon should appear in the menu bar).";
+/** Interactive captures and the ruler wait on the user, so they get this budget instead. */
+export const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
 // Stamped on every request so the app can attribute it to a client and, in
 // exclusive mode, gate on it. One mechanism, one shape: the identity always
 // lives in a holder. HTTP runs each request inside its session's holder; stdio
@@ -124,7 +126,7 @@ export async function call(path, options = {}) {
         if (timeout.aborted) {
             return { error: `Plonk did not answer within ${timeoutMs / 1000}s. It may be waiting on a dialog.` };
         }
-        return { error: NOT_RUNNING };
+        return { error: notRunningMessage(agentIdentityName()) };
     }
     const text = await res.text();
     try {

package/dist/cli.js

@@ -5,8 +5,9 @@
 // neither helps a script, a Raycast command or a Makefile. This is that gap:
 // every subcommand is one HTTP call to 127.0.0.1, and nothing here holds state.
 import { spawn } from "node:child_process";
-import { BASE, call, processIdentityHolder } from "./api.js";
+import { BASE, call, INTERACTIVE_TIMEOUT_MS, processIdentityHolder } from "./api.js";
 import { options } from "./args.js";
+import { CLI_NAME } from "./messages.js";
 const USAGE = `plonk — drive the Plonk menu bar app from a shell
 
   plonk state [--json]              screens, windows, zone sets, workspaces
@@ -134,12 +135,10 @@ async function main() {
             return;
         case "ping":
             report(await call("/ping"));
-            break;
         case "state":
             if (flags.json)
                 report(await call("/state"));
             await summarize();
-            break;
         case "snap": {
             const [app, zone] = args;
             if (!app || zone === undefined)
@@ -148,7 +147,6 @@ async function main() {
                 method: "POST",
                 body: { app, zone: number(zone, "zone"), screen },
             }));
-            break;
         }
         case "workspaces": {
             const state = await call("/state");
@@ -165,17 +163,14 @@ async function main() {
                 body: { name: args[0], screen },
                 timeoutMs: 90_000,
             }));
-            break;
         case "save":
             if (!args[0])
                 fail("save needs a name for the workspace");
             report(await call("/workspaces/save", { method: "POST", body: { name: args[0] } }));
-            break;
         case "zones":
             if (!args[0])
                 fail("zones needs a set name, or 'edge' for edge snapping");
             report(await call("/zones/assign", { method: "POST", body: { screen: screen ?? 0, name: args[0] } }));
-            break;
         case "awake": {
             // `while` is handled before flags are parsed; anything else must be on/off.
             if (args[0] !== "on" && args[0] !== "off")
@@ -189,7 +184,6 @@ async function main() {
                     pid: number(flags.pid, "--pid"),
                 },
             }));
-            break;
         }
         case "measure": {
             // With no point named there is nobody to ask but the user, so the ruler
@@ -205,15 +199,14 @@ async function main() {
                         point: { x: fraction(x, "x"), y: fraction(y, "y") },
                         tolerance: number(flags.tolerance, "--tolerance"),
                     },
-                timeoutMs: interactive ? 5 * 60_000 : 30_000,
+                timeoutMs: interactive ? INTERACTIVE_TIMEOUT_MS : 30_000,
             }));
-            break;
         }
         case "text": {
             const result = await call("/shot/text", {
                 method: "POST",
                 body: { mode: flags.mode ?? "region", path: flags.path },
-                timeoutMs: 5 * 60_000,
+                timeoutMs: INTERACTIVE_TIMEOUT_MS,
             });
             if ("error" in result)
                 report(result);
@@ -225,16 +218,15 @@ async function main() {
             report(await call("/shot/capture", {
                 method: "POST",
                 body: { mode: flags.mode ?? "region", path: flags.path },
-                timeoutMs: 5 * 60_000,
+                timeoutMs: INTERACTIVE_TIMEOUT_MS,
             }));
-            break;
         default:
             fail(`unknown command "${command}"\n\n${USAGE}`);
     }
 }
 // Named so the app can attribute the calls, and so "only the active agent
 // controls" can be pointed at the shell like anything else.
-processIdentityHolder().identity = { name: "plonk-cli", version: "", pid: process.pid };
+processIdentityHolder().identity = { name: CLI_NAME, version: "", pid: process.pid };
 try {
     await main();
 }

package/dist/factory.js

@@ -37,7 +37,7 @@ export function createPlonkServer() {
  * "pet-project"). The initialized notification can outrun the initialize
  * handler's bookkeeping in the SDK, leaving clientInfo briefly unset, so this
  * polls instead of trusting the callback's timing. */
-export function watchClientInfo(server, onKnown) {
+function watchClientInfo(server, onKnown) {
     const poll = (attempt = 0) => {
         const client = server.server.getClientVersion();
         if (!client && attempt < 50) {
@@ -49,9 +49,25 @@ export function watchClientInfo(server, onKnown) {
     };
     server.server.oninitialized = () => poll();
 }
+/** Once the client is known, names the holder after it and keeps the app told
+ * about it. Returns a stop function that ends both once they have started. */
+export function bindClient(server, holder, nextPid) {
+    let stop = () => { };
+    watchClientInfo(server, ({ name, version }) => {
+        const identity = { name, version, pid: nextPid() };
+        holder.identity = identity;
+        const stopHello = startHello(identity);
+        const stopInbox = startInboxLoop(server, identity);
+        stop = () => {
+            stopHello();
+            stopInbox();
+        };
+    });
+    return () => stop();
+}
 /** Registers the identity with the app and keeps it marked online with a
  * heartbeat. Returns a stop function for when the session ends. */
-export function startHello(identity) {
+function startHello(identity) {
     const hello = () => call("/agents/hello", {
         method: "POST",
         body: { name: identity.name, version: identity.version, pid: identity.pid },
@@ -70,7 +86,7 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
  * queue, and draining what this client cannot act on would silently throw the
  * user's words away instead of leaving them for a CLI adapter.
  * Returns a stop function; it is a no-op when the loop never started. */
-export function startInboxLoop(server, identity) {
+function startInboxLoop(server, identity) {
     if (!server.server.getClientCapabilities()?.sampling) {
         console.error(`plonk-mcp: ${identity.name} does not support MCP sampling, so Plonk cannot hand it spoken ` +
             `or queued prompts. Configure a CLI adapter for it in Plonk (Settings, AI · MCP) to use voice.`);

package/dist/http.js

@@ -6,7 +6,7 @@ import { createServer } from "node:http";
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { localApiToken, runWithIdentity } from "./api.js";
-import { createPlonkServer, startHello, startInboxLoop, watchClientInfo } from "./factory.js";
+import { bindClient, createPlonkServer } from "./factory.js";
 // The app's registry tells sessions apart by (name, pid). Every HTTP client
 // shares this process, so each session gets a synthetic pid instead.
 let syntheticPid = 100_000 + (process.pid % 1_000) * 100;
@@ -75,19 +75,13 @@ export async function serveHttp(port) {
             }),
         };
         session.transport.onclose = () => {
-            session.stopHello?.();
-            session.stopInbox?.();
+            session.stop?.();
             const sid = session.transport.sessionId;
             if (sid !== undefined)
                 sessions.delete(sid);
         };
         const server = createPlonkServer();
-        watchClientInfo(server, ({ name, version }) => {
-            const identity = { name, version, pid: syntheticPid++ };
-            session.holder.identity = identity;
-            session.stopHello = startHello(identity);
-            session.stopInbox = startInboxLoop(server, identity);
-        });
+        session.stop = bindClient(server, session.holder, () => syntheticPid++);
         await server.connect(session.transport);
         await runWithIdentity(session.holder, () => session.transport.handleRequest(req, res));
     };

package/dist/messages.js

@@ -0,0 +1,14 @@
+// Errors the client composes itself, worded for whoever will read them.
+/** The identity `plonk` registers before its first call, so a refusal can be
+ * addressed to a person at a prompt rather than to a model. */
+export const CLI_NAME = "plonk-cli";
+const NOT_RUNNING_FOR_AGENT = "Plonk menu bar app is not running. Ask the user to launch Plonk.app (its icon should appear in the menu bar).";
+// A person who ran `npm i -g plonk-mcp` first has no reason to know the app is
+// a separate install, so the cask is the useful half of this sentence.
+const NOT_RUNNING_FOR_CLI = "Plonk.app is not running. Launch it (its icon appears in the menu bar), or install it first: brew install --cask ostapondo/plonk/plonk";
+/** The refused-connection message for the client named `agent`. Same cause
+ * either way; the CLI's form tells the reader what to do instead of telling
+ * them to ask themselves. */
+export function notRunningMessage(agent) {
+    return agent === CLI_NAME ? NOT_RUNNING_FOR_CLI : NOT_RUNNING_FOR_AGENT;
+}

package/dist/schemas.js

@@ -1,5 +1,9 @@
 // Shared zod schemas for tool inputs.
 import { z } from "zod";
+export const pointSchema = z.object({
+    x: z.number().min(0).max(1),
+    y: z.number().min(0).max(1),
+});
 export const frameSchema = z.object({
     x: z.number().min(0).max(1),
     y: z.number().min(0).max(1),

package/dist/server.js

@@ -6,7 +6,7 @@
 // instead, for clients that cannot spawn a process — several at once.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { BASE, isAppReachable, processIdentityHolder } from "./api.js";
-import { createPlonkServer, startHello, startInboxLoop, watchClientInfo } from "./factory.js";
+import { bindClient, createPlonkServer } from "./factory.js";
 import { serveHttp } from "./http.js";
 const args = process.argv.slice(2);
 if (args.includes("--http")) {
@@ -19,14 +19,8 @@ if (args.includes("--http")) {
     await serveHttp(port);
 }
 else {
-    const holder = processIdentityHolder();
     const server = createPlonkServer();
-    watchClientInfo(server, ({ name, version }) => {
-        const identity = { name, version, pid: process.pid };
-        holder.identity = identity;
-        startHello(identity);
-        startInboxLoop(server, identity);
-    });
+    bindClient(server, processIdentityHolder(), () => process.pid);
     await server.connect(new StdioServerTransport());
 }
 // stdout carries the stdio protocol, so this goes to stderr. Not fatal: the

package/dist/tools/annotate.js

@@ -1,9 +1,6 @@
 import { z } from "zod";
 import { call, text } from "../api.js";
-const pointSchema = z.object({
-    x: z.number().min(0).max(1),
-    y: z.number().min(0).max(1),
-});
+import { pointSchema } from "../schemas.js";
 export function register(server) {
     server.tool("annotate_screenshot", "Draw on a screenshot you already took, then copy it to the clipboard and show it to the user. Call take_screenshot first and LOOK at the image: you cannot know where anything is until you have seen it. Points are fractions 0..1 of the image, origin TOP-LEFT, so a rectangle around a left sidebar that is a seventh of the width and starts under the title bar is [{x:0,y:0.05},{x:0.14,y:1}]. Rectangle and ellipse take two opposite corners, arrow takes start then tip, pen and highlight take a run of points. Returns the marked image so you can check what you drew.", {
         path: z.string().describe("Path returned by take_screenshot"),

package/dist/tools/ruler.js

@@ -1,11 +1,6 @@
 import { z } from "zod";
-import { call, text } from "../api.js";
-// The interactive mode hands the user a crosshair and waits for them.
-const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
-const pointSchema = z.object({
-    x: z.number().min(0).max(1),
-    y: z.number().min(0).max(1),
-});
+import { call, INTERACTIVE_TIMEOUT_MS, text } from "../api.js";
+import { pointSchema } from "../schemas.js";
 export function register(server) {
     server.tool("measure_screen", "Measure the screen in points and pixels, without taking a picture of it. Plonk photographs the screen once and walks out from the given point in all four directions until one pixel is unlike the one before it, which is where an edge is. What comes back is how far the point could travel each way: the run across and the run down. " +
         "Prefer this over take_screenshot whenever the answer is a number: how wide that sidebar is, how tall that row is, how big the gap between two things is, is that tap target 44 points. An image costs far more tokens and still has to be eyeballed. Use extract_text when the answer is words, and take_screenshot when it is 'what does this look like'. " +

package/dist/tools/screenshot.js

@@ -1,9 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { z } from "zod";
-import { call, text } from "../api.js";
+import { call, INTERACTIVE_TIMEOUT_MS, text } from "../api.js";
 // The interactive modes hand the user a crosshair and wait for them.
 const INTERACTIVE_MODES = new Set(["region", "window"]);
-const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
 // Refuse to inline anything larger; a full retina desktop is easily 10 MB,
 // which is dead weight in the conversation.
 const MAX_INLINE_BYTES = 4 << 20;
@@ -44,7 +43,7 @@ export function register(server) {
             body: { mode: wanted, app, title_contains, annotate, path, clipboard, preview: include_image !== false },
             timeoutMs: INTERACTIVE_MODES.has(wanted) ? INTERACTIVE_TIMEOUT_MS : undefined,
         });
-        const savedPath = "path" in result && typeof result.path === "string" ? result.path : undefined;
+        const savedPath = "path" in result ? result.path : undefined;
         if (!savedPath || include_image === false)
             return text(result);
         const preview = "preview_path" in result && typeof result.preview_path === "string"

package/dist/tools/text.js

@@ -1,7 +1,5 @@
 import { z } from "zod";
-import { call, text } from "../api.js";
-// The interactive mode hands the user a crosshair and waits for them.
-const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
+import { call, INTERACTIVE_TIMEOUT_MS, text } from "../api.js";
 export function register(server) {
     server.tool("extract_text", "Read the words off the screen, or off a saved image, and return them as text. Recognition runs on the Mac itself and nothing is uploaded. " +
         "Prefer this over take_screenshot whenever the answer is words rather than a picture — an error dialog, a log, a terminal, a table, text baked into an image or a paused video, a PDF page in a viewer that will not let text be selected. It costs a fraction of the tokens an image does and does not depend on reading pixels correctly. " +

package/dist/tools/workspaces.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import { call, text } from "../api.js";
 import { workspaceItemsSchema } from "../schemas.js";
-/// Launching waits for every app to open a window, which the app gives up on
-/// after 20 seconds per app.
+// Launching waits for every app to open a window, which the app gives up on
+// after 20 seconds per app.
 const LAUNCH_TIMEOUT_MS = 90_000;
 export function register(server) {
     server.tool("save_workspace", "Save a workspace: the apps of a desktop setup, where each window goes, and what each app should open. Pass 'items' to describe the arrangement, or omit them to snapshot the windows exactly as they are on screen right now. Saving over an existing name replaces it. Saved workspaces are listed in get_state, with their full contents.", {

package/dist/tools/zones.js

@@ -2,11 +2,17 @@ import { z } from "zod";
 import { call, text } from "../api.js";
 import { zonesSchema } from "../schemas.js";
 export function register(server) {
-    server.tool("save_zone_set", "Create or replace a named zone set used for drag snapping. Zones are rectangles {x,y,w,h} as fractions 0..1 of a screen's visible area, origin TOP-LEFT; each zone must stay inside the screen, but zones may overlap each other (the smallest one under the cursor wins). Pass 'screen' to also assign the set to that monitor so it becomes active immediately. Built-in sets already exist: Halves, Thirds, 60 / 40, Quarters, Priority.", {
+    server.tool("save_zone_set", "Create or replace a named zone set used for drag snapping. Zones are rectangles {x,y,w,h} as fractions 0..1 of a screen's visible area, origin TOP-LEFT; each zone must stay inside the screen, but zones may overlap each other (the smallest one under the cursor wins). Pass 'screen' to also assign the set to that monitor so it becomes active immediately. Pass 'gap' to give this set its own spacing around windows in points, or null to make it follow the default gap again; omitting it keeps whatever the set had. Built-in sets already exist: Halves, Thirds, 60 / 40, Quarters, Priority.", {
         name: z.string().describe("Zone set name, e.g. 'coding'"),
         zones: zonesSchema,
         screen: z.number().int().optional().describe("Monitor index to assign this set to (0 = primary)"),
-    }, async ({ name, zones, screen }) => text(await call("/zones/save", { method: "POST", body: { name, zones, screen } })));
+        gap: z
+            .number()
+            .min(0)
+            .nullable()
+            .optional()
+            .describe("This set's own gap in points; null follows the default gap (get_state.zone_gap); omit to leave unchanged"),
+    }, async ({ name, zones, screen, gap }) => text(await call("/zones/save", { method: "POST", body: { name, zones, screen, gap } })));
     server.tool("assign_zone_set", "Assign a zone set (built-in or saved) to one monitor, so dragging a window there snaps to that set's zones. Each monitor keeps its own assignment; assigning replaces whatever that monitor used before and takes effect on the next drag. Omit 'name' to restore the default set (Halves); pass 'edge' for plain edge snapping instead of zones. Available set names and current per-monitor assignments are in get_state.", {
         screen: z.number().int().describe("Monitor index (0 = primary)"),
         name: z.string().optional().describe("Zone set name, or 'edge' for edge snapping; omit for the default set"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "mcpName": "io.github.ostapondo/plonk",
   "description": "MCP server for Plonk, a macOS window manager: zones you draw yourself, workspaces, keep-awake, screenshots and on-device OCR, as tools an agent can call.",
   "type": "module",