plonk-mcp 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,74 @@
+# plonk-mcp
+
+The MCP server for [Plonk](https://github.com/ostapondo/plonk), a macOS menu bar
+window manager. It lets an agent arrange your desktop: apply layouts across
+monitors, save and relaunch workspaces, snap windows into zones, keep the screen
+awake, and take and annotate screenshots.
+
+> browser on the left 60%, terminal top right, notes bottom right
+>
+> save that as a workspace called "review"
+>
+> screenshot the screen and tell me what looks off
+
+## This package is only half of it
+
+`plonk-mcp` is a thin bridge. The app does the work, and without it every tool
+call returns "Plonk menu bar app is not running". Install it first — macOS 13+:
+
+```sh
+brew install --cask ostapondo/plonk/plonk
+```
+
+Launch it, grant Accessibility when asked, and relaunch once so macOS picks the
+grant up. Screen Recording is asked for separately, the first time you capture.
+
+## Then point an agent at it
+
+Node 18+.
+
+```sh
+claude mcp add plonk -- npx -y plonk-mcp   # Claude Code
+codex mcp add plonk -- npx -y plonk-mcp    # Codex CLI
+```
+
+Any MCP client works the same way — give it `npx -y plonk-mcp` as a stdio
+server. One-pagers for
+[Cursor](https://github.com/ostapondo/plonk/blob/main/docs/clients/cursor.md),
+[Zed](https://github.com/ostapondo/plonk/blob/main/docs/clients/zed.md) and
+[Cline](https://github.com/ostapondo/plonk/blob/main/docs/clients/cline.md).
+
+A client that cannot spawn a process connects over HTTP instead:
+`npx -y plonk-mcp --http` serves Streamable HTTP at
+`http://127.0.0.1:43918/mcp` (loopback only, `--port` to change).
+
+Several clients may be connected at once. Set `PLONK_AGENT_NAME` in a client's
+config to tell two sessions of the same client apart.
+
+## Tools
+
+| | |
+| --- | --- |
+| `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 |
+| `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 |
+| `take_screenshot` · `annotate_screenshot` | Capture, mark up, hand the image back |
+| `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 |
+
+`save_layout`, `apply_saved_layout` and `delete_layout` are older names kept for
+compatibility; they map onto the workspace tools.
+
+Frames are fractions `0..1` of a monitor's visible area with the origin at the
+top left, so the left 60% is `{x: 0, y: 0, w: 0.6, h: 1}`.
+
+## Where things run
+
+The server talks to the app over loopback HTTP on `127.0.0.1:43917` and nowhere
+else. No account, no cloud, no telemetry. It depends only on the official MCP
+SDK and zod.
+
+MIT. Source, screenshots and the rest of the documentation are in the
+[repository](https://github.com/ostapondo/plonk).

package/dist/api.js

@@ -2,19 +2,38 @@ 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).";
 // Stamped on every request so the app can attribute it to a client and, in
-// exclusive mode, gate on it. Set once the MCP handshake reveals who we serve.
-let agentHeaders = {};
-let identityName = "";
-export function setAgentIdentity(name, version) {
-    identityName = name;
-    agentHeaders = {
-        "x-plonk-agent": version ? `${name}/${version}` : name,
-        "x-plonk-agent-pid": String(process.pid),
-    };
+// 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
+// fills the process-wide one, because process.stdin exists before any context
+// we could enter and its callbacks never inherit one. HTTP never fills that
+// holder, so a lost context there means no identity — an unidentified client
+// the app can reject — rather than another session's name.
+import { AsyncLocalStorage } from "node:async_hooks";
+const identityStore = new AsyncLocalStorage();
+const processHolder = {};
+/** Run fn with a per-session identity; every call() inside sees it. */
+export function runWithIdentity(holder, fn) {
+    return identityStore.run(holder, fn);
+}
+/** The holder for a transport that serves a single client per process. */
+export function processIdentityHolder() {
+    return processHolder;
+}
+function currentIdentity() {
+    return (identityStore.getStore() ?? processHolder).identity;
 }
-/** The client name this server registered with, e.g. "claude-code". */
+/** The client name this session registered with, e.g. "claude-code". */
 export function agentIdentityName() {
-    return identityName;
+    return currentIdentity()?.name ?? "";
+}
+function agentHeaders() {
+    const id = currentIdentity();
+    if (!id)
+        return {};
+    return {
+        "x-plonk-agent": id.version ? `${id.name}/${id.version}` : id.name,
+        "x-plonk-agent-pid": String(id.pid),
+    };
 }
 export async function call(path, options = {}) {
     const { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
@@ -23,7 +42,7 @@ export async function call(path, options = {}) {
     try {
         res = await fetch(BASE + path, {
             method,
-            headers: { "content-type": "application/json", ...agentHeaders },
+            headers: { "content-type": "application/json", ...agentHeaders() },
             body: body !== undefined ? JSON.stringify(body) : undefined,
             signal: timeout,
         });

package/dist/factory.js

@@ -0,0 +1,98 @@
+// Builds a fully-registered Plonk MCP server. Each connected client gets its
+// own instance, so per-session state (clientInfo) stays separate.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createRequire } from "node:module";
+import { call } 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";
+import { register as registerAgents } from "./tools/agents.js";
+import { register as registerUpdate } from "./tools/update.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+export function createPlonkServer() {
+    const server = new McpServer({ name: "plonk", version });
+    registerState(server);
+    registerWorkspaces(server);
+    registerLayouts(server);
+    registerZones(server);
+    registerAwake(server);
+    registerScreenshot(server);
+    registerAnnotate(server);
+    registerAgents(server);
+    registerUpdate(server);
+    return server;
+}
+/** Reports the client's name and version once the MCP handshake lands.
+ * PLONK_AGENT_NAME lets the user name a session by hand ("work",
+ * "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) {
+    const poll = (attempt = 0) => {
+        const client = server.server.getClientVersion();
+        if (!client && attempt < 50) {
+            setTimeout(() => poll(attempt + 1), 100).unref();
+            return;
+        }
+        const name = (process.env.PLONK_AGENT_NAME || client?.name || "mcp-client").replaceAll("/", "-");
+        onKnown({ name, version: client?.version ?? "" });
+    };
+    server.server.oninitialized = () => poll();
+}
+/** 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) {
+    const hello = () => call("/agents/hello", {
+        method: "POST",
+        body: { name: identity.name, version: identity.version, pid: identity.pid },
+        timeoutMs: 3_000,
+    });
+    void hello();
+    const timer = setInterval(hello, 30_000);
+    timer.unref();
+    return () => clearInterval(timer);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
+/** Long-polls the app's inbox for tasks addressed to this client — the
+ * channel that lets Plonk (voice, hotkeys, other agents) reach the agent.
+ * A task is handed to the client's own model through MCP sampling, so the loop
+ * only runs for clients that declared that capability: polling drains the
+ * 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) {
+    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.`);
+        return () => { };
+    }
+    let stopped = false;
+    const loop = async () => {
+        while (!stopped) {
+            const res = await call(`/agents/inbox?agent=${encodeURIComponent(identity.name)}&wait=25`, { timeoutMs: 30_000 });
+            if (stopped)
+                return;
+            if ("error" in res) {
+                await sleep(5_000);
+                continue;
+            }
+            for (const task of res.tasks ?? []) {
+                server.server
+                    .createMessage({
+                    messages: [{ role: "user", content: { type: "text", text: task.prompt } }],
+                    maxTokens: 4_000,
+                    systemPrompt: "The user sent this through Plonk, the Mac window manager this agent controls over MCP. Act on it with the plonk tools where they apply.",
+                })
+                    .catch((err) => console.error(`plonk-mcp: sampling failed for task ${task.id}:`, err));
+            }
+        }
+    };
+    void loop();
+    return () => {
+        stopped = true;
+    };
+}

package/dist/http.js

@@ -0,0 +1,83 @@
+// Streamable HTTP transport: one process, many clients — for anything that
+// cannot spawn a stdio process. Binds to loopback only and carries the same
+// threat model as the app's own API: a web page must never be able to drive
+// the desktop, and a DNS-rebinding page must not reach the port by Host games.
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { runWithIdentity } from "./api.js";
+import { createPlonkServer, startHello, startInboxLoop, watchClientInfo } 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;
+function reject(res, status, error) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error }));
+}
+export async function serveHttp(port) {
+    const sessions = new Map();
+    const handle = async (req, res) => {
+        // Browsers always attach Origin to cross-site POSTs and Sec-Fetch-Site to
+        // every request, and page script cannot suppress either.
+        if (req.headers.origin !== undefined || req.headers["sec-fetch-site"] !== undefined) {
+            reject(res, 403, "requests from web pages are not accepted");
+            return;
+        }
+        const host = (req.headers.host ?? "").toLowerCase();
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+            reject(res, 403, "unexpected Host header");
+            return;
+        }
+        if (new URL(req.url ?? "/", `http://${host}`).pathname !== "/mcp") {
+            reject(res, 404, "the MCP endpoint is /mcp");
+            return;
+        }
+        const sessionId = req.headers["mcp-session-id"];
+        const existing = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
+        if (existing) {
+            await runWithIdentity(existing.holder, () => existing.transport.handleRequest(req, res));
+            return;
+        }
+        if (req.method !== "POST") {
+            reject(res, 400, "start a session with an initialize POST first");
+            return;
+        }
+        const session = {
+            holder: {},
+            transport: new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    sessions.set(sid, session);
+                },
+            }),
+        };
+        session.transport.onclose = () => {
+            session.stopHello?.();
+            session.stopInbox?.();
+            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);
+        });
+        await server.connect(session.transport);
+        await runWithIdentity(session.holder, () => session.transport.handleRequest(req, res));
+    };
+    const httpServer = createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            console.error("plonk-mcp:", err);
+            if (!res.headersSent)
+                reject(res, 500, "internal error");
+        });
+    });
+    await new Promise((resolve, rejectListen) => {
+        httpServer.once("error", rejectListen);
+        httpServer.listen(port, "127.0.0.1", resolve);
+    });
+    console.error(`plonk-mcp: Streamable HTTP at http://127.0.0.1:${port}/mcp`);
+}

package/dist/server.js

@@ -1,55 +1,36 @@
 #!/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";
+//
+// Default transport is stdio: one process per client, spawned by it.
+// `--http [--port N]` serves Streamable HTTP at http://127.0.0.1:<port>/mcp
+// instead, for clients that cannot spawn a process — several at once.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createRequire } from "node:module";
-import { BASE, call, isAppReachable, setAgentIdentity } 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";
-import { register as registerAgents } from "./tools/agents.js";
-const { version } = createRequire(import.meta.url)("../package.json");
-const server = new McpServer({ name: "plonk", version });
-registerState(server);
-registerWorkspaces(server);
-registerLayouts(server);
-registerZones(server);
-registerAwake(server);
-registerScreenshot(server);
-registerAnnotate(server);
-registerAgents(server);
-// The handshake tells us which client we serve; PLONK_AGENT_NAME lets the user
-// name a session by hand ("work", "pet-project"). Registering keeps this
-// client on the app's agent list; the heartbeat keeps it marked online.
-// The initialized notification can outrun the initialize handler's bookkeeping
-// in the SDK, leaving clientInfo briefly unset, so poll instead of trusting
-// the callback's timing.
-function identify(attempt = 0) {
-    const client = server.server.getClientVersion();
-    if (!client && attempt < 50) {
-        setTimeout(() => identify(attempt + 1), 100).unref();
-        return;
+import { BASE, isAppReachable, processIdentityHolder } from "./api.js";
+import { createPlonkServer, startHello, startInboxLoop, watchClientInfo } from "./factory.js";
+import { serveHttp } from "./http.js";
+const args = process.argv.slice(2);
+if (args.includes("--http")) {
+    const portIndex = args.indexOf("--port");
+    const port = portIndex >= 0 ? Number(args[portIndex + 1]) : 43918;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        console.error("plonk-mcp: --port needs a number between 1 and 65535");
+        process.exit(1);
     }
-    const agentName = (process.env.PLONK_AGENT_NAME || client?.name || "mcp-client").replaceAll("/", "-");
-    const agentVersion = client?.version ?? "";
-    setAgentIdentity(agentName, agentVersion);
-    const hello = () => call("/agents/hello", {
-        method: "POST",
-        body: { name: agentName, version: agentVersion, pid: process.pid },
-        timeoutMs: 3_000,
+    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);
     });
-    void hello();
-    setInterval(hello, 30_000).unref();
+    await server.connect(new StdioServerTransport());
 }
-server.server.oninitialized = () => identify();
-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.
+// stdout carries the stdio 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/agents.js

@@ -11,6 +11,14 @@ export function register(server) {
             .optional()
             .describe("Also turn 'only the active agent controls' on or off"),
     }, async ({ name, exclusive }) => {
+        // An unset identity would turn "select myself" into "" — the value that
+        // clears the user's choice — so refuse rather than undo their selection.
+        if (name === undefined && !agentIdentityName()) {
+            return text({
+                error: "this client has not finished registering with Plonk yet, so it cannot select itself; " +
+                    "retry in a moment or pass an explicit name from get_state",
+            });
+        }
         const target = name === undefined ? agentIdentityName() : name;
         const selected = await call("/agents/select", { method: "POST", body: { name: target } });
         if ("error" in selected || exclusive === undefined)

package/dist/tools/update.js

@@ -0,0 +1,5 @@
+import { call, text } from "../api.js";
+export function register(server) {
+    server.tool("check_for_update", "Ask Plonk whether a newer release exists, and report what is installed. Use this when the user asks what version they run, whether Plonk is up to date, or before calling install_update — which refuses unless a newer release is already on offer. The check is a network round trip to the GitHub releases API, so this returns immediately with the state as it stands and the result lands a moment later: read it back from get_state's 'update' key, or wait for an 'update' event on the change stream. If the user has turned update checks off, this fails with 409 rather than dialling out on their behalf — Plonk promises a process that only listens, and the user can still check by hand on its Updates page; report that back instead of retrying. Returns {installed, latest?, available, phase, status, automatic, notes?, page?}: 'available' is true only when 'latest' is newer than 'installed', 'phase' is idle|checking|available|downloading|verifying|installing|failed, and 'status' is a sentence fit to show the user.", {}, async () => text(await call("/update/check", { method: "POST" })));
+    server.tool("install_update", "Install the release that check_for_update found: Plonk downloads the build, checks it is signed with the same certificate as the running copy, swaps the bundle in, and relaunches itself. Prefer this over telling the user to download a build by hand — the signature check is also what preserves their Accessibility and Screen Recording grants, which a hand-installed copy can lose. Ask the user before calling it: it quits the app, so any window arrangement in flight stops and the local API is unreachable for a few seconds until the new copy is up. It fails without touching the installed copy when no newer release is on offer (call check_for_update first), when the user has update checks switched off (409 — installing downloads a build, so it is bound by the same promise as the check; they can install from Plonk's Updates page), when the download does not match the release or its signature, or when Plonk.app sits somewhere the user cannot write. Returns the same shape as check_for_update plus {installing: true} once the swap has started; poll get_state afterwards to confirm the new version came up.", {}, async () => text(await call("/update/install", { method: "POST" })));
+}

package/dist/tools/zones.js

@@ -7,9 +7,9 @@ export function register(server) {
         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.", {
+    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"),
     }, 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 } })));
+    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 } })));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "mcpName": "io.github.ostapondo/plonk",
   "description": "MCP server for Plonk — the Mac window manager your AI agent can drive. Layouts, workspaces, snap zones, keep-awake and screenshots.",
   "type": "module",