JCAppleScript

JCAppleScript

macOS アプリケーションから AppleScript を実行するための Swift パッケージです。AI アシスタントが事前構築されたコマンドショートカットを通じて macOS アプリを制御できる、MCP サーバーを内蔵しています。

概要

JCAppleScript は 3 つのコンポーネントを提供します。

1. JCAppleScript (ライブラリ) - コアとなる AppleScript 実行エンジン
2. AppShortcuts (ライブラリ) - 主要な macOS アプリ向けの事前構築された AppleScript コマンドのレジストリ
3. jcas-mcp (実行ファイル) - AI 駆動のアプリ自動化のための MCP (Model Context Protocol) サーバー

インストール

Swift Package Manager

Package.swift に JCAppleScript を追加します。

dependencies: [
    .package(url: "https://github.com/johnnyclem/JCAppleScript.git", from: "2.0.0")
]

次に、必要なターゲットを追加します。

.target(
    name: "YourTarget",
    dependencies: [
        "JCAppleScript",     // Core engine only
        "AppShortcuts",      // App command registry
    ]
)

クイックスタート

コアエンジンの使用

import JCAppleScript

let engine = AppleScriptEngine.shared

// Execute raw AppleScript
let result = try engine.execute("""
    tell application "Finder"
        display dialog "Hello from Swift!"
    end tell
""")

// Send a command to an application
let output = try engine.tell(application: "Music", command: "play")

// Execute a script file with variable substitution
let fileResult = try engine.executeFile(at: "/path/to/script.scpt", variables: ["Alice", "Hello!"])

// Execute JavaScript for Automation (JXA)
let jxa = try engine.execute("Application('Music').play()", language: .javaScript)

// Check syntax without executing
try engine.checkSyntax("tell application \"Finder\" to activate")

// All execution APIs also have async variants
let asyncResult = try await engine.execute("return 40 + 2")

信頼できない値をスクリプトのソースに埋め込む場合は、まずそれらをエスケープしてください。

let userInput = "…"
let script = "display dialog \(AppleScriptString.quoted(userInput))"

アプリショートカットの使用

import AppShortcuts

let registry = AppRegistry.shared

// Execute a pre-built command
let result = try registry.executeCommand("messages.send_message", arguments: [
    "recipient": "+15551234567",
    "message": "Hello from JCAppleScript!"
])

// Discover available commands
let commands = registry.commands(forApp: "Reminders")
for cmd in commands {
    print("\(cmd.id): \(cmd.name) - \(cmd.description)")
}

// Search across all apps
let results = registry.searchCommands("send")

MCP サーバーの使用

jcas-mcp 実行ファイルは、AI アシスタント (Claude、GPT など) が macOS アプリケーションを制御するために使用できる Model Context Protocol サーバーです。

これは io.github.johnnyclem/jcas-mcp として公式 MCP レジストリに公開されており、各 GitHub リリースにはビルド済みの jcas-mcp.mcpb バンドル (ユニバーサル macOS バイナリ) が同梱されており、Claude Desktop の設定 → 拡張機能から直接インストールできます。

Claude Desktop でのセットアップ

Claude Desktop の設定 (~/Library/Application Support/Claude/claude_desktop_config.json) に追加します。

{
  "mcpServers": {
    "applescript": {
      "command": "/path/to/jcas-mcp"
    }
  }
}

サーバーをビルドします。

swift build -c release
# Binary at: .build/release/jcas-mcp

利用可能な MCP ツール

ツール	説明
execute_applescript	任意の AppleScript コードを実行します †
execute_jxa	JavaScript for Automation (JXA) コードを実行します †
tell_application	tell ブロックを介して特定のアプリにコマンドを送信します †
check_script_syntax	スクリプト (AppleScript または JXA) を実行せずにコンパイルします
list_running_applications	現在実行中のアプリケーションを取得します
list_registered_apps	登録されているすべてのアプリコマンドシートを閲覧します
search_commands	キーワードでコマンドを検索します
run_app_command	ID で事前構築されたコマンドを実行します
preview_app_command	ドライラン: コマンドが実行する正確なスクリプトを表示します
get_app_commands	特定のアプリの詳細なコマンド情報を取得します

† サーバーがセーフモードで実行されている場合は非表示になり、無効化されます (以下を参照)。

サーバー設定

環境変数	効果
JCAS_SAFE_MODE=1	任意コード実行ツール (execute_applescript、execute_jxa、tell_application) と、dangerous とフラグ付けされたレジストリコマンド (例: terminal.run_command、safari.run_javascript) を無効化します。事前構築されたサニタイズ済みのレジストリコマンドのみが利用可能なまま残ります。
JCAS_APP_MANIFESTS=a.json:b.json	起動時に読み込む追加のコミュニティアプリ定義を含む、コロン区切りの JSON マニフェストファイル。

CLI フラグ: jcas-mcp --manifest は完全なレジストリを JSON として出力し、--version はサーバーのバージョンを出力し、--help は使用方法を表示します。

AI との対話例

User: "Send a message to John saying I'll be late"
AI uses tool: run_app_command
  command_id: "messages.send_message"
  arguments: { "recipient": "John", "message": "I'll be late" }

対応アプリケーション

JCAppleScript には、12 個の組み込み macOS アプリ用のコマンドシートが同梱されています:

アプリ	カテゴリ	コマンド数	例
Messages	コミュニケーション	6	メッセージの送信、チャットの一覧表示、参加者の取得
Mail	コミュニケーション	7	メールの作成、検索、メールの確認、アカウントの一覧表示
Reminders	生産性	7	リマインダーの作成／完了／削除、検索、一覧表示
Calendar	生産性	6	イベントの作成、今日のイベントの一覧表示、今後の予定
Notes	生産性	8	ノートの作成／検索／追記、フォルダの管理
Finder	システム	12	ファイル操作、フォルダの内容、ラベル、ゴミ箱
Safari	インターネット	10	URL を開く、タブの管理、JavaScript の実行、ページコンテンツの取得
Music	メディア	13	再生コントロール、プレイリスト、ライブラリ検索、評価
Terminal	開発	8	コマンドの実行、ウィンドウ／タブの管理、プロファイル
System Settings	システム	13	ダークモード、音量、通知、ダイアログ、システム情報
Xcode	開発	20+	プロジェクトのオープン／ビルド／実行／テスト、スキーム、ビルドログ、デバッグ
Speech Recognition	システム	3	システムの音声エンジンを介した発話フレーズの認識

カスタムアプリのサポート追加

ScriptableApp プロトコルを実装することで、スクリプト対応のあらゆる macOS アプリのサポートを追加できます:

import AppShortcuts

struct MyApp: ScriptableApp {
    static let bundleIdentifier = "com.example.myapp"
    static let appName = "MyApp"
    static let description = "My custom application"
    static let category = AppCategory.productivity

    static let commands: [AppCommand] = [
        AppCommand(
            id: "myapp.do_thing",
            name: "Do Thing",
            description: "Performs the thing",
            parameters: [
                CommandParameter(name: "input", description: "The input value"),
            ]
        ) { args in
            let input = args["input", default: ""]
            return """
            tell application "MyApp"
                do thing with "\(input)"
            end tell
            """
        },
    ]
}

// Register at runtime
AppRegistry.shared.register(MyApp.self)

コミュニティアプリレジストリ

JCAppleScript は、コミュニティからのコントリビューションによって成長するように設計されています。アプリショートカットシステムは標準プロトコル（ScriptableApp）を使用しており、次のことを容易にします:

• 新しいアプリケーションの追加 - スクリプト対応のあらゆる macOS アプリに対して ScriptableApp を実装します
• 既存アプリの拡張 - すでに登録されているアプリに新しいコマンドを投稿します
• コマンドシートの共有 - JSON マニフェストを介してアプリ定義をエクスポート／インポートします

私たちは、次のことができる閲覧可能なレジストリ（npmjs.org に似たもの）を構築しています:

• アプリケーションと、それらがサポートする AppleScript コマンドを閲覧する
• 既存のアプリに新しいコマンドを投稿する
• まったく新しいアプリケーションをレジストリに追加する
• 他のツールとの統合用に JSON マニフェストを生成する

レジストリのエクスポートとインポート

// Export all registered apps as manifest JSON
let json = try AppRegistry.shared.exportManifestJSON()

// Import community app definitions from a JSON manifest.
// Manifest commands are declarative script templates with ${param}
// placeholders; argument values are sanitized before substitution.
try AppRegistry.shared.loadManifest(contentsOf: URL(fileURLWithPath: "community.json"))

マニフェストの例:

[
  {
    "name": "CoolApp",
    "bundleIdentifier": "com.example.coolapp",
    "description": "A community-contributed app",
    "category": "Productivity",
    "commands": [
      {
        "id": "coolapp.greet",
        "name": "Greet",
        "description": "Show a greeting",
        "script": "tell application \"CoolApp\"\n    greet \"${who}\"\nend tell",
        "parameters": [
          {"name": "who", "description": "Who to greet", "required": true, "type": "string"}
        ]
      }
    ]
  }
]

MCP サーバーは、起動時に JCAS_APP_MANIFESTS 環境変数から追加のマニフェストを読み込みます。

セキュリティモデル

レジストリのコマンド引数は、スクリプト生成の前にサニタイズされます:

• 文字列、ファイルパス、日付の引数はエスケープされ（\、"、および制御文字）、AppleScript の文字列リテラルから抜け出せないようになります。
• 整数およびブール値の引数は厳密に検証／正規化されます — 不正な値は検証時に拒否され、生成時には宣言されたデフォルト値にフォールバックします。
• パラメータの allowedValues リストに含まれない値は破棄されます。
• 宣言されたパラメータに対応しない引数は破棄されます。

呼び出し元が指定したコードを実行するコマンド（Terminal のシェルコマンド、Safari の JavaScript）は dangerous としてフラグ付けされ、JCAS_SAFE_MODE=1 で一括して無効化できます。preview_app_command ツールを使用すると、コマンドを実行する前に、そのコマンドが実行する正確なスクリプトを確認できます。

なお、execute_applescript、execute_jxa、tell_application は設計上、任意のコードを実行します — 信頼できるクライアントにのみ公開するか、サーバーをセーフモードで実行してください。

アーキテクチャ

JCAppleScript/
├── Sources/
│   ├── JCAppleScript/           # Core engine
│   │   ├── AppleScriptEngine.swift
│   │   ├── AppleScriptSanitizer.swift
│   │   ├── ScriptResult.swift
│   │   └── ScriptError.swift
│   ├── AppShortcuts/            # App command registry
│   │   ├── AppProtocol.swift    # ScriptableApp protocol
│   │   ├── AppCommand.swift     # Command & parameter types + sanitization
│   │   ├── AppDefinition.swift  # Instance-based app description
│   │   ├── AppManifest.swift    # JSON import/export
│   │   ├── AppRegistry.swift    # Central registry
│   │   └── Apps/                # Built-in app sheets
│   │       ├── MessagesApp.swift
│   │       ├── RemindersApp.swift
│   │       ├── FinderApp.swift
│   │       ├── SafariApp.swift
│   │       ├── MailApp.swift
│   │       ├── CalendarApp.swift
│   │       ├── NotesApp.swift
│   │       ├── MusicApp.swift
│   │       ├── TerminalApp.swift
│   │       └── SystemSettingsApp.swift
│   └── JCAppleScriptMCP/       # MCP server
│       ├── main.swift
│       ├── MCPServer.swift
│       ├── MCPTransport.swift
│       └── MCPTypes.swift
├── Tests/
├── Legacy/                      # Original Obj-C implementation
├── Package.swift
└── LICENSE

要件

• macOS 13.0+
• Swift 5.9+

レガシー

オリジナルの Objective-C 実装（2013 年）は、参照用として Legacy/ ディレクトリに保存されています。これは、変数置換を伴う基本的な NSAppleScript のラッピングを提供していました。新しい Swift 実装は、それらのコンセプトを基に構築しつつ、MCP サーバー、アプリレジストリ、およびモダンな Swift パターンを追加しています。

ライセンス

MIT License - Copyright (c) 2013 John Clem。詳細は LICENSE を参照してください。