plonk-mcp 0.1.0 → 0.2.0

package/README.md

@@ -40,7 +40,10 @@ server. One-pagers for
 
 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).
+`http://127.0.0.1:43918/mcp` (loopback only, `--port` to change). Requests to
+it carry the same token as the app's own API — send the contents of
+`~/Library/Application Support/Plonk/token` as an `X-Plonk-Token` header. The
+stdio transport reads that file itself and needs no configuration.
 
 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.
@@ -70,5 +73,10 @@ 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.
 
+The app gates that API on a token it writes to
+`~/Library/Application Support/Plonk/token`. This server reads the file itself,
+so there is nothing to configure — but it does have to run as the same user
+Plonk is running as.
+
 MIT. Source, screenshots and the rest of the documentation are in the
 [repository](https://github.com/ostapondo/plonk).

package/dist/api.js

@@ -35,17 +35,90 @@ function agentHeaders() {
         "x-plonk-agent-pid": String(id.pid),
     };
 }
+// The app gates its API on a secret it writes to a file only this user can
+// read, because binding to loopback keeps the network out and does nothing
+// about the machine. Reading it is the whole handshake: anything that can read
+// the file could ask macOS for the screen directly.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const TOKEN_PATH = join(homedir(), "Library", "Application Support", "Plonk", "token");
+let cachedToken;
+function readTokenFile() {
+    try {
+        return readFileSync(TOKEN_PATH, "utf8").trim() || undefined;
+    }
+    catch {
+        // No app yet, or a file this user cannot read. The request goes without a
+        // token and the app's own 401 explains it better than a guess here would.
+        return undefined;
+    }
+}
+/** Only a successful read is cached: a client started before the app has ever
+ * run would otherwise never see the token the app writes on first launch. */
+function apiToken() {
+    if (cachedToken)
+        return cachedToken;
+    cachedToken = readTokenFile();
+    return cachedToken;
+}
+/** The token the HTTP transport gates its own callers on, read from disk every
+ * time rather than from the cache above.
+ *
+ * A cache here would be a gate on a secret the app may already have replaced:
+ * it would keep accepting the token a restored backup leaked — the exact one
+ * the app rotated away from — and keep refusing the current one, until this
+ * process was restarted. Nothing else could fix it, because the retry that
+ * refreshes the cache lives on the far side of this check and never runs when
+ * no session gets in. It is one small read per request on a transport that
+ * handles few. */
+export function localApiToken() {
+    const fresh = readTokenFile();
+    // Outgoing calls may as well learn about a rotation from the same read.
+    if (fresh !== undefined && fresh !== cachedToken)
+        cachedToken = fresh;
+    return fresh;
+}
+/** Drops the cache and reads again, true only when the file now holds
+ * something other than what this request actually sent — the one case where
+ * repeating a refused request can help.
+ *
+ * `sent` rather than the cache, because the cache is shared: the hello
+ * heartbeat and the inbox long-poll are always in flight beside a tool call,
+ * so after a rotation the first 401 refreshes the cache and every other
+ * request in the air would find it already fresh and give up, handing the
+ * model a token error for a token that had just been fixed. */
+function refreshToken(sent) {
+    cachedToken = undefined;
+    const fresh = apiToken();
+    return fresh !== undefined && fresh !== sent;
+}
 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, {
+    // Captured per attempt, so the retry can tell "the token changed" from
+    // "somebody else refreshed the cache while this request was in the air".
+    let sent;
+    const send = () => {
+        sent = apiToken();
+        return fetch(BASE + path, {
             method,
-            headers: { "content-type": "application/json", ...agentHeaders() },
+            headers: {
+                "content-type": "application/json",
+                ...agentHeaders(),
+                ...(sent ? { "x-plonk-token": sent } : {}),
+            },
             body: body !== undefined ? JSON.stringify(body) : undefined,
             signal: timeout,
         });
+    };
+    let res;
+    try {
+        res = await send();
+        // A long-lived client outlives the token if the file is ever replaced.
+        // One re-read makes that a hiccup instead of a session to restart.
+        if (res.status === 401 && refreshToken(sent))
+            res = await send();
     }
     catch (err) {
         if (timeout.aborted) {

package/dist/args.js

@@ -0,0 +1,32 @@
+// Argument parsing for the `plonk` command, kept out of cli.ts so it can be
+// tested without running the CLI: importing cli.ts runs it.
+/**
+ * Pulls "--name value" out of argv and returns what is left, in order.
+ *
+ * A flag with nothing usable after it — the end of argv, or another flag — is
+ * a switch and reads as "true", so `--json` and `--screen 1` parse the same
+ * way. Values are not converted here; the caller knows which of its flags are
+ * numbers and says so in the error when one is not.
+ */
+export function options(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                flags[key] = "true";
+            }
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { flags, rest };
+}

package/dist/cli.js

@@ -6,6 +6,7 @@
 // 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 { options } from "./args.js";
 const USAGE = `plonk — drive the Plonk menu bar app from a shell
 
   plonk state [--json]              screens, windows, zone sets, workspaces
@@ -21,29 +22,6 @@ const USAGE = `plonk — drive the Plonk menu bar app from a shell
   plonk shot [--mode region|window|screen] [--path FILE]
 
 Everything talks to ${BASE}; Plonk.app has to be running.`;
-/** Pulls "--name value" out of argv and returns what is left. */
-function options(argv) {
-    const flags = {};
-    const rest = [];
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg.startsWith("--")) {
-            const key = arg.slice(2);
-            const next = argv[i + 1];
-            if (next === undefined || next.startsWith("--")) {
-                flags[key] = "true";
-            }
-            else {
-                flags[key] = next;
-                i++;
-            }
-        }
-        else {
-            rest.push(arg);
-        }
-    }
-    return { flags, rest };
-}
 /** Unwinds to the top instead of calling process.exit, which on a pipe cuts
  * stdout off mid-write: `plonk state --json | jq` would get invalid JSON.
  * Letting the process end on its own flushes first. */

package/dist/http.js

@@ -3,13 +3,22 @@
 // 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 { randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { runWithIdentity } from "./api.js";
+import { localApiToken, 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 headerToken(req) {
+    const value = req.headers["x-plonk-token"];
+    return (Array.isArray(value) ? value[0] : value) ?? "";
+}
+/** Length is not the secret; which byte differed would be. */
+function timingSafeEqualString(presented, token) {
+    const a = Buffer.from(presented, "utf8"), b = Buffer.from(token, "utf8");
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
 function reject(res, status, error) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify({ error }));
@@ -32,6 +41,20 @@ export async function serveHttp(port) {
             reject(res, 404, "the MCP endpoint is /mcp");
             return;
         }
+        // This process holds the app's token, so without a gate of its own it is a
+        // way around the app's: anything local could call take_screenshot through
+        // it and borrow Screen Recording. Same secret, same header, same file —
+        // there is nothing extra for a client to be given.
+        const token = localApiToken();
+        if (!token) {
+            reject(res, 503, "no Plonk API token could be read, so this transport is answering nothing");
+            return;
+        }
+        if (!timingSafeEqualString(headerToken(req), token)) {
+            reject(res, 401, "this request carried no valid token; send the contents of " +
+                "~/Library/Application Support/Plonk/token as the X-Plonk-Token header");
+            return;
+        }
         const sessionId = req.headers["mcp-session-id"];
         const existing = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
         if (existing) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
@@ -35,7 +35,8 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "tsc",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsc && node --test test/*.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",