spacepal-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Halberd LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# Spacepal MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets Claude, Cursor and other MCP clients work with your macOS Spaces through
+[Spacepal](https://getspacepal.com): "switch to my Mail Space", "what's on Desktop 3?",
+"name this desktop Research".
+
+It runs locally over stdio. It reads the Space list Spacepal writes to
+`~/Library/Application Support/Spacepal/state.json` and sends commands through the
+`spacepal://` URL scheme. It makes no network calls.
+
+## Requirements
+
+- macOS 14 or later, with Spacepal running (direct or Mac App Store build)
+- Node.js 18 or later
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_spaces` | Every Space with its number, name, display, apps, and which one is active |
+| `current_space` | The Space you are on |
+| `switch_space` | Switch by number or name, or step with `next`, `previous`, `back` |
+| `move_window_to_space` | Send the frontmost window to a Space by number or name, or to `next` or `previous` |
+| `rename_space` | Name a Space; an empty name restores "Desktop N" |
+| `open_overview` | Open Spacepal's overview grid |
+| `set_space_note` | Attach a short note to a Space |
+| `apply_profile` | Apply a saved Spacepal profile |
+
+`move_window_to_space` acts on the frontmost window. In Claude Desktop that is usually
+Claude's own window. Moving the frontmost window works on every supported macOS version.
+
+## Install
+
+### Claude Code
+
+```sh
+claude mcp add spacepal -- npx -y spacepal-mcp
+```
+
+### Claude Desktop
+
+Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`, then restart
+Claude:
+
+```json
+{
+  "mcpServers": {
+    "spacepal": { "command": "npx", "args": ["-y", "spacepal-mcp"] }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:
+
+```json
+{
+  "mcpServers": {
+    "spacepal": { "command": "npx", "args": ["-y", "spacepal-mcp"] }
+  }
+}
+```
+
+### From source
+
+```sh
+cd mcp && npm install
+claude mcp add spacepal -- node "$PWD/index.js"
+```
+
+## Troubleshooting
+
+- **"Spacepal is not running"**: open Spacepal from Applications.
+- **Names are out of date**: Spacepal rewrites `state.json` when Spaces change. Open its
+  menu once to refresh it.
+- **Switching does nothing**: check Spacepal > Settings > Setup. It needs Accessibility
+  permission.
+
+MIT © Halberd LLC

package/index.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// Spacepal MCP server (stdio).
+// Reads the live Space list from the state.json Spacepal writes, and sends
+// commands through the spacepal:// URL scheme. Nothing leaves the Mac.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const VERSION = "0.1.0";
+
+// Direct build writes to Application Support; the App Store build is sandboxed.
+const STATE_FILES = [
+  join(homedir(), "Library/Application Support/Spacepal/state.json"),
+  join(homedir(), "Library/Containers/com.halberd.spacepal/Data/Library/Application Support/Spacepal/state.json"),
+];
+
+const NOT_RUNNING = "Spacepal is not running. Open Spacepal (getspacepal.com) and try again.";
+
+async function isRunning() {
+  try {
+    await run("/usr/bin/pgrep", ["-x", "Spacepal"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readState() {
+  let newest = null;
+  for (const path of STATE_FILES) {
+    try {
+      const { mtimeMs } = await stat(path);
+      if (!newest || mtimeMs > newest.mtimeMs) newest = { path, mtimeMs };
+    } catch {}
+  }
+  if (!newest) return null;
+  return JSON.parse(await readFile(newest.path, "utf8"));
+}
+
+async function send(path, query = {}) {
+  if (!(await isRunning())) throw new Error(NOT_RUNNING);
+  // Encode with %20, not "+": the app reads query values with URLComponents, which keeps "+".
+  const qs = Object.entries(query)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+  const url = `spacepal://${path}${qs ? `?${qs}` : ""}`;
+  // -g keeps Spacepal from stealing focus from the client.
+  await run("/usr/bin/open", ["-g", url]);
+  return url;
+}
+
+// A Space can be addressed by desktop number or by name.
+function ref(space) {
+  if (space === undefined || space === null || space === "") return "current";
+  if (typeof space === "number" || /^\d+$/.test(String(space))) return String(space);
+  return encodeURIComponent(String(space));
+}
+
+async function findSpace(space) {
+  const state = await readState();
+  if (!state) return null;
+  const key = String(space).toLowerCase();
+  return state.spaces.find((s) => String(s.number) === key || s.name.toLowerCase() === key) ?? null;
+}
+
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const fail = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const settle = () => new Promise((r) => setTimeout(r, 600));
+
+// state.json is rewritten after the switch animation; poll until "current" changes.
+async function waitForSwitch(before, timeoutMs = 2500) {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    await new Promise((r) => setTimeout(r, 150));
+    const current = (await readState())?.current;
+    if (current && current !== before) return current;
+  }
+  return null;
+}
+
+function guarded(fn) {
+  return async (args) => {
+    try {
+      return await fn(args ?? {});
+    } catch (e) {
+      return fail(e.message ?? String(e));
+    }
+  };
+}
+
+const server = new McpServer({ name: "spacepal", version: VERSION });
+const spaceArg = z
+  .union([z.number().int().positive(), z.string().min(1)])
+  .describe("Desktop number (1, 2, ...) or Space name, e.g. \"Mail\".");
+
+server.registerTool(
+  "list_spaces",
+  {
+    title: "List Spaces",
+    description: "List every macOS Space (desktop) with its number, name, display, apps and which one is active.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  guarded(async () => {
+    if (!(await isRunning())) return fail(NOT_RUNNING);
+    const state = await readState();
+    if (!state) return fail("Spacepal has not written its Space list yet. Open the Spacepal menu once and try again.");
+    const lines = state.spaces.map((s) => {
+      const label = s.isFullscreen ? "full screen" : `Desktop ${s.number ?? "?"}`;
+      const apps = s.apps?.length ? ` — ${s.apps.join(", ")}` : "";
+      return `${s.isActive ? "*" : " "} ${label}: ${s.name}${apps}`;
+    });
+    const displays = new Set(state.spaces.map((s) => s.display)).size;
+    return {
+      content: [
+        { type: "text", text: `Current: ${state.current}\n${displays} display(s), ${state.spaces.length} Spaces (* = active)\n${lines.join("\n")}` },
+      ],
+      structuredContent: state,
+    };
+  }),
+);
+
+server.registerTool(
+  "current_space",
+  {
+    title: "Current Space",
+    description: "Name and number of the Space you are on.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  guarded(async () => {
+    if (!(await isRunning())) return fail(NOT_RUNNING);
+    const state = await readState();
+    const active = state?.spaces.filter((s) => s.isActive) ?? [];
+    if (!active.length) return text(state?.current ? `Current: ${state.current}` : "Unknown");
+    return text(active.map((s) => `${s.name} (Desktop ${s.number ?? "full screen"})`).join("\n"));
+  }),
+);
+
+server.registerTool(
+  "switch_space",
+  {
+    title: "Switch Space",
+    description: "Switch to a Space by desktop number or name. Use \"next\", \"previous\" or \"back\" to step.",
+    inputSchema: { space: spaceArg },
+  },
+  guarded(async ({ space }) => {
+    const before = (await readState())?.current;
+    const s = String(space).toLowerCase();
+    if (["next", "right"].includes(s)) await send("next");
+    else if (["previous", "prev", "left"].includes(s)) await send("previous");
+    else if (["back", "last"].includes(s)) await send("back");
+    else {
+      const target = await findSpace(space);
+      if (!target) return fail(`No Space called "${space}". Call list_spaces to see the names.`);
+      // Spacepal treats "switch to the Space you are on" as back-and-forth, so skip it.
+      if (target.isActive) return text(`Already on ${target.name}.`);
+      await send(`switch/${ref(space)}`);
+    }
+    const now = await waitForSwitch(before);
+    return text(now ? `Switched. Now on: ${now}` : "Switch sent; Spacepal has not confirmed it yet.");
+  }),
+);
+
+server.registerTool(
+  "move_window_to_space",
+  {
+    title: "Move window to Space",
+    description:
+      "Send the frontmost window to another Space (by number or name, or \"next\"/\"previous\"). " +
+      "Note: moving windows needs macOS 14.0-14.4 or 26.4+, a macOS limit.",
+    inputSchema: { space: spaceArg },
+  },
+  guarded(async ({ space }) => {
+    const s = String(space).toLowerCase();
+    if (["next", "right"].includes(s)) await send("move-window/next");
+    else if (["previous", "prev", "left"].includes(s)) await send("move-window/previous");
+    else {
+      if (!(await findSpace(space))) return fail(`No Space called "${space}". Call list_spaces to see the names.`);
+      await send(`move-window/${ref(space)}`);
+    }
+    return text(`Asked Spacepal to move the front window to ${space}.`);
+  }),
+);
+
+server.registerTool(
+  "rename_space",
+  {
+    title: "Rename Space",
+    description: "Give a Space a name. Leave space empty for the current one; an empty name restores the default.",
+    inputSchema: {
+      space: spaceArg.optional(),
+      name: z.string().max(60).describe("New name. Empty text restores \"Desktop N\"."),
+    },
+  },
+  guarded(async ({ space, name }) => {
+    if (space !== undefined && !(await findSpace(space))) return fail(`No Space called "${space}".`);
+    await send(`rename/${ref(space)}`, { name });
+    await settle();
+    return text(name ? `Renamed to "${name}".` : "Name reset to default.");
+  }),
+);
+
+server.registerTool(
+  "open_overview",
+  {
+    title: "Open overview",
+    description: "Open Spacepal's overview grid of all Spaces on screen.",
+    inputSchema: {},
+  },
+  guarded(async () => {
+    await send("overview");
+    return text("Overview opened.");
+  }),
+);
+
+server.registerTool(
+  "set_space_note",
+  {
+    title: "Set Space note",
+    description: "Attach a short note to a Space (what it is for).",
+    inputSchema: { space: spaceArg.optional(), text: z.string().max(500) },
+  },
+  guarded(async ({ space, text: note }) => {
+    await send(`note/${ref(space)}`, { text: note });
+    return text("Note saved.");
+  }),
+);
+
+server.registerTool(
+  "apply_profile",
+  {
+    title: "Apply profile",
+    description: "Apply a saved Spacepal profile by name (names, layouts and rules).",
+    inputSchema: { name: z.string().min(1) },
+  },
+  guarded(async ({ name }) => {
+    await send(`profile/${encodeURIComponent(name)}`);
+    return text(`Applied profile "${name}".`);
+  }),
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "spacepal-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Spacepal: list, switch, rename macOS Spaces and move windows between them from Claude, Cursor or any MCP client.",
+  "mcpName": "com.getspacepal/spacepal",
+  "type": "module",
+  "bin": { "spacepal-mcp": "index.js" },
+  "files": ["index.js", "README.md", "LICENSE", "server.json"],
+  "engines": { "node": ">=18" },
+  "os": ["darwin"],
+  "keywords": ["mcp", "model-context-protocol", "macos", "spaces", "mission-control", "spacepal", "claude"],
+  "homepage": "https://getspacepal.com/integrations/mcp/",
+  "author": "Halberd LLC",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.23.8"
+  }
+}

package/server.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "com.getspacepal/spacepal",
+  "title": "Spacepal",
+  "description": "List, switch and rename macOS Spaces and move windows between them. Needs the Spacepal app.",
+  "version": "0.1.0",
+  "websiteUrl": "https://getspacepal.com/integrations/mcp/",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "spacepal-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" }
+    }
+  ]
+}