@mrfentmen/applescript-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# AppleScript MCP
 
-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.
+AppleScript is a missing language in the MCP ecosystem. This server gives agents real macOS automation tools instead of a stub.
+
+Keyless. No API key. No signup. Requires macOS and the built-in `osascript`, `osacompile`, `sdef`, `open`, and `pbcopy` tools.
+
+## Install
+
+```bash
+npx -y @mrfentmen/applescript-mcp
+```
+
+Or in an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "applescript-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mrfentmen/applescript-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `run_script` | Run an AppleScript string. |
+| `run_script_file` | Run a `.scpt` or `.applescript` file with argv values. |
+| `check_syntax` | Compile without running. |
+| `compile_script` | Compile a string to a `.scpt` file. |
+| `run_handler` | Call one named handler from a script. |
+| `list_running_apps` | List visible foreground apps. |
+| `get_app_info` | Check running, frontmost and visible state. |
+| `get_app_dictionary` | Read an app's AppleScript dictionary with `sdef`. |
+| `tell_app` | Send a raw command inside a `tell application` block. |
+| `display_dialog` | Show a dialog and return the chosen button. |
+| `display_notification` | Show a macOS notification. |
+| `get_clipboard` | Read plain text from the clipboard. |
+| `set_clipboard` | Replace the clipboard with plain text. |
+| `open_app` | Open an app by name. |
+| `quit_app` | Ask an app to quit. |
+| `system_info` | Return the macOS system info record. |
+
+## Safety
+
+These tools can run arbitrary AppleScript and control applications. Use them with trusted input only. `run_script`, `run_script_file`, `tell_app`, and `run_handler` are intentionally powerful.
+
+## Run locally
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${process.env.npm_package_name ?? "language-mcp"} running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/run.d.ts

@@ -0,0 +1,31 @@
+export declare class ToolError extends Error {
+}
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface RunOptions {
+    input?: string;
+    timeoutMs?: number;
+    cwd?: string;
+}
+/** Run a command without a shell and capture both streams. */
+export declare function run(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+export declare function runChecked(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+export declare function requireCommand(command: string): Promise<void>;
+export declare function text(value: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function fail(value: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare function errorMessage(error: unknown): string;
+export declare function clean(value: string): string;

package/dist/run.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+export class ToolError extends Error {
+}
+/** Run a command without a shell and capture both streams. */
+export function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill("SIGKILL");
+            reject(new ToolError(`${command} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new ToolError(`${command} could not start: ${error.message}`));
+        });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.stdin.on("error", () => { });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code: code ?? 0 });
+        });
+        if (options.input !== undefined)
+            child.stdin.write(options.input);
+        child.stdin.end();
+    });
+}
+export async function runChecked(command, args, options = {}) {
+    const result = await run(command, args, options);
+    if (result.code !== 0) {
+        throw new ToolError((result.stderr || result.stdout || `${command} exited with code ${result.code}`).trim());
+    }
+    return result;
+}
+export async function requireCommand(command) {
+    const result = await run("which", [command], { timeoutMs: 5_000 });
+    if (result.code !== 0)
+        throw new ToolError(`${command} is not installed or not on PATH`);
+}
+export function text(value) {
+    return { content: [{ type: "text", text: value }] };
+}
+export function fail(value) {
+    return { content: [{ type: "text", text: value }], isError: true };
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function clean(value) {
+    return value.replace(/\s+/g, " ").trim();
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,249 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { access, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { errorMessage, fail, requireCommand, run, runChecked, text, ToolError, } from "./run.js";
+const quote = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+const appName = z
+    .string()
+    .min(1)
+    .max(120)
+    .regex(/^[A-Za-z0-9 ._-]+$/, "Use an app name, not a path");
+const timeout = z.number().int().min(1_000).max(120_000).default(30_000);
+async function osa(script, timeoutMs = 30_000) {
+    const result = await run("osascript", ["-e", script], { timeoutMs });
+    if (result.code !== 0) {
+        throw new ToolError(result.stderr.trim() || `osascript exited with code ${result.code}`);
+    }
+    return result.stdout.trim();
+}
+async function osaFile(path, args, timeoutMs = 30_000) {
+    const result = await run("osascript", [path, ...args], { timeoutMs });
+    if (result.code !== 0) {
+        throw new ToolError(result.stderr.trim() || `osascript exited with code ${result.code}`);
+    }
+    return result.stdout.trim();
+}
+async function appPath(name) {
+    const candidates = [
+        join("/Applications", `${name}.app`),
+        join("/System/Applications", `${name}.app`),
+        join(homedir(), "Applications", `${name}.app`),
+    ];
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // Try the next standard app location.
+        }
+    }
+    throw new ToolError(`Could not find ${name}.app in /Applications, /System/Applications or ~/Applications`);
+}
+export function createServer() {
+    const server = new McpServer({ name: "applescript-mcp", version: "1.0.0" });
+    server.tool("run_script", "Run an AppleScript string with osascript. The script can control apps and the system; run only trusted code.", { script: z.string().min(1).max(200_000), timeoutMs: timeout }, async (a) => {
+        try {
+            return text(await osa(a.script, a.timeoutMs));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("run_script_file", "Run an AppleScript .scpt or .applescript file with optional argv values.", {
+        path: z.string().min(1).max(2_000),
+        args: z.array(z.string().max(2_000)).max(50).default([]),
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            return text(await osaFile(resolve(a.path), a.args, a.timeoutMs));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("check_syntax", "Compile an AppleScript without running it. Returns OK or the compiler error.", { script: z.string().min(1).max(200_000) }, async (a) => {
+        const dir = await mkdtemp(join(tmpdir(), "applescript-mcp-"));
+        try {
+            await requireCommand("osacompile");
+            await runChecked("osacompile", ["-e", a.script, "-o", join(dir, "check.scpt")], {
+                timeoutMs: 30_000,
+            });
+            return text("AppleScript syntax OK");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    server.tool("compile_script", "Compile an AppleScript string to a .scpt file without running it.", {
+        script: z.string().min(1).max(200_000),
+        outputPath: z.string().min(1).max(2_000),
+    }, async (a) => {
+        try {
+            await requireCommand("osacompile");
+            const output = resolve(a.outputPath);
+            await runChecked("osacompile", ["-e", a.script, "-o", output], { timeoutMs: 30_000 });
+            return text(`Compiled AppleScript to ${output}`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("run_handler", "Run one named AppleScript handler from a script, passing string or number arguments.", {
+        script: z.string().min(1).max(200_000),
+        handler: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "Use a valid AppleScript handler name"),
+        args: z.array(z.union([z.string(), z.number()])).max(20).default([]),
+        timeoutMs: timeout,
+    }, async (a) => {
+        const dir = await mkdtemp(join(tmpdir(), "applescript-mcp-"));
+        const file = join(dir, "handler.applescript");
+        const callArgs = a.args
+            .map((value) => (typeof value === "number" ? String(value) : quote(value)))
+            .join(", ");
+        const source = `${a.script}\n\non run argv\n  return ${a.handler}(${callArgs})\nend run\n`;
+        try {
+            await writeFile(file, source, "utf8");
+            return text(await osaFile(file, [], a.timeoutMs));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    server.tool("list_running_apps", "List visible foreground applications currently running.", {}, async () => {
+        try {
+            const output = await osa('tell application "System Events" to get name of every process whose background only is false');
+            const apps = output
+                .split(",")
+                .map((name) => name.trim())
+                .filter(Boolean);
+            return text(apps.length ? apps.join("\n") : "No foreground apps reported");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("get_app_info", "Check whether an app is running and whether it is frontmost and visible.", { app: appName }, async (a) => {
+        try {
+            return text(await osa(`tell application "System Events"\n` +
+                `if exists application process ${quote(a.app)} then\n` +
+                `tell application process ${quote(a.app)} to return "running, frontmost=" & (frontmost as text) & ", visible=" & (visible as text)\n` +
+                `else\nreturn "not running"\nend if\nend tell`));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("get_app_dictionary", "Read an installed app's AppleScript dictionary with sdef.", { app: appName }, async (a) => {
+        try {
+            await requireCommand("sdef");
+            const path = await appPath(a.app);
+            const result = await runChecked("sdef", [path], { timeoutMs: 30_000 });
+            const body = result.stdout.trim();
+            return text(body.slice(0, 30_000) || "The app returned an empty dictionary");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("tell_app", "Send one raw AppleScript command to an app. The command is executed inside a tell block.", {
+        app: appName,
+        command: z.string().min(1).max(20_000),
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            return text(await osa(`tell application ${quote(a.app)} to ${a.command}`, a.timeoutMs));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("display_dialog", "Show a macOS dialog and return the button the user chose.", {
+        message: z.string().min(1).max(10_000),
+        title: z.string().max(500).optional(),
+        buttons: z.array(z.string().min(1).max(80)).min(1).max(4).default(["OK"]),
+        defaultButton: z.string().max(80).optional(),
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            let script = `display dialog ${quote(a.message)}`;
+            if (a.title)
+                script += ` with title ${quote(a.title)}`;
+            script += ` buttons {${a.buttons.map(quote).join(", ")}}`;
+            if (a.defaultButton)
+                script += ` default button ${quote(a.defaultButton)}`;
+            return text(await osa(script, a.timeoutMs));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("display_notification", "Show a macOS notification. This does not wait for the user.", {
+        message: z.string().min(1).max(2_000),
+        title: z.string().min(1).max(200).default("AppleScript MCP"),
+        subtitle: z.string().max(200).optional(),
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            let script = `display notification ${quote(a.message)} with title ${quote(a.title)}`;
+            if (a.subtitle)
+                script += ` subtitle ${quote(a.subtitle)}`;
+            await osa(script, a.timeoutMs);
+            return text("Notification sent");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("get_clipboard", "Read plain text from the macOS clipboard.", {}, async () => {
+        try {
+            return text(await osa("the clipboard as text"));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("set_clipboard", "Replace the macOS clipboard with plain text.", { value: z.string().max(1_000_000) }, async (a) => {
+        try {
+            await runChecked("pbcopy", [], { input: a.value, timeoutMs: 10_000 });
+            return text(`Copied ${a.value.length} characters to the clipboard`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("open_app", "Open an installed macOS app by name.", { app: appName }, async (a) => {
+        try {
+            await runChecked("open", ["-a", a.app], { timeoutMs: 15_000 });
+            return text(`Opened ${a.app}`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("quit_app", "Ask an app to quit. Unsaved work may prompt the app.", { app: appName }, async (a) => {
+        try {
+            await osa(`tell application ${quote(a.app)} to quit`);
+            return text(`Asked ${a.app} to quit`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("system_info", "Return the macOS system info record (OS version, model, CPU, memory).", {}, async () => {
+        try {
+            return text(await osa("system info"));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@mrfentmen/applescript-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AppleScript MCP: run, compile, inspect and control macOS apps with 14 real tools.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/applescript-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "applescript-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test tests/tools.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "applescript",
+    "macos",
+    "automation",
+    "osascript"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/applescript-mcp",
+  "description": "AppleScript MCP: run, compile, inspect and control macOS apps with 14 real tools.",
+  "repository": {
+    "url": "https://github.com/mrfentmen/awesome-servers/tree/main/mcp/servers/applescript-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@mrfentmen/applescript-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}