AppleScript MCP 服务器
一个模型上下文协议（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 | sh2. 在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 .env2. 配置环境
编辑 .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 minutes3. 运行服务器
# Development mode (with auto-reload)
deno task dev
# Production mode
deno task start4. 在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做出贡献
欢迎投稿：
- 为仓库创建分支
- 创建一个特性分支
- 为新功能添加测试
- 提交拉取请求
许可证
MIT 许可证 - 详情请参阅 LICENSE 文件
相关项目
- bb-mcp-server 翻译成中文是：“bb-MCP服务器”为这个项目提供支持的MCP服务器库
- 模型上下文协议协议规范
支持
- 问题:
- 讨论：
- 库文档： bb-mcp-server 文档
______________________________________________________________________
使用（某种材料/技术）建造 @beyondbetter/bb-mcp-server 翻译成中文可以是：“超越更好的 bb-mcp 服务器”。不过，这里的“beyondbetter”可能是一个特定项目或公司的名称，直接翻译可能无法准确传达其原意，因此在实际应用中，可能需要根据上下文或品牌的具体含义来调整翻译。如果“beyondbetter”是品牌名，且没有官方中文译名，通常会保留原英文名称，或者根据品牌的核心理念进行意译 - 一个强大的框架，用于构建支持插件、工作流和OAuth的MCP服务器。