plonk-mcp 0.0.1

package/dist/api.js

@@ -0,0 +1,42 @@
+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).";
+export async function call(path, options = {}) {
+    const { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    let res;
+    try {
+        res = await fetch(BASE + path, {
+            method,
+            headers: { "content-type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal: timeout,
+        });
+    }
+    catch (err) {
+        if (timeout.aborted) {
+            return { error: `Plonk did not answer within ${timeoutMs / 1000}s. It may be waiting on a dialog.` };
+        }
+        return { error: NOT_RUNNING };
+    }
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: `Plonk returned ${res.status} with an unexpected body: ${text.slice(0, 200)}` };
+    }
+}
+/**
+ * Whether the app is answering. Several servers may run at once — one per MCP
+ * client — but all of them are useless without the app behind the port.
+ */
+export async function isAppReachable(timeoutMs = 2_000) {
+    return !("error" in (await call("/ping", { timeoutMs })));
+}
+// An `error` key means the app refused or was unreachable; flagging it stops
+// the model from reading the failure as a successful call.
+export const text = (obj) => ({
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+    ...("error" in obj ? { isError: true } : {}),
+});

package/dist/schemas.js

@@ -0,0 +1,49 @@
+// Shared zod schemas for tool inputs.
+import { z } from "zod";
+export const frameSchema = z.object({
+    x: z.number().min(0).max(1),
+    y: z.number().min(0).max(1),
+    w: z.number().min(0).max(1),
+    h: z.number().min(0).max(1),
+});
+export const itemsSchema = z
+    .array(z.object({
+    app: z.string().describe("App name to match, e.g. 'Safari', 'Visual Studio Code'"),
+    title: z.string().optional().describe("Only windows whose title contains this substring"),
+    screen: z.number().int().optional().describe("Monitor index from get_state (0 = primary)"),
+    frame: frameSchema,
+}))
+    .min(1);
+export const zonesSchema = z.array(frameSchema).min(1);
+export const workspaceItemsSchema = z
+    .array(z.object({
+    app: z.string().describe("App name as it appears in get_state, e.g. 'Safari'"),
+    bundle_id: z
+        .string()
+        .optional()
+        .describe("Bundle identifier, e.g. 'com.apple.Safari'. Required to launch an app that is not running"),
+    bundle_path: z.string().optional().describe("Path to the .app, from get_state"),
+    title: z.string().optional().describe("Prefer windows whose title contains this substring"),
+    window_index: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Which window of that app, when the workspace holds several of them"),
+    screen: z.number().int().optional().describe("Monitor index from get_state (0 = primary)"),
+    screen_uuid: z
+        .string()
+        .optional()
+        .describe("Display UUID from a saved workspace; survives monitors being unplugged, unlike the index"),
+    frame: frameSchema,
+    minimized: z.boolean().optional().describe("Minimize the window once it is in place"),
+    urls: z
+        .array(z.string())
+        .optional()
+        .describe("Files, folders or URLs this app opens when the workspace launches it, e.g. a project folder for an editor or a set of tabs for a browser"),
+    args: z
+        .array(z.string())
+        .optional()
+        .describe("Launch arguments. Many Mac apps ignore these; prefer 'urls'"),
+}))
+    .min(1);

package/dist/server.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Plonk MCP server — bridges AI agents to the Plonk menu bar app (localhost HTTP).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BASE, isAppReachable } from "./api.js";
+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 registerAwake } from "./tools/awake.js";
+import { register as registerScreenshot } from "./tools/screenshot.js";
+import { register as registerAnnotate } from "./tools/annotate.js";
+const server = new McpServer({ name: "plonk", version: "1.0.0" });
+registerState(server);
+registerWorkspaces(server);
+registerLayouts(server);
+registerZones(server);
+registerAwake(server);
+registerScreenshot(server);
+registerAnnotate(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// stdout carries the protocol, so this goes to stderr. Not fatal: the app may
+// still be starting, and every tool reports the same thing on its own.
+if (!(await isAppReachable())) {
+    console.error(`plonk-mcp: nothing is answering on ${BASE} — launch Plonk.app or its tools will fail.`);
+}

package/dist/tools/annotate.js

@@ -0,0 +1,27 @@
+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),
+});
+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"),
+        marks: z
+            .array(z.object({
+            kind: z.enum(["rectangle", "ellipse", "arrow", "pen", "highlight"]),
+            points: z.array(pointSchema).min(2),
+            color: z
+                .enum(["red", "orange", "yellow", "green", "blue", "purple", "black", "white"])
+                .optional()
+                .describe("Defaults to red"),
+            width: z
+                .number()
+                .optional()
+                .describe("Stroke width as a fraction of image width; defaults to 0.004"),
+        }))
+            .min(1),
+        output: z.string().optional().describe("Where to write it; defaults to the source name plus ' marked'"),
+        clipboard: z.boolean().optional().describe("Copy the result to the clipboard (default true)"),
+    }, async (args) => text(await call("/shot/annotate", { method: "POST", body: args })));
+}

package/dist/tools/awake.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { call, text } from "../api.js";
+export function register(server) {
+    server.tool("set_awake", "Turn keep-awake on or off. Optional 'minutes' limits the session (it ends automatically). Behavior also follows the user's settings: keep-awake may pause on battery or engage automatically while charging; the returned 'status' explains the current state. The menu bar icon glows while active.", {
+        on: z.boolean(),
+        minutes: z.number().int().min(1).optional().describe("Auto-off after this many minutes"),
+    }, async ({ on, minutes }) => text(await call("/awake", { method: "POST", body: { on, minutes } })));
+}

package/dist/tools/layouts.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { call, text } from "../api.js";
+import { itemsSchema } from "../schemas.js";
+export function register(server) {
+    server.tool("apply_layout", "Move and resize windows to build a layout. Each item places one window: 'app' is the app name (fuzzy matched), optional 'title' filters windows of that app by title substring, optional 'screen' is the monitor index from get_state (each monitor can get its own layout — just send items with different 'screen' values; defaults to the screen the window is currently on), 'frame' is {x,y,w,h} as fractions 0..1 of that screen's visible area with origin at TOP-LEFT (left half = {x:0,y:0,w:0.5,h:1}; bottom-right quarter = {x:0.5,y:0.5,w:0.5,h:0.5}; centered 60% = {x:0.2,y:0.15,w:0.6,h:0.7}). Windows are unminimized if needed. Returns per-item success/errors.", { items: itemsSchema }, async ({ items }) => text(await call("/layout", { method: "POST", body: { items } })));
+    // Saved layouts became workspaces, which also know how to launch their apps.
+    // These two stay so older clients keep working; prefer save_workspace and
+    // launch_workspace, which can carry an app's bundle id and what it opens.
+    server.tool("save_layout", "Deprecated alias of save_workspace. Saves the named arrangement as a workspace; omit 'items' to snapshot what is on screen right now.", {
+        name: z.string().describe("Workspace name, e.g. 'work', 'focus'"),
+        items: itemsSchema.optional(),
+    }, async ({ name, items }) => text(await call("/workspaces/save", { method: "POST", body: { name, items } })));
+    server.tool("apply_saved_layout", "Deprecated alias of launch_workspace. Launches the saved workspace of that name, opening any app that is not running.", { 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.", {
+        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"),
+        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 })));
+    server.tool("delete_layout", "Deprecated alias of delete_workspace. Deletes the saved workspace of that name.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/delete", { method: "POST", body: { name } })));
+}

package/dist/tools/screenshot.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import { call, text } from "../api.js";
+// The interactive modes hand the user a crosshair and wait for them.
+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;
+export function register(server) {
+    server.tool("take_screenshot", "Capture the screen and return the image so it can be looked at. mode 'screen' captures everything (no user interaction), 'region' and 'window' hand the user the native crosshair/window picker and wait for them. Set annotate=true to open Plonk's drawing editor on the capture instead of returning it — use that when the user wants to mark the shot up themselves. Optional 'path' writes to an explicit file, otherwise the configured screenshot folder is used; 'clipboard' overrides the configured copy-to-clipboard behavior. The returned image is scaled down for legibility; the file at 'path' keeps full resolution. To draw on the result, pass that 'path' to annotate_screenshot.", {
+        mode: z.enum(["screen", "region", "window"]).default("screen"),
+        annotate: z.boolean().optional().describe("Open the annotation editor instead of returning the image"),
+        path: z.string().optional().describe("Explicit output file path (.png)"),
+        clipboard: z.boolean().optional().describe("Also copy the capture to the clipboard"),
+        include_image: z
+            .boolean()
+            .optional()
+            .describe("Return the image content itself, so it can be inspected (default true)"),
+    }, async ({ mode, annotate, path, clipboard, include_image }) => {
+        const result = await call("/shot/capture", {
+            method: "POST",
+            body: { mode, annotate, path, clipboard, preview: include_image !== false },
+            timeoutMs: mode === "screen" ? undefined : INTERACTIVE_TIMEOUT_MS,
+        });
+        const savedPath = "path" in result && typeof result.path === "string" ? result.path : undefined;
+        if (!savedPath || include_image === false)
+            return text(result);
+        const preview = "preview_path" in result && typeof result.preview_path === "string"
+            ? result.preview_path
+            : undefined;
+        const imagePath = preview ?? savedPath;
+        try {
+            const data = await readFile(imagePath);
+            if (data.byteLength > MAX_INLINE_BYTES) {
+                return text({
+                    ...result,
+                    note: `image is ${Math.round(data.byteLength / 1024)} KB, too large to inline — read it from 'path' if needed`,
+                });
+            }
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                    { type: "image", data: data.toString("base64"), mimeType: "image/png" },
+                ],
+            };
+        }
+        catch {
+            return text({ ...result, warning: `saved but could not be read back from ${imagePath}` });
+        }
+    });
+}

package/dist/tools/state.js

@@ -0,0 +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, and whether keep-awake is 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/workspaces.js

@@ -0,0 +1,29 @@
+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.
+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.", {
+        name: z.string().describe("Workspace name, e.g. 'work', 'writing'"),
+        items: workspaceItemsSchema.optional(),
+        move_existing: z
+            .boolean()
+            .optional()
+            .describe("When true (the default), an app that is already running has its windows moved into place. When false, running apps are left alone and only missing apps are launched."),
+    }, async ({ name, items, move_existing }) => text(await call("/workspaces/save", { method: "POST", body: { name, items, move_existing } })));
+    server.tool("launch_workspace", "Launch a saved workspace: opens every app that is not running, waits for its windows, and moves them into the saved positions. Each window returns to the monitor it was captured on, so a workspace spanning several displays comes back spanning them. 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(),
+        screen: z
+            .number()
+            .int()
+            .optional()
+            .describe("Pull the whole workspace onto this monitor instead of the ones it was captured on. Use when a display is no longer attached, or to move a setup to another screen."),
+    }, async ({ name, screen }) => text(await call("/workspaces/launch", {
+        method: "POST",
+        body: { name, screen },
+        timeoutMs: LAUNCH_TIMEOUT_MS,
+    })));
+    server.tool("delete_workspace", "Delete a saved workspace by name. Use this to clean up workspaces you created that are no longer wanted.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/delete", { method: "POST", body: { name } })));
+}

package/dist/tools/zones.js

@@ -0,0 +1,15 @@
+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.", {
+        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 } })));
+    server.tool("assign_zone_set", "Assign a zone set (built-in or saved) to a monitor. Omit 'name' to restore the default set (Halves); pass 'edge' for edge snapping instead of zones. Available set names and current 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"),
+    }, async ({ screen, name }) => text(await call("/zones/assign", { method: "POST", body: { screen, name } })));
+    server.tool("delete_zone_set", "Delete a saved zone set. Monitors using it fall back to the default set. Built-in sets cannot be deleted.", { name: z.string() }, async ({ name }) => text(await call("/zones/delete", { method: "POST", body: { name } })));
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "plonk-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Plonk — the Mac window manager your AI agent can drive. Layouts, workspaces, snap zones, keep-awake and screenshots.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ostapondo/plonk.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/ostapondo/plonk#readme",
+  "bugs": "https://github.com/ostapondo/plonk/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "macos",
+    "window-manager",
+    "workspaces",
+    "screenshots"
+  ],
+  "engines": { "node": ">=18" },
+  "files": ["dist"],
+  "bin": { "plonk-mcp": "dist/server.js" },
+  "main": "dist/server.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "typescript": "^5.5.0"
+  }
+}