plonk-mcp 0.3.4 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 # plonk-mcp
 
 The MCP server for [Plonk](https://github.com/ostapondo/plonk), a macOS menu bar
-app that is ten utilities at once, a window manager among them. It lets an agent
-work the desk: apply layouts across monitors, save and relaunch workspaces, snap
-windows into zones, keep the screen awake, take and annotate screenshots, and
-read text off the screen without uploading a pixel.
+app that is eight utilities at once, a window manager among them. It lets an
+agent work the desk: apply layouts across monitors, save and relaunch
+workspaces, snap windows into zones, keep the screen awake, take and annotate
+screenshots, and read text off the screen without uploading a pixel.
 
 > browser on the left 60%, terminal top right, notes bottom right
 >
@@ -54,12 +54,14 @@ config to tell two sessions of the same client apart.
 | | |
 | --- | --- |
 | `get_state` | Monitors, every open window and where it sits, zone sets, saved workspaces, awake status |
-| `apply_layout` · `snap_window` | Place windows by fraction of a screen, or drop one into a numbered zone |
+| `apply_layout` · `snap_window` | Place windows by fraction of a screen, or drop one into a zone by number or by name |
 | `save_workspace` · `launch_workspace` · `delete_workspace` | Named desktops that reopen their apps and restore every window |
 | `save_zone_set` · `assign_zone_set` · `delete_zone_set` | Snap zones, assigned per monitor |
-| `set_awake` | Keep-awake, optionally time-limited |
-| `set_active` | Stay active, so chat apps do not show you as Away |
+| `set_app_rule` · `clear_app_rule` | Where an app's new windows open: a zone, and optionally a monitor |
+| `set_awake` | Keep the Mac awake, optionally time-limited, optionally also holding your chat status at available |
 | `take_screenshot` · `annotate_screenshot` | Capture, mark up, hand the image back — `mode: "app"` photographs one named window even when it is buried, without raising it |
+| `extract_text` | Read the words off the screen, with a box per line in the same coordinates `annotate_screenshot` draws in |
+| `measure_screen` | How far a point can travel each way before it meets an edge, or the distance between two points, in points and pixels |
 | `select_agent` | Make an agent the active one, optionally the only one allowed to control |
 | `check_for_update` · `install_update` | Ask GitHub for a newer release and install it |
 

package/dist/cli.js

@@ -8,10 +8,11 @@ import { spawn } from "node:child_process";
 import { BASE, call, INTERACTIVE_TIMEOUT_MS, processIdentityHolder } from "./api.js";
 import { options } from "./args.js";
 import { CLI_NAME } from "./messages.js";
+import { PACKAGE_VERSION } from "./version.js";
 const USAGE = `plonk — drive the Plonk menu bar app from a shell
 
   plonk state [--json]              screens, windows, zone sets, workspaces
-  plonk snap <app> <zone>           drop a window into a numbered zone
+  plonk snap <app> <zone>           drop a window into a zone, by number or name
   plonk workspaces                  list saved workspaces
   plonk launch <name> [--screen N]  launch one
   plonk save <name>                 save the desktop as one
@@ -80,6 +81,11 @@ async function summarize() {
     lines.push(`zone sets  ${Object.keys(state.zone_sets).sort().join(", ")}`);
     if (state.excluded_apps?.length)
         lines.push(`excluded   ${state.excluded_apps.join(", ")}`);
+    if (state.app_rules?.length) {
+        const where = (rule) => rule.screen !== undefined ? ` on screen ${rule.screen}` : rule.screen_uuid ? " on a screen that is not attached" : "";
+        const rules = state.app_rules.map((rule) => `${rule.app} -> zone ${rule.zone}${where(rule)}`);
+        lines.push(`rules      ${rules.join(", ")}`);
+    }
     lines.push(`windows   ${state.windows.length}`);
     for (const window of state.windows) {
         lines.push(`  ${window.app}${window.title ? ` — ${window.title}` : ""} [screen ${window.screen}]`);
@@ -118,6 +124,10 @@ async function awakeWhile(argv) {
 }
 async function main() {
     const argv = process.argv.slice(2);
+    if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
+        console.log(PACKAGE_VERSION);
+        return;
+    }
     // Everything after `awake while` belongs to the command being run, flags
     // included, so it is taken verbatim rather than parsed for plonk's own.
     // Otherwise `plonk awake while cargo build --release` builds in debug.
@@ -142,10 +152,13 @@ async function main() {
         case "snap": {
             const [app, zone] = args;
             if (!app || zone === undefined)
-                fail("snap needs an app and a zone number, e.g. plonk snap Safari 1");
+                fail("snap needs an app and a zone, e.g. plonk snap Safari 1 or plonk snap Slack chat");
+            // A whole number travels as one, which is what every app so far
+            // expects; anything else is a name, and the app says so if the set
+            // has neither.
             report(await call("/layout/zone", {
                 method: "POST",
-                body: { app, zone: number(zone, "zone"), screen },
+                body: { app, zone: Number.isInteger(Number(zone)) ? Number(zone) : zone, screen },
             }));
         }
         case "workspaces": {
@@ -226,7 +239,7 @@ async function main() {
 }
 // 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: CLI_NAME, version: "", pid: process.pid };
+processIdentityHolder().identity = { name: CLI_NAME, version: PACKAGE_VERSION, pid: process.pid };
 try {
     await main();
 }

package/dist/factory.js

@@ -7,7 +7,6 @@ import { register as registerState } from "./tools/state.js";
 import { register as registerLayouts } from "./tools/layouts.js";
 import { register as registerWorkspaces } from "./tools/workspaces.js";
 import { register as registerZones } from "./tools/zones.js";
-import { register as registerActive } from "./tools/active.js";
 import { register as registerAwake } from "./tools/awake.js";
 import { register as registerScreenshot } from "./tools/screenshot.js";
 import { register as registerAnnotate } from "./tools/annotate.js";
@@ -23,7 +22,6 @@ export function createPlonkServer() {
     registerLayouts(server);
     registerZones(server);
     registerAwake(server);
-    registerActive(server);
     registerScreenshot(server);
     registerAnnotate(server);
     registerText(server);

package/dist/schemas.js

@@ -18,7 +18,19 @@ export const itemsSchema = z
     frame: frameSchema,
 }))
     .min(1);
-export const zonesSchema = z.array(frameSchema).min(1);
+/** A zone is a frame with, optionally, what it is called. The app decides
+ * what a name may be (it cuts one at 24 characters and refuses a bare
+ * number), the way it decides the gap; measuring it here would count code
+ * units and refuse names the app itself keeps. */
+export const zoneSchema = frameSchema.extend({
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("What the zone is called, e.g. 'chat': drawn under its number, spoken to, and accepted by snap_window instead of the number. Unique within the set"),
+});
+export const zonesSchema = z.array(zoneSchema).min(1);
 export const workspaceItemsSchema = z
     .array(z.object({
     app: z.string().describe("App name as it appears in get_state, e.g. 'Safari'"),

package/dist/tools/awake.js

@@ -1,11 +1,17 @@
 import { z } from "zod";
 import { call, text } from "../api.js";
 export function register(server) {
-    server.tool("set_awake", "Turn keep-awake on or off, so the Mac does not sleep part-way through something. " +
-        "Three ways to end the session, in order of preference: 'pid' ends it the moment that process exits — best by far when something is running, because a build or a render knows when it is finished and nothing is left holding the machine awake afterwards; 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give none of them and it runs until switched off. " +
-        "Behavior also follows the user's settings: keep-awake may pause on battery or engage automatically while charging, so the returned 'status' is what actually happened and 'awake' is whether an assertion is held right now. The menu bar icon glows while it is. " +
+    server.tool("set_awake", "Keep the Mac from sleeping, and optionally keep the user shown as available in chat apps. One session with two levels, called Pulse in the app. " +
+        "'available' picks the level. Left off, Plonk holds a power assertion: the Mac does not sleep, but Slack and Teams still slide the user to Away, because those read the system idle timer and an assertion does not touch it. Turned on, Plonk also resets that idle timer with a Shift keypress every two minutes, which is what keeps a chat status green — and which postpones sleep by itself, so being available always includes being awake. Use it whenever the point is how the user looks to other people rather than whether a job finishes. " +
+        "Three ways to end the session, in order of preference: 'pid' ends it the moment that process exits — best by far when something is running, because a build or a render knows when it is finished and nothing is left holding the machine awake afterwards; 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give none of them and it runs until switched off, or until the user's configured default timeout expires. " +
+        "Switching it by hand overrides the schedule until the schedule itself next changes, so turning it off during scheduled hours lasts until those hours end rather than being undone on the next tick. Sessions Plonk starts on its own — a recurring schedule of hours and weekdays, a list of apps whose being open arms it, or the charger being plugged in — are settings on the Pulse page rather than parameters here; get_state reports all of them under 'awake_details'. " +
+        "Behavior also follows those settings: a session may pause on battery, so the returned 'status' is what actually happened, 'awake' is whether an assertion is held right now, and 'available' is whether a keypress is actually being posted. Those differ from what was asked for when Plonk has no Accessibility permission (nothing can be posted, though the Mac still stays awake) or when the user disallowed running on battery and the Mac is unplugged; neither is an error, since the request was understood. The menu bar cube glows while a session holds. " +
         "A process-bound session is deliberately not restored if Plonk restarts, since the pid would mean nothing by then. Errors come back for a pid that is not running or a time that has already passed.", {
         on: z.boolean(),
+        available: z
+            .boolean()
+            .optional()
+            .describe("Also reset the idle timer, so chat apps go on showing the user as available instead of Away. This is the user's stored level rather than a property of one session: later sessions run at it too, until it is changed again. Omit to leave it as the user set it"),
         minutes: z.number().int().min(1).optional().describe("End the session after this many minutes"),
         until: z
             .string()
@@ -17,5 +23,5 @@ export function register(server) {
             .min(1)
             .optional()
             .describe("End when this process exits. Use the pid of the long job being waited on; get_state lists a pid for every open window"),
-    }, async ({ on, minutes, until, pid }) => text(await call("/awake", { method: "POST", body: { on, minutes, until, pid } })));
+    }, async ({ on, available, minutes, until, pid }) => text(await call("/awake", { method: "POST", body: { on, available, minutes, until, pid } })));
 }

package/dist/tools/layouts.js

@@ -11,9 +11,11 @@ export function register(server) {
         items: itemsSchema.optional(),
     }, async ({ name, items }) => text(await call("/workspaces/save", { method: "POST", body: { name, items } })));
     server.tool("apply_saved_layout", "Launch a saved workspace by name. Legacy name kept for older clients — new integrations should call launch_workspace, which adds a 'screen' option to pull the whole workspace onto one monitor. Opens every app that is not running, waits for its windows, and moves them into the saved positions; macOS cannot open an app straight into a position, so windows appear first and jump into place. Returns per-app success and reports apps that never opened a window. Takes up to a minute for a large workspace.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/launch", { method: "POST", body: { name }, timeoutMs: 90_000 })));
-    server.tool("snap_window", "Drop one window into a numbered zone of the snap-zone set assigned to that monitor. The numbers are the ones Plonk draws on the zones while a window is dragged, so 'the middle zone' of a three-zone set is 2. Zone sets and their per-monitor assignment are in get_state; use apply_layout instead when the user describes a size rather than a zone.", {
+    server.tool("snap_window", "Drop one window into a zone of the snap-zone set assigned to that monitor, by number or by name. The numbers are the ones Plonk draws on the zones while a window is dragged, so 'the middle zone' of a three-zone set is 2; a name is whatever the set calls a zone ('chat'), listed per zone in get_state.zone_sets, matched ignoring case. Fails with the zones that screen does have, names included, when neither matches. Zone sets and their per-monitor assignment are in get_state; use apply_layout instead when the user describes a size rather than a zone.", {
         app: z.string().describe("App name to match, e.g. 'Visual Studio Code'"),
-        zone: z.number().int().min(1).describe("1-based zone number, as shown on the drag overlay"),
+        zone: z
+            .union([z.number().int().min(1), z.string().min(1)])
+            .describe("1-based zone number as shown on the drag overlay, or the zone's name from get_state.zone_sets"),
         title: z.string().optional().describe("Only windows whose title contains this substring"),
         screen: z.number().int().optional().describe("Monitor index; defaults to the one the window is on"),
     }, async (args) => text(await call("/layout/zone", { method: "POST", body: args })));

package/dist/tools/state.js

@@ -1,4 +1,4 @@
 import { call, text } from "../api.js";
 export function register(server) {
-    server.tool("get_state", "Get the current desktop state: all screens/monitors (index, frame, visible area — coordinates have origin at top-left of the primary screen, y grows down), all open windows (app name, title, which screen it is on, absolute frame, and 'fraction' — its position as fractions 0..1 of that screen's visible area), saved layout names, whether keep-awake is on, and 'disabled_features': the modules the user switched off in Plonk (zones, workspaces, shot, ruler, awake, active and so on). A tool belonging to one of those fails with an error saying so until the user switches it back on. ALWAYS call this first before applying a layout, to see which apps are running and how many monitors there are.", {}, async () => text(await call("/state")));
+    server.tool("get_state", "Get the current desktop state: all screens/monitors (index, frame, visible area — coordinates have origin at top-left of the primary screen, y grows down), all open windows (app name, title, which screen it is on, absolute frame, and 'fraction' — its position as fractions 0..1 of that screen's visible area), 'zone_sets' (every set by name, each zone as {x,y,w,h} with a 'name' where the set gives it one), 'screen_zone_sets' (which set each monitor wears), saved layout names, 'app_rules' (where each app's new windows open, see set_app_rule), 'place_new_windows' and 'auto_fill_zones', whether a keep-awake session is holding, and 'disabled_features': the modules the user switched off in Plonk (zones, workspaces, shot, ruler, awake and so on). A tool belonging to one of those fails with an error saying so until the user switches it back on. ALWAYS call this first before applying a layout, to see which apps are running and how many monitors there are.", {}, async () => text(await call("/state")));
 }

package/dist/tools/zones.js

@@ -2,7 +2,7 @@ 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. 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.", {
+    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). A zone may also carry a 'name' ('chat', 'editor'): it is drawn under the zone's number, the user can say it out loud, and snap_window takes it instead of the number; names must be unique within the set, ignoring case, and cannot be a bare number. 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)"),
@@ -18,4 +18,10 @@ export function register(server) {
         name: z.string().optional().describe("Zone set name, or 'edge' for edge snapping; omit for the default set"),
     }, async ({ screen, name }) => text(await call("/zones/assign", { method: "POST", body: { screen, name } })));
     server.tool("delete_zone_set", "Delete a saved zone set by name. Any monitor currently using it falls back to the default set (Halves), so snapping keeps working. Only sets made with save_zone_set can go: the built-ins (Halves, Thirds, 60 / 40, Quarters, Priority) are refused. Deleting is immediate and cannot be undone — the zones would have to be described again. Saved sets and their per-monitor assignments are listed in get_state; use assign_zone_set instead when a monitor should merely stop using a set that others still need.", { name: z.string().describe("Saved zone set name, as shown in get_state") }, async ({ name }) => text(await call("/zones/delete", { method: "POST", body: { name } })));
+    server.tool("set_app_rule", "Make an app's windows open into a numbered zone from now on, so an arrangement holds without anyone dragging: 'Slack always in zone 1 on the second monitor'. 'app' is matched anywhere in the app's name or bundle id, case-insensitively, the way get_state.excluded_apps entries are; a bundle id such as 'com.tinyspeck.slackmacgap' is the safest form. 'zone' is the number Plonk draws on the zone (1-based) in the set assigned to that monitor. 'screen' is a monitor index from get_state and is stored as that display's identity, so it survives a reboot renumbering the screens; omit it and the window stays on whichever screen it opened on. One rule per app: setting it again replaces the old one; a rule that names the app exactly wins over a bare-word rule. Applies to ordinary windows that open after it is set, not to windows already open (use snap_window for those) and not to dialogs or panels. An app on get_state.excluded_apps is left alone even with a rule. A rule beats the habit Plonk keeps of where an app's last window went, and both beat filling an empty zone. Current rules are get_state.app_rules. Fails when 'screen' names a monitor that is not attached or a zone that monitor's set does not have.", {
+        app: z.string().describe("App name or bundle id to match, e.g. 'com.apple.Safari' or 'Safari'"),
+        zone: z.number().int().min(1).describe("1-based zone number, as shown on the drag overlay"),
+        screen: z.number().int().optional().describe("Monitor index from get_state (0 = primary); omit for the screen the window opens on"),
+    }, async ({ app, zone, screen }) => text(await call("/zones/rules", { method: "POST", body: { app, zone, screen } })));
+    server.tool("clear_app_rule", "Remove the rule set for an app with set_app_rule, so its new windows open wherever the app puts them again, or where its last window went when that habit is switched on in Plonk. 'app' is the pattern exactly as get_state.app_rules lists it, ignoring case. Fails when no rule matches; nothing else changes.", { app: z.string().describe("The app pattern as listed in get_state.app_rules") }, async ({ app }) => text(await call("/zones/rules/delete", { method: "POST", body: { app } })));
 }

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,2 @@
+import { readFileSync } from "node:fs";
+export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "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",

package/dist/tools/active.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { call, text } from "../api.js";
-export function register(server) {
-    server.tool("set_active", "Turn stay-active on or off, so chat apps go on showing the user as available instead of Away. " +
-        "Pick this over 'set_awake' by what is being protected: set_awake holds a power assertion and stops the Mac sleeping, which does nothing for a Slack or Teams status; set_active resets the system idle timer by posting a Shift keypress every two minutes, which is what those apps actually read. Resetting the idle timer also postpones sleep, so stay-active implies keep-awake and there is no need to turn both on. " +
-        "Two ways to end the session: 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give neither and it runs until switched off, or until the user's configured default timeout expires. " +
-        "This only starts and ends sessions. The recurring schedule (hours and weekdays) and the list of apps that arm it automatically are settings on the Stay active page, not parameters here; get_state reports both under 'active_details'. " +
-        "Switching it by hand overrides the schedule until the schedule itself next changes, so turning it off during scheduled hours lasts until those hours end rather than being undone on the next tick. " +
-        "Returns 'active', whether a keypress is actually being posted right now, and 'status', what happened in words. Those differ when Plonk has no Accessibility permission (nothing can be posted) or when the user disallowed running on battery and the Mac is unplugged; neither is reported as an error, since the request was understood. An 'until' that has already passed is an error.", {
-        on: z.boolean(),
-        minutes: z
-            .number()
-            .int()
-            .min(1)
-            .optional()
-            .describe("End the session after this many minutes"),
-        until: z
-            .string()
-            .optional()
-            .describe("End at a time of day, e.g. '17:00' (the next such moment — tomorrow if today's has passed), or an ISO-8601 timestamp like '2026-08-08T17:00:00Z'"),
-    }, async ({ on, minutes, until }) => text(await call("/active", { method: "POST", body: { on, minutes, until } })));
-}