AppleScript MCP 服务器

![Beyond Better](https://beyondbetter.app) ![MCP Server](https://github.com/Beyond-Better/bb-mcp-server)

![JSR](https://jsr.io/@beyondbetter/bb-applescript-mcp-server) ![JSR Score](https://jsr.io/@beyondbetter/bb-applescript-mcp-server) ![JSR Scope](https://jsr.io/@beyondbetter) ![License: MIT](https://opensource.org/licenses/MIT)

一个模型上下文协议（MCP）服务器，它使大型语言模型（LLM）客户端能够通过AppleScript与macOS应用程序进行交互。该服务器是使用（后续内容未给出，但基于前文，可推测为“某种技术或框架构建的”）构建的 @beyondbetter/bb-mcp-server 翻译为中文可以是：“超越更好的/bb-mcp服务器” 或者根据上下文简化为 “超越更好（项目/组织）的MCP服务器”，具体翻译可能需要根据“beyondbetter”和“bb-mcp-server”在实际应用中的具体含义来调整。如果“beyondbetter”是一个特定项目或组织的名称，那么翻译时可能需要保留其原名或采用官方翻译。同样，“mcp-server”也可能是一个特定技术或服务的名称，需要根据实际情况来确定最准确的翻译该服务器提供安全、受控的预定义脚本执行环境，并可选地支持任意脚本执行。

特点/功能

🔒 默认安全默认情况下禁用任意脚本执行
📦 插件架构模块化设计，配备任务导向的插件
🛠️ 标准工具阅读字典，检查权限，Finder 操作
📝 BBEdit 集成创建笔记本和项目
⏱️ 超时保护可配置的超时设置，带有硬性限制
📄 结构化错误与大型语言模型（LLM）友好的提示相结合的一致错误处理
📊 性能支持编译脚本和基于模板的脚本

先决条件

Deno（注：Deno是一个JavaScript和TypeScript运行时，由Ryan Dahl开发，可直接在浏览器或服务器上运行，此处仅作为名称翻译，不涉及具体功能或背景介绍）版本2.5.0或更高版本
macOS（发音为 /ˈmækOS/，中文常直接称为“苹果电脑操作系统”或简称“苹果系统”）执行AppleScript所需
应用程序任何支持AppleEvents的macOS应用程序（可脚本化应用程序）

- 示例：Finder（内置）、BBEdit、Mail、Safari 等。 - 此服务器默认包含Finder和BBEdit的插件 - 你可以为任何可脚本化的应用程序创建插件

快速入门

选项1：直接从JSR运行（推荐）

无需安装！ 只需Deno和一个配置文件。

1. 安装Deno（如需）

curl -fsSL https://deno.land/install.sh | sh

2. 在Beyond Better中进行配置

全局配置 （适用于所有项目）：

打开BB设置
转到“MCP 服务器”选项卡
点击“配置服务器”
添加新服务器，使用：

- 服务器ID： applescript - 显示名称： AppleScript Tools - 运输类型: STDIO (Local Process) - 命令： deno - 论点；论据：

     run
     --allow-all
     --unstable-kv
     jsr:@beyondbetter/bb-applescript-mcp-server

项目级配置 （仅限特定项目）：

在BB中打开你的项目
前往项目设置 → “MCP 服务器”
启用服务器以供 AppleScript Tools

3. 开始使用

就是这样！服务器直接从JSR运行，无需下载或安装。

Alternative: Claude Desktop Configuration

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
	"mcpServers": {
		"applescript": {
			"command": "deno",
			"args": [
				"run",
				"--allow-all",
				"--unstable-kv",
				"jsr:@beyondbetter/bb-applescript-mcp-server"
			]
		}
	}
}

重启Claude桌面应用。

4. 可选：配置

默认情况下，服务器以安全默认设置运行：

任意脚本执行： 残疾的
所有标准插件：启用
默认超时设置： 30秒默认，最长5分钟

要进行自定义，请在BB的MCP服务器配置中添加环境变量：

在BB设置 → MCP服务器 → 编辑服务器 → 环境变量中：

关键字	值	描述
`LOG_LEVEL`	`info`	设置为 `debug` 用于查看详细日志
`ENABLE_ARBITRARY_SCRIPTS`	`false`	设置为 `true` 启用 run_script 工具
`PLUGINS_ALLOWED_LIST`	（空）	逗号分隔的列表，用于加载特定插件
`PLUGINS_BLOCKED_LIST`	（空）	用逗号分隔的列表，用于阻止插件

选项2：从本地仓库运行

对于开发或定制：

1. 克隆并设置

# Clone the repository
git clone https://github.com/your-username/bb-mcp-applescript.git
cd bb-mcp-applescript/server

# Copy environment template
cp .env.example .env

2. 配置环境

编辑 .env 进行定制：

# Basic Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=info

# Plugin Control
PLUGINS_ALLOWED_LIST=        # Empty = load all plugins
PLUGINS_BLOCKED_LIST=        # Block specific plugins

# Safety (IMPORTANT)
ENABLE_ARBITRARY_SCRIPTS=false  # Set to true to enable run_script tool

# Timeouts
APPLESCRIPT_TIMEOUT_DEFAULT=30000   # 30 seconds
APPLESCRIPT_TIMEOUT_MAX=300000      # 5 minutes

3. 运行服务器

# Development mode (with auto-reload)
deno task dev

# Production mode
deno task start

4. 在Beyond Better中进行配置

全局配置：

打开BB设置（或项目设置）
转到“MCP 服务器”选项卡
添加新服务器：

- 服务器ID： applescript - 显示名称： AppleScript Tools (Local Dev) - 运输类型： STDIO (Local Process) - 命令： deno - 论点；论据：

     run
     --allow-all
     --unstable-kv
     /absolute/path/to/bb-mcp-applescript/server/main.ts

- 环境变量 （可选）： - LOG_LEVEL： debug - ENABLE_ARBITRARY_SCRIPTS： false

Alternative: Claude Desktop Configuration

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
	"mcpServers": {
		"applescript": {
			"command": "deno",
			"args": [
				"run",
				"--allow-all",
				"--unstable-kv",
				"/absolute/path/to/bb-mcp-applescript/server/main.ts"
			]
		}
	}
}

重启Claude桌面应用。

项目结构

server/
├── main.ts                          # Server entry point
├── deno.jsonc                       # Deno configuration
├── .env.example                     # Environment template
├── mcp_server_instructions.md       # LLM context/instructions
├── src/
│   ├── plugins/
│   │   ├── standard.plugin/         # Standard tools plugin
│   │   │   ├── plugin.ts            # Plugin implementation
│   │   │   └── scripts/             # AppleScript files
│   │   │       ├── read_dictionary.applescript
│   │   │       ├── check_permissions.applescript
│   │   │       └── finder/
│   │   │           ├── set_file_label.applescript
│   │   │           ├── get_file_label.applescript
│   │   │           ├── get_file_info_extended.applescript
│   │   │           ├── reveal_in_finder.applescript
│   │   │           └── get_selection.applescript
│   │   └── bbedit.plugin/           # BBEdit tools plugin
│   │       ├── plugin.ts
│   │       └── scripts/
│   │           ├── create_notebook.applescript
│   │           └── create_project.applescript
│   └── utils/
│       ├── scriptLoader.ts          # Script loading/discovery
│       ├── scriptRunner.ts          # Script execution
│       ├── templateRenderer.ts      # Template interpolation
│       └── errorHandler.ts          # Error standardization
└── tests/

可用工具

AppleScript 工具（标准插件）

🔧 运行脚本

状态默认禁用

执行任意 AppleScript 代码。

启用设置 ENABLE_ARBITRARY_SCRIPTS=true 在里面 .env

参数：

script执行AppleScript代码
timeout可选的超时时间（以毫秒为单位）

示例:

{
  script: 'tell application "Finder" to get name of startup disk',
  timeout: 5000
}

📖 读取字典

阅读一个应用程序的AppleScript词典，以了解其可脚本化的接口。

参数：

application应用程序名称（例如，“BBEdit”，“Finder”）
filter可选的过滤条件

- include.types要包含的类型数组 - include.names需包含的具体名称 - searchTerms模糊匹配的条件/术语 - format“full”或“summary”（默认：“summary”）

timeout可选的超时设置

示例:

{
  application: "BBEdit",
  filter: {
    include: { names: ["project", "notebook"] },
    searchTerms: ["create"],
    format: "summary"
  }
}

✅ 检查AppleScript权限

检查应用程序的自动化权限。

参数：

applications可选的应用程序名称数组（默认：\["Finder", "BBEdit", "Terminal"\]）
timeout可选的超时时间

回报每个应用程序的权限状态，如有需要，附上说明。

Finder 工具（标准插件）

🏷️ 设置文件标签

为文件/文件夹设置Finder标签颜色。

参数：

paths文件/文件夹路径数组
labelIndex0=无，1=红色，2=橙色，3=黄色，4=绿色，5=蓝色，6=紫色，7=灰色
timeout可选的超时时间

🏷️ 获取文件标签

获取文件/文件夹的Finder标签颜色。

参数：

paths文件/文件夹路径数组
timeout可选超时时间

📊 获取文件详细信息

获取包含Spotlight注释、标签、标签等详细文件信息。

参数:

path文件或文件夹路径
timeout可选的超时时间

🔍 在Finder中显示

在Finder中显示并选择文件/文件夹。

参数：

paths要揭示的路径数组
timeout可选超时时间

📋 获取查找器选择项

获取Finder中当前选中的项目。

参数：

timeout可选超时时间

BBEdit 工具（BBEdit 插件）

📓 创建BB编辑笔记本

创建一个新的BBEdit笔记本。

参数：

name笔记本名称（必填）
location可选的保存位置（默认：~/Documents/BBEdit 笔记本/）
content可选的内容项数组

- type“文本”或“文件” - data文本内容或文件路径

open创建后是否自动打开（默认：true）
timeout可选的超时时间

示例：

{
  name: "Project Notes",
  content: [
    { type: "text", data: "Meeting notes..." },
    { type: "file", data: "/path/to/notes.txt" }
  ],
  open: true
}

📁 创建_bbedit项目

创建一个新的BBEdit项目。

参数：

name项目名称（必填）
location可选保存位置（默认：~/Documents/BBEdit Projects/）
items可选的文件/文件夹路径数组，用于添加
settings可选的项目设置（保留以供将来使用）
open创建后是否自动打开（默认：true）
timeout可选超时时间

示例：

{
  name: "Website Project",
  items: [
    "/Users/username/Projects/website/src",
    "/Users/username/Projects/website/docs"
  ],
  open: true
}

插件管理

插件加载策略

这台服务器使用的是 混合插件加载方法 自动适应运行时环境：

JSR模式当从JSR（例如。， jsr:@beyondbetter/bb-applescript-mcp-server):

- 内置插件（standard-tools、bbedit）是静态加载的 - 用户插件可以通过本地目录加载 PLUGINS_DISCOVERY_PATHS - 允许用户通过自定义插件扩展服务器功能

- 内置插件作为备用方案被静态加载 - 默认启用动态发现 - 在开发过程中支持热重载

服务器会自动检测其运行模式，并相应地配置插件加载。无需任何配置，即开即用！

📖 关于技术细节，见插件加载文档

添加自定义插件

即使在通过JSR运行时，您也可以添加自己的插件：

创建一个插件目录： mkdir ~/my-applescript-plugins
添加您的插件文件（参见插件指南)
设置环境变量： PLUGINS_DISCOVERY_PATHS=/path/to/your/plugins
重启服务器

您的自定义插件将与内置插件一起被发现并加载。

加载插件

插件会自动从（指定位置）发现 src/plugins/ 目录（本地模式）或静态加载（JSR模式）。

加载所有插件 （默认）：

PLUGINS_ALLOWED_LIST=
PLUGINS_BLOCKED_LIST=

仅加载特定插件：

PLUGINS_ALLOWED_LIST=standard,bbedit
PLUGINS_BLOCKED_LIST=

加载除特定插件外的所有插件：

PLUGINS_ALLOWED_LIST=
PLUGINS_BLOCKED_LIST=experimental

创建自定义插件

插件允许您为任何可脚本化的 macOS 应用程序添加工具。请参阅完整指南：

📝 翻译成中文是：📝（这个符号本身没有直接对应的中文翻译，它通常表示“笔记”或“待办事项”等意思，具体含义需结合上下文理解。）创建插件指南

Mail.app 插件的快速示例：

// src/plugins/mail.plugin/plugin.ts
import { AppPlugin, ToolRegistry, z } from 'jsr:@beyondbetter/bb-mcp-server';
import { findAndExecuteScript } from '../../utils/scriptLoader.ts';

export default {
	name: 'mail',
	version: '1.0.0',
	description: 'Tools for Mail.app',
	workflows: [],
	tools: [],

	async initialize(dependencies, toolRegistry, workflowRegistry) {
		const pluginDir = getPluginDir();
		
		toolRegistry.registerTool(
			'send_email',
			{
				title: 'Send Email',
				description: 'Create an email in Mail.app',
				category: 'Mail',
				inputSchema: {
					to: z.string().email().describe('Recipient'),
					subject: z.string().describe('Subject'),
					body: z.string().describe('Body'),
				},
			},
			async (args) => {
				// Runs scripts/send_email.applescript with template variables
				return await findAndExecuteScript(
					pluginDir,
					'send_email',
					{ to: args.to, subject: args.subject, body: args.body }
				);
			},
		);
	},
} as AppPlugin;

该指南涵盖：

插件结构和文件命名
AppleScript 模板变量
每个插件对应多个工具
错误处理和调试
完整的可运行示例

脚本开发

模板脚本

在（某处）使用模板变量 .applescript 文件：

-- my_script.applescript
tell application "Finder"
    set file label of (POSIX file ${filePath} as alias) to ${labelIndex}
end tell

变量会自动进行转义和类型转换：

字符串用引号括起来，已转义
数组转换为AppleScript列表： {"item1", "item2"}
物体；对象转换为AppleScript记录： {key:"value"}
空/未定义转换为 missing value

编译脚本

为了获得更好的性能，请使用编译后的脚本：

# Compile an AppleScript
osacompile -o my_script.scpt my_script.applescript

编译后的脚本无需编译开销即可直接运行。

错误处理

所有工具返回一致的错误结构：

{
	"success": false,
	"error": {
		"type": "permission|timeout|script_error|system_error|disabled",
		"message": "Human-readable error",
		"code": "ERR_CODE",
		"hint": "LLM-friendly suggestion",
		"details": "Technical details"
	},
	"metadata": {
		"executionTime": 123,
		"scriptPath": "/path/to/script",
		"timeoutUsed": 30000
	}
}

常见问题

权限被拒绝

解决方案授予自动化权限

使用 check_applescript_permissions 确定哪些应用程序需要权限
进入系统设置 > 隐私与安全 > 自动化
为MCP服务器进程启用自动化

脚本超时

解决方案增加超时时间或优化脚本

设定得更高 timeout 参数
检查 APPLESCRIPT_TIMEOUT_MAX 配置
将复杂操作分解为更小的脚本

禁用运行脚本

解决方案在配置中启用

设置 ENABLE_ARBITRARY_SCRIPTS=true 在里面 .env
重启服务器
注意安全影响

安全考虑因素

🔒 随意脚本默认情况下禁用。仅在信任LLM客户端时启用。
📁 文件系统脚本以服务器进程权限运行。
🎯 应用程序控制可以控制任何已授予自动化权限的应用程序。
⏱️ 超时限制始终强制执行以防止脚本失控。
📝 错误详情可能包含系统信息。请检查错误输出。

性能优化技巧

使用 编译后的脚本 (.scpt) 对于常用操作
设定；套装 适当的暂停时间 基于操作复杂性
批处理操作 在可能的情况下（例如，一次性处理多个文件）
缓存结果 用于只读操作（例如，字典读取）

测试

# Run tests
deno task test

# Run specific test file
deno test tests/scriptRunner.test.ts

做出贡献

这是一个展示示例，用于 @beyondbetter/bb-mcp-server 翻译为中文是：“超越更好的/bb-mcp服务器”。不过，这里的“beyondbetter”可能是一个特定项目或组织的名称，如果它有官方的中文译名，应该使用那个译名。同时，“bb-mcp-server”也可能是一个特定技术或服务的名称，具体翻译可能需要根据上下文或官方资料来确定。在没有具体上下文的情况下，上述翻译是一个较为通用的表述图书馆。

欢迎投稿：

为仓库创建分支
创建一个特性分支
为新功能添加测试
提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

支持

问题:
讨论：
库文档： bb-mcp-server 文档

______________________________________________________________________

使用（某种材料/技术）建造 @beyondbetter/bb-mcp-server 翻译成中文可以是：“超越更好的 bb-mcp 服务器”。不过，这里的“beyondbetter”可能是一个特定项目或公司的名称，直接翻译可能无法准确传达其原意，因此在实际应用中，可能需要根据上下文或品牌的具体含义来调整翻译。如果“beyondbetter”是品牌名，且没有官方中文译名，通常会保留原英文名称，或者根据品牌的核心理念进行意译 - 一个强大的框架，用于构建支持插件、工作流和OAuth的MCP服务器。

Bb Applescript MCP Server

快速接入

详细介绍