plonk-mcp 0.2.4 → 0.3.0

package/README.md

@@ -58,6 +58,7 @@ config to tell two sessions of the same client apart.
 | `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 |
 | `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 |
 | `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

@@ -18,6 +18,7 @@ const USAGE = `plonk — drive the Plonk menu bar app from a shell
   plonk awake off
   plonk awake on [--minutes N] [--until HH:MM] [--pid N]
   plonk awake while <command...>    stay awake until that command exits
+  plonk measure [X Y] [--screen N] [--tolerance N]   measure at that point
   plonk text [--mode region|window|screen] [--path FILE]
   plonk shot [--mode region|window|screen] [--path FILE]
 
@@ -44,6 +45,15 @@ function number(raw, what) {
         fail(`${what} must be a whole number, got "${raw}"`);
     return value;
 }
+/** Points arrive as fractions of a screen, the way every frame in this API
+ * does, so a measurement can be pasted straight back into a layout. */
+function fraction(raw, what) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        fail(`${what} must be a fraction between 0 and 1, got "${raw}"`);
+    }
+    return value;
+}
 /** Prints the reply and exits non-zero when the app refused. */
 function report(result) {
     if ("error" in result) {
@@ -181,6 +191,24 @@ async function main() {
             }));
             break;
         }
+        case "measure": {
+            // With no point named there is nobody to ask but the user, so the ruler
+            // goes on screen and this waits for them.
+            const [x, y] = args;
+            const interactive = x === undefined || y === undefined;
+            report(await call("/ruler/measure", {
+                method: "POST",
+                body: interactive
+                    ? { interactive: true }
+                    : {
+                        screen,
+                        point: { x: fraction(x, "x"), y: fraction(y, "y") },
+                        tolerance: number(flags.tolerance, "--tolerance"),
+                    },
+                timeoutMs: interactive ? 5 * 60_000 : 30_000,
+            }));
+            break;
+        }
         case "text": {
             const result = await call("/shot/text", {
                 method: "POST",

package/dist/factory.js

@@ -7,10 +7,12 @@ 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";
 import { register as registerText } from "./tools/text.js";
+import { register as registerRuler } from "./tools/ruler.js";
 import { register as registerAgents } from "./tools/agents.js";
 import { register as registerUpdate } from "./tools/update.js";
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -21,9 +23,11 @@ export function createPlonkServer() {
     registerLayouts(server);
     registerZones(server);
     registerAwake(server);
+    registerActive(server);
     registerScreenshot(server);
     registerAnnotate(server);
     registerText(server);
+    registerRuler(server);
     registerAgents(server);
     registerUpdate(server);
     return server;

package/dist/tools/active.js

@@ -0,0 +1,22 @@
+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 } })));
+}

package/dist/tools/ruler.js

@@ -0,0 +1,43 @@
+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),
+});
+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'. " +
+        "Read the result honestly: these are two independent runs through one point, not the outline of an element. Inside a plain rectangle they are its width and height; inside a gap they are the gap; on a large flat background they run until something else is in the way, which may be most of the screen. When the exact bounds of a specific element matter, pass 'interactive' and let the user point at it. " +
+        "Three ways to ask. Pass 'point' for the runs through one place. Pass 'from' and 'to' for the straight-line distance between two places, which needs no capture at all. Pass 'interactive' to hand the user the ruler and wait up to five minutes while they measure it themselves. " +
+        "Points are fractions 0..1 of the screen's visible area with origin at TOP-LEFT, the same space apply_layout and save_zone_set use, so {x:0.5,y:0.5} is the middle of the screen. " +
+        "Returns 'points' {x,y,w,h} in screen points (absolute, origin top-left of the primary display) where w is the run across and h the run down, 'pixels' {w,h} in the display's own pixels — twice the points on a Retina screen, which is the difference that matters when checking an asset — 'fraction' {x,y,w,h} of that screen's visible area ready to hand to apply_layout, 'scale', and 'text', the same line Plonk shows the user. A distance also carries 'distance' and 'distance_pixels'. " +
+        "Needs macOS Screen Recording permission, the same as a screenshot; without it the call fails rather than guessing. What is measured is a still taken when the call started, so a screen that is animating measures as it was at that moment.", {
+        point: pointSchema
+            .optional()
+            .describe("Where to measure from, as fractions 0..1 of the screen's visible area, origin TOP-LEFT. {x:0.5,y:0.5} is the middle of the screen"),
+        from: pointSchema.optional().describe("One end of a distance, in the same fractions as 'point'"),
+        to: pointSchema.optional().describe("The other end of a distance, in the same fractions as 'point'"),
+        screen: z
+            .number()
+            .int()
+            .optional()
+            .describe("Monitor index from get_state (0 = primary, the default). Every point is a fraction of this screen"),
+        tolerance: z
+            .number()
+            .int()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe("How different one pixel must be from the pixel beside it, on a scale of 255, to count as an edge. Omit to use the user's setting (10 by default). Lower stops at fainter borders and finds smaller things; raise it for a photograph or video, where every pixel differs a little from the last"),
+        interactive: z
+            .boolean()
+            .optional()
+            .describe("Hand the user the ruler instead of measuring a given point: they hover, drag, click to copy and press Escape, and the last measurement comes back. The one to use when it is their screen and their judgement of what to measure. Waits up to five minutes"),
+    }, async ({ point, from, to, screen, tolerance, interactive }) => text(await call("/ruler/measure", {
+        method: "POST",
+        body: { point, from, to, screen, tolerance, interactive },
+        timeoutMs: interactive ? INTERACTIVE_TIMEOUT_MS : 30_000,
+    })));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.2.4",
+  "version": "0.3.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",
@@ -44,10 +44,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.24.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^18.19.0",
-    "typescript": "^5.5.0"
+    "typescript": "^7.0.2"
   }
 }