spacepal-mcp 0.4.2 → 0.5.0

package/README.md

@@ -24,6 +24,7 @@ It runs locally over stdio. It reads the Space list Spacepal writes to
 | `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` |
+| `open_url` | Open a link in a new browser window on a chosen Space (or the current one), so it does not land in a browser window on another Space |
 | `rename_space` | Name a Space; an empty name restores "Desktop N" |
 | `set_space_note` | Attach a short note to a Space |
 | `open_overview` | Open Spacepal's overview grid |

package/index.js

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 const run = promisify(execFile);
-const VERSION = "0.4.1";
+const VERSION = "0.5.0";
 
 // Direct build writes to Application Support; the App Store build is sandboxed.
 const SUPPORT_DIRS = [
@@ -21,6 +21,8 @@ const SUPPORT_DIRS = [
   join(homedir(), "Library/Containers/com.halberd.spacepal/Data/Library/Application Support/Spacepal"),
 ];
 const STATE_FILES = SUPPORT_DIRS.map((d) => join(d, "state.json"));
+// Per-Space settings, including the folders of the terminals that belong to each Space.
+const SPACE_FILES = SUPPORT_DIRS.map((d) => join(d, "spaces.json"));
 const PROFILE_FILES = SUPPORT_DIRS.map((d) => join(d, "profiles.json"));
 // Built into the app (Profiles.swift, SpaceTemplate.all()).
 const TEMPLATES = ["Developer", "Designer", "Freelancer", "Student", "Streamer"];
@@ -139,6 +141,8 @@ Start with list_spaces to learn the Spaces, their numbers, names, notes and the
 
 Tools that only read: list_spaces, current_space, list_profiles. Tools that change the user's screen or setup: everything else. Ask the user before remove_desktop, apply_template and apply_profile, which replace or remove things; rename_space and set_space_note are easy to undo by calling them again.
 
+To show the user a web page (docs, a pull request, a local dev server, a sign-in page), call open_url instead of running "open <url>" in a shell. A shell open puts the page in whichever browser window was used last, often on another Space where the user cannot find it. Leave open_url's space out and the page opens on this project's Space.
+
 Every action goes through Spacepal, so it must be running (macOS 14 or later). Nothing is sent over the network. If a tool says Spacepal is not running, tell the user to open it. If it says Spacepal is not installed, give the user the download link from the message. The overview and sessions need Spacepal's trial or a license; names, notes and switching work in the free version.`;
 
 const server = new McpServer({ name: "spacepal", version: VERSION }, { instructions: INSTRUCTIONS });
@@ -285,6 +289,131 @@ server.registerTool(
   }),
 );
 
+// The Space of the project this client works in: the one whose terminals run in this folder
+// (Spacepal records them), or whose note names it. A coding agent's MCP server starts in the
+// project folder; Claude Desktop starts it in "/", which matches nothing.
+async function projectSpace(state) {
+  const cwd = process.cwd();
+  if (!state || cwd === "/" || cwd === homedir()) return null;
+  let best = null;
+  let tie = false;
+  try {
+    const path = await newestFile(SPACE_FILES);
+    const meta = path ? JSON.parse(await readFile(path, "utf8")) : {};
+    for (const [id, entry] of Object.entries(meta)) {
+      for (const t of entry?.automation?.terminals ?? []) {
+        const folder = String(t.folder ?? "").replace(/\/+$/, "");
+        if (!folder || folder === homedir()) continue;
+        if (cwd !== folder && !cwd.startsWith(folder + "/")) continue;
+        if (!best || folder.length > best.len) { best = { id, len: folder.length }; tie = false; }
+        else if (folder.length === best.len && id !== best.id) tie = true;
+      }
+    }
+  } catch {}
+  if (best && !tie) {
+    const space = state.spaces.find((s) => s.id === best.id && !s.isFullscreen);
+    if (space) return space;
+  }
+  // Notes such as "Reddit Growth (~/workspace/reddit-growth)".
+  const short = cwd.replace(homedir(), "~");
+  const named = state.spaces.filter((s) => s.note && (s.note.includes(cwd) || s.note.includes(short)));
+  return named.length === 1 ? named[0] : null;
+}
+
+// Default browser's app path, via AppKit from JXA (no extra permission needed).
+async function defaultBrowser() {
+  try {
+    const { stdout } = await run("/usr/bin/osascript", [
+      "-l", "JavaScript", "-e",
+      "ObjC.import('AppKit'); $.NSWorkspace.sharedWorkspace.URLForApplicationToOpenURL($.NSURL.URLWithString('https://example.com')).path.js",
+    ]);
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Opens the link in a NEW window of the default browser, so it lands on the Space shown now
+// instead of in the browser window the user used last (which may be on another Space).
+async function openInNewWindow(url) {
+  const app = await defaultBrowser();
+  const name = app ? app.split("/").pop().replace(/\.app$/, "") : "";
+  if (/safari/i.test(name)) {
+    await run("/usr/bin/osascript", [
+      "-e", "on run argv",
+      "-e", `tell application "${name}" to make new document with properties {URL:item 1 of argv}`,
+      "-e", `tell application "${name}" to activate`,
+      "-e", "end run", url,
+    ]);
+  } else if (/firefox|zen|librewolf|floorp/i.test(name)) {
+    await run("/usr/bin/open", ["-na", app, "--args", "-new-window", url]);
+  } else if (app && /chrome|chromium|brave|edge|vivaldi|opera|arc|dia|comet|thorium/i.test(name)) {
+    await run("/usr/bin/open", ["-na", app, "--args", "--new-window", url]);
+  } else {
+    await run("/usr/bin/open", [url]);
+  }
+  return name || "the default browser";
+}
+
+server.registerTool(
+  "open_url",
+  {
+    title: "Open link on a Space",
+    description:
+      "Open a web link in a new window of the user's default browser, on the Space you choose. " +
+      "Leave space out to open it on the Space of the project you are working in (the Space whose terminals run in your working folder), or on the user's current Space if none matches. " +
+      "Use it instead of the shell's open command: that adds a tab to the browser window used last, which may be on another Space, so the user cannot find it. " +
+      "With a space, Spacepal briefly shows that Space, opens the window there, then returns to the Space the user was on (stay=true keeps that Space on screen). " +
+      "Only http and https links. Fails if no Space has that name.",
+    inputSchema: {
+      url: z.string().min(1).describe('The link, e.g. "https://example.com". "example.com" is read as https.'),
+      space: spaceArg.optional().describe(
+        "Desktop number or name from list_spaces. Leave it out for this project's Space, or the current Space if Spacepal does not know the project.",
+      ),
+      stay: z.boolean().optional().describe("Stay on that Space afterwards instead of returning. Default false."),
+    },
+    annotations: { title: "Open link on a Space", ...CHANGE, openWorldHint: true },
+  },
+  guarded(async ({ url, space, stay }) => {
+    let link = String(url).trim();
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(link)) link = `https://${link}`;
+    let parsed;
+    try {
+      parsed = new URL(link);
+    } catch {
+      return fail(`"${url}" is not a valid link.`);
+    }
+    if (!["http:", "https:"].includes(parsed.protocol)) return fail("Only http and https links can be opened.");
+    if (!(await isRunning())) return fail(await notRunning());
+
+    const state = await readState();
+    const origin = state?.spaces.find((s) => s.isActive);
+    const target = space === undefined ? await projectSpace(state) : await findSpace(space);
+    if (space !== undefined && !target) return fail(`No Space called "${space}". Call list_spaces to see the names.`);
+    if (target?.isFullscreen) return fail(`${target.name} is a full-screen app; pick a desktop.`);
+
+    const elsewhere = target && !target.isActive;
+    // Spacepal's "Keep with me" would otherwise bring the new window back to the Space the user returns to.
+    // Older Spacepal versions ignore this command.
+    if (elsewhere) await send("hold-windows/8");
+    if (elsewhere) {
+      await send(`switch/${ref(target.number ?? target.name)}`);
+      if (!(await waitForSwitch(state?.current))) return fail(`Could not switch to ${target.name}; the link was not opened.`);
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    const browser = await openInNewWindow(parsed.href);
+    const where = target?.name ?? origin?.name ?? "the current Space";
+    if (elsewhere && !stay && origin) {
+      // Give the browser time to put its window on this Space before leaving it.
+      await new Promise((r) => setTimeout(r, 1800));
+      await send(`switch/${ref(origin.number ?? origin.name)}`);
+      await waitForSwitch(target.name);
+      return text(`Opened ${parsed.href} in a new ${browser} window on ${where}, then returned to ${origin.name}.`);
+    }
+    return text(`Opened ${parsed.href} in a new ${browser} window on ${where}.`);
+  }),
+);
+
 server.registerTool(
   "rename_space",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spacepal-mcp",
-  "version": "0.4.2",
+  "version": "0.5.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",

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.getspacepal/spacepal",
   "title": "Spacepal",
   "description": "List, switch and rename macOS Spaces and move windows between them. Needs the Spacepal app.",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "websiteUrl": "https://getspacepal.com/integrations/mcp/",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "spacepal-mcp",
-      "version": "0.4.2",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       }