Logic Pro MCP

适用于 Claude、Cursor 和 AI Agent 的 Logic Pro MCP 服务

一个本地模型上下文协议（MCP）服务，可让 Claude Code、Claude Desktop、Cursor、Codex、VS Code 和其他 MCP 客户端控制 Logic Pro 进行 AI 音乐制作：创建音轨、编写 MIDI、操作传输和混音器状态、检查实时项目数据，并验证结果。

安装 · 观看演示 · 控制内容

🏆 入选 Anthropic 的 Claude 开源项目计划

Logic Pro MCP 已 正式入选 Anthropic 的 Claude 开源项目计划——这是 Claude 的开发者对该项目作为值得支持的开源工作的认可。此服务由 Claude 构建，供由 Claude 驱动的 Agent 使用——现已获得该计划的官方支持。

一个由 MCP 在 Logic Pro 12.3 中实时创作的 82 BPM D 小调 lo-fi 循环——速度、三个 MIDI 部分、一位鼓手和播放，全部通过提示词完成。
▶ 观看 36 秒演示（含声音）

---

Logic Pro MCP 服务为 Claude、Cursor、Codex 和其他 MCP 客户端提供了一种结构化方式来控制 Logic Pro，无需脆弱的键盘宏。Logic Pro 并未提供用于 Agent 创作、会话设置、混音器操作或实时项目读取的官方 API，因此 Logic Pro MCP 通过将 7 种原生 macOS 控制通道（CoreMIDI、辅助功能、AppleScript、CGEvent、MCU、Scripter、MIDI 键盘命令 — Sources/LogicProMCP/Channels/Channel.swift）整合到一个 MCP 接口中，填补了这一空白，并为每项高风险操作都设置了明确的状态、确认和验证契约。

这并不是“用提示词进行屏幕自动化”，而是一个面向 DAW Agent 的结构化服务：工具负责修改，资源负责读取，证据会标注，不确定的结果会如实保持不确定，而不会被报告为成功。

You: "Make a 4-bar techno loop in A minor at 140 BPM"

MCP client → logic_tracks.record_sequence {
  bar: 1, tempo: 140,
  notes: "45,0,95;57,107,95;45,214,95;..."
}
MCP client → logic_tracks.set_instrument {
  index: 0, path: "Electronic Drums/Roland TR-909"
}

Logic Pro MCP: region imported, instrument routed, readback exposed through resources.

概览

以下计数通过所示命令从当前源代码树中读取；拉取更新后重新运行即可复现。

界面	当前源代码树	命令
MCP 工具	10 个工具 — logic_transport、logic_tracks、logic_mixer、logic_midi、logic_edit、logic_navigate、logic_project、logic_audio、logic_system、logic_plugins	grep -c '^ toolWithOutputSchema' Sources/LogicProMCP/Server/LogicProServer.swift
读取资源	19 个静态资源 — health、transport、已打开的 Tempo List、tracks、mixer、markers、项目信息/审计/清理计划、MIDI 端口、MCU 状态、资源库清单、内置插件/清单/功能、内置乐器、Session Players、工作流技能/架构	awk '/private static let baseResources/,/^\]/' Sources/LogicProMCP/Resources/ResourceProvider.swift | grep -c 'uri:'
资源模板	12 个模板 — 操作目录、音轨、片段、混音器通道条、内置插件详情/搜索、内置乐器详情/搜索、Session Player 详情、会话计划试运行、工作流详情/搜索	awk '/private static let baseTemplates/,/^\]/' Sources/LogicProMCP/Resources/ResourceProvider.swift | grep -c 'uriTemplate:'
控制通道	7 个 — CoreMIDI、Accessibility、CGEvent、AppleScript、MCU、MIDIKeyCommands、Scripter	grep -n 'case .* = "' Sources/LogicProMCP/Channels/Channel.swift
Logic 随附的语言区域	10 个 — de-DE en-US es-ES fr-FR it-IT ja-JP ko-KR pt-BR zh-CN zh-TW	python3 -c "import json; print(json.load(open('docs/locale/ui-labels.json'))['supported_locales'])"
支持的 Logic Pro	优先使用最新的 Logic Pro — 桌面版 Logic Pro（com.apple.logic10、/Applications/Logic Pro.app）。Apple Creator Studio Logic Pro Creator Studio（com.apple.mobilelogic、/Applications/Logic Pro Creator Studio.app）可被识别，但不受支持。桌面版 Logic Pro 是发布资格矩阵涵盖的唯一变体（shipVariants = [.desktop]），也是此版本支持的唯一变体。未设置 LOGIC_PRO_BUNDLE_ID 时，服务仍可能选择 Creator Studio：它会以最前台的 Logic 为目标；若没有，则选择一个正在运行的 Logic，再否则选择一个已安装的 Logic，这两种情况下都会优先选择桌面版。因此，如果 Creator Studio 位于最前台，或是唯一正在运行的 Logic，它就会成为目标，但没有任何资格验证证据作为依据。设置 LOGIC_PRO_BUNDLE_ID=com.apple.logic10 可让服务始终使用桌面版 Logic Pro。Logic Pro 12.3 是当前主动验证的目标（macOS 15.6+）；对低至 12.0.1 的旧版本则尽力支持
发布状态	当前稳定版：v3.18.0 — v3.18.0

如果这个项目能帮助你使用 Claude、Cursor、Codex 或任何 MCP 客户端创作音乐，请为仓库点亮星标。这有助于项目触达更多 Logic Pro 用户和维护者。

想要贡献？请从贡献指南和未解决的问题开始。许多文档、示例、验证测试和 CLI 消息改进都不需要 Logic Pro。

项目缘起

大多数 Logic Pro 自动化尝试都会陷入以下三种误区之一：

1. 仅依赖提示词的方案，容易偏离实际工具功能。
2. 键盘宏自动化，可能点错目标，却看起来仍然成功。
3. 单通道控制，可以向 Logic 写入，却无法可靠读取 Logic 实际执行的操作。

Logic Pro MCP 使用不同的模式。它会将每项操作路由到最强大的可用通道，通过 MCP 资源公开实时状态，并要求调用方处理三种结果：已确认、不确定或失败。

控制范围

区域	Agent 可以执行的操作	安全/回读模型
传输	播放、停止、录制、定位、循环、节拍器、速度	通过 CoreMIDI/AX 路由，并实时读取 logic://transport/state
轨道	创建、删除、复制、选择、重命名、静音、独奏、录音准备、设置乐器	修改目标必须明确指定索引/名称；选择不确定时会在写入前安全失败
MIDI 编曲	在服务端生成 SMF、导入 MIDI、发送音符/CC/MMC、创建虚拟端口	.mid 导入仅限服务管理的临时文件，且必须创建实时轨道
混音器	音量、声像、插件快照、受保护的内置插件插入、由 MCU 驱动的推子组切换	AX 写入后在同一界面回读音量/声像；MCU 写入通过 LCD 上排重绘进行验证；已占用的插件插槽拒绝替换
资源库	扫描 Logic 的乐器资源库并按路径加载补丁	磁盘/AX 清单会缓存；磁盘扫描会对用户/应用程序包中的 .patch 候选项去重，而 resolve_path 会在 set_instrument 前对类型/来源/是否可加载进行分类
导航	小节、标记、缩放、视图切换	标记导航会忠实定位目标；缓存未命中时会返回失败，而不是转到“下一个标记”
项目生命周期	新建、打开、保存、另存为、关闭、弹跳、导出计划、退出；仅基于缓存生成会话内容报告	破坏性操作需要确认；导出试运行计划不会打开 Logic 或写入文件

面向 Agent 的接口

工具用于执行操作和检查本地文件。 公开的写入接口刻意保持精简：logic_transport、logic_tracks、logic_mixer、logic_plugins、logic_midi、logic_edit、logic_navigate、logic_project 和 logic_system。logic_audio 为只读，用于在 Logic 写入文件后验证导出文件。

资源用于读取状态。 客户端应读取 logic://transport/state、logic://tracks、logic://mixer、logic://project/info、logic://project/audit、logic://project/cleanup-plan、logic://midi/ports 及相关资源，而不是反复调用工具进行轮询。

证据与声明分开呈现。 README 会链接到发行版证据、当前主分支验证结果和实时媒体文件，而不会暗示命令成功就代表 Logic 状态已验证。

信任模型

• 诚实的 Contract 信封：修改操作会返回状态 A（已确认）、状态 B（不确定，附原因）或状态 C（失败，附错误）。
• 已验证的插件应用回读：logic_plugins.* 使用 HC v2（hc_schema: 2），只有在项目身份、目标轨道、物理插入槽位、插件身份和回读结果全部一致后才会返回状态 A。
• 失败关闭的目标：危险的混音器、标记、轨道、MIDI 导入和插件操作都需要明确指定目标并通过验证。
• 确认级别：破坏性/项目操作和插件插入流程都需要在执行前提供明确的确认元数据。
• 来源标签：读取接口会公开来源、时效性和证据标签，客户端无需自行猜测。
• 安装程序加固：Homebrew 会固定 SHA256；除非明确允许同源来源证明，否则 shell 安装程序会拒绝在未明确固定哈希/团队信息的情况下运行。
• 发行版声明准确：v3.18.0 是当前稳定版本线，README 中的声明均以已发布文件、发行版目录测试或明确链接的实时证据为依据。

语言区域

Logic Pro 提供 10 种 UI 语言区域，本服务默认跟踪全部 10 种（而不只是 en/ko）：de-DE、en-US、es-ES、fr-FR、it-IT、ja-JP、ko-KR、pt-BR、zh-CN、zh-TW。UI 字符串匹配（菜单项、标题标签、对话框按钮）位于 docs/locale/ui-labels.json，这是所有受语言区域影响的定位器所依据的规范索引。

203 个规范标签中的每个都带有逐语言区域的 coverage：measured（从正在运行的 Logic 窗口中读取，并记录主机、日期和 AX 角色/属性）、derived（由 Scripts/derive_label_variants.py 根据 Apple 自己的 .strings 表计算得出，并非从实时窗口读取）、unmeasured 或 retired（一个标签 headerPanHint 已被 sliderPanHint 取代，并保留在规范索引中以说明原因）。各语言区域的实测数量（共 203 个规范标签，运行 python3 -c "import json,collections; d=json.load(open('docs/locale/ui-labels.json')); c=collections.Counter(); [c.update([(l,v) for l,v in e['coverage'].items() if v=='measured']) for e in d['labels'].values()]; print(c)"）：

语言区域	实测	派生	未测量	已弃用
en-US	45	156	1	1
ko-KR	50	147	5	1
ja-JP	37	154	11	1
de-DE	44	144	14	1
es-ES	7	177	18	1
fr-FR	6	175	21	1
it-IT	6	175	21	1
pt-BR	5	178	19	1
zh-CN	7	169	26	1
zh-TW	6	166	30	1

derived 标签并非从该语言区域下正在运行的 Logic 中读取；它是 Apple 为该键提供的字符串，虽是有力参考，但并非实时观察结果。路线图（docs/roadmap/README.md）跟踪各功能的实时语言区域测试工作（混音器路由图、MCU 音库遍历、录音启用按键命令设置等），这些工作会在每种语言下针对真实 Logic 会话开展。

快速开始

前提条件：运行 MCP 服务需要 macOS 14+；需要 Logic Pro（优先支持最新版本——当前为 12.3，Apple 列出的要求是 macOS 15.6+；对最低支持版本 12.0.1 及以上的旧版 Logic 尽力提供支持），以及能够启动 stdio 服务的 MCP 客户端。已发布的 GitHub Actions/Homebrew 资源为通用版本（arm64 + x86_64），无需 Xcode。弹奏/导出使用捆绑的原生 CGEvent 辅助工具，不依赖第三方点击二进制文件。

Logic Pro 版本政策。 Logic Pro MCP 将 最新的 Logic Pro 版本作为一等支持目标 并针对该版本进行验证。Apple 发布新的 Logic Pro 版本时，支持该版本是首要任务——不同版本的辅助功能/UI 树会发生变化，因此修复会优先适配最新版本。高于最低支持版本 12.0.1 的旧版仍会尽力支持，但随着这些 UI 界面发生变化，支持一致性可能会下降。

为确保兼容性，软件包清单使用 Swift tools 6.0。当前源代码验证在 CI 中使用 Xcode 16.4 / Swift 6.2。

当前稳定版本线为 v3.18.0（于 2026-09-28 UTC 发布）。各版本的详细信息——自 v3.17.0 以来添加、更改和修复的所有内容，以及所有已声明的限制——请参阅 CHANGELOG.md；本 README 不会重复介绍版本历史。

1. 安装

brew tap MongLong0214/logic-pro-mcp https://github.com/MongLong0214/logic-pro-mcp
brew trust monglong0214/logic-pro-mcp   # Homebrew 6.0+ requires trusting third-party taps
brew install logic-pro-mcp

Homebrew formula 固定了发布 tarball URL 和 SHA256；Homebrew 本身是可信的分发渠道，具有自己的签名链。这是适用于生产安装的强化路径。（在低于 6.0 的 Homebrew 版本中，没有 brew trust 步骤——请跳过。）

如需基于源代码树进行开发，请在本地构建：

git clone https://github.com/MongLong0214/logic-pro-mcp.git
cd logic-pro-mcp
swift build -c release

升级现有安装：Homebrew 安装使用 brew update && brew upgrade logic-pro-mcp；源代码构建使用 git pull && swift build -c release；使用固定版本的 shell 安装程序安装时，请使用新版发布的固定值重新运行安装程序（见下文）。由于发布二进制文件采用临时签名（没有 Apple Developer ID；参见 SECURITY.md），macOS 会将每个新构建视为不同的签名身份——辅助功能和自动化授权不会沿用到新构建或重新安装的二进制文件，因此每次升级后都需要重新批准 TCC，而不只是长时间间隔后才需要（docs/TROUBLESHOOTING.md 介绍了如何移除过期的 TCC 条目并重新授予权限）。

2. 在 MCP 客户端中注册

Claude Code：

claude mcp add --scope user logic-pro -- LogicProMCP

通用 MCP 客户端配置（Claude Desktop、Cursor、VS Code、Codex CLI、Codex Desktop，以及其他任何接受 stdio MCP 服务条目的客户端——各客户端自己的配置文件位置和键名由该客户端说明，而非本文档说明）：

{
  "mcpServers": {
    "logic-pro": {
      "command": "LogicProMCP"
    }
  }
}

如果你是从源代码构建的，请将命令指向 .build/release/LogicProMCP。

3. 完成 Logic Pro 设置

运行本地检查：

LogicProMCP --check-permissions

然后按照 docs/SETUP.md 完成 Logic 端的两个设置步骤：

• 注册 LogicProMCP-MCU-Internal MCU 控制表面。
• 如果需要写入插件参数，请添加捆绑的 Scripter 插入效果。

Logic 12.2+ 不会自动导入旧版 Key Commands plist；捆绑的预设会作为手动 MIDI Learn 参考提供。

4. 在你的 Agent 中测试

向客户端询问：

检查 Logic Pro MCP 的运行状况，并显示所有就绪频道。

预期结果：完成全部设置后，7 个频道均为 ready；如果有意跳过 Key Commands 和 Scripter，则为 5 个。

固定版本的 shell 安装程序

该安装程序采用失败即关闭策略：如果没有明确设置 LOGIC_PRO_MCP_SHA256 + LOGIC_PRO_MCP_TEAM_ID 环境变量固定值，就会拒绝运行。它会验证下载的 LogicProMCP-macOS-universal.tar.gz 压缩包，因此请从发布版 SHA256SUMS.txt 中该压缩包对应的条目复制 SHA：

curl -fsSL https://raw.githubusercontent.com/MongLong0214/logic-pro-mcp/v3.18.0/Scripts/install.sh -o install.sh
# inspect install.sh, then:
LOGIC_PRO_MCP_SHA256=<paste LogicProMCP-macOS-universal.tar.gz SHA256SUMS entry> \
LOGIC_PRO_MCP_TEAM_ID=<paste team_id from RELEASE-METADATA.json> \
bash install.sh

如果你知情并接受同源来源验证（哈希值和 Team ID 与二进制文件来自同一发布版），请明确选择加入：

LOGIC_PRO_MCP_ALLOW_SAME_ORIGIN=1 \
bash <(curl -fsSL https://raw.githubusercontent.com/MongLong0214/logic-pro-mcp/v3.18.0/Scripts/install.sh)

有关信任级别和威胁模型，请参见 SECURITY.md §安装程序信任模型。

权限

打开 系统设置 -> 隐私与安全性：

1. 辅助功能：启用启动 LogicProMCP 的应用（Claude Code、Terminal、Cursor、Codex 或 Claude Desktop）。
2. 自动化：允许该应用控制 Logic Pro，并单独允许控制 System Events —— macOS 将其视为两项独立授权，授予 Logic Pro 权限并不意味着也授予了 System Events 权限。

如果你使用 Apple Creator Studio 版 Logic Pro（com.apple.mobilelogic），请将自动化权限与桌面版 Logic Pro（com.apple.logic10）分开授予；macOS 将它们视为不同的应用，即使在某些选择器中二者都显示为“Logic Pro”。

--check-permissions 和 LogicProMCP doctor 会将每项授权报告为三态值（granted / not_granted / not_verifiable，绝不会是单纯的布尔值），并涵盖：辅助功能、自动化 → Logic Pro、自动化 → System Events，以及 PostEvent（输入监控，是 CGEvent 弹跳/点击回退方案所必需的）。

LogicProMCP --check-permissions
LogicProMCP doctor

由于发布二进制文件采用临时签名，每次新建构建或重新安装都会在 macOS 中形成一个新的签名身份：升级后也需要重新授予辅助功能/自动化权限，而不只是首次安装时。如果重新安装后权限看起来不正确，请在系统设置中移除过期的 TCC 条目，然后重新向实际启动器应用授予权限（docs/TROUBLESHOOTING.md）。

强制指定 Logic Pro 变体

LOGIC_PRO_BUNDLE_ID=com.apple.logic10 LogicProMCP

有效值：com.apple.logic10（桌面版）和 com.apple.mobilelogic（Creator Studio）。本次发布仅对桌面版 Logic Pro 进行了验证。强制指定 com.apple.mobilelogic 仍会让服务指向 Creator Studio，但没有任何验证证据支持；如果设备上只安装了 Creator Studio 版 Logic，LogicProMCP doctor 会因原因 unshipped_variant_only 而导致 logic.installation 检查失败。

将 LogicProMCP 用作库

自 v3.17.0 起，该软件包还将 LogicProMCP 目标作为名为 LogicProMCPKit 的库产品公开，因此 Swift 应用可以链接服务器运行的同一份代码，而不必将服务器作为单独的 stdio 进程来驱动。

公开接口范围小而明确。模块几乎所有内容都是 internal，包括 Accessibility 读取器（AXLogicProElements、AXHelpers、AccessibilityChannel）、通道、状态缓存和调度器，无法通过库访问。公开内容如下：

• PluginInspector（位于 Accessibility/PluginInspector.swift）：插件窗口 Setting 菜单检查器。静态入口包括 enumerateMenuTree、parsePath、encodePath、resolveMenuPath、selectMenuPath、decodeAUVersion、findPluginWindow、identifyPlugin、openPluginWindow 和 closePluginWindow。所有会操作窗口或菜单的入口都需要调用方提供 PluginPresetProbe 或由闭包组成的 PluginWindowRuntime；模块不提供公开的生产运行时，因此这里的任何内容都不会自行访问 Logic。
• 这些入口使用的数据类型：PluginPresetNodeKind、PluginPresetNode、PluginPresetCache、PluginPresetInventory、MenuHop、PluginMenuItemInfo、ScannerWindowRecord、PluginPresetProbe、PluginWindowRuntime、PluginError、AXUIElementSendable，以及常量 maxPluginMenuDepth。
• AXPluginInstanceIdentity（位于 Accessibility/AXPluginInstanceIdentity.swift，#972）：用于插件宿主的只读清点。census(pluginName:identifierPrefix:) 返回一个 AXSnapshot，包含插入槽位中名称与该插件匹配的 Mixer 通道（序号、名称、槽位位置），以及已打开的插件编辑器窗口（标题，以及给定前缀下的首个 kAXIdentifier）；此外还会返回说明发现内容的 Diagnostics。它不会执行任何操作。可区分三种结果：带有说明的空快照、通道读取不完整（stripsReadWhole 为 false，因此序号不可信），以及编辑器窗口读取失败；后一种情况会抛出 CensusError.windowsReadFailed，而不是返回零个窗口。#972 的测量是在 Logic Pro 12.3.1 中进行的，当时 Mixer 停靠在主窗口中（X）。
• Library 清单数据模型（位于 Accessibility/LibraryAccessor.swift）：LibraryNodeKind、LibraryNode、LibraryRoot 和 TreeProbe。用于扫描和选择补丁的 LibraryAccessor 枚举是 internal，因此只有其数据模型可以访问。

依赖设置

// Package.swift
dependencies: [
    .package(url: "https://github.com/MongLong0214/logic-pro-mcp", from: "3.17.0"),
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [.product(name: "LogicProMCPKit", package: "logic-pro-mcp")]
    ),
]

import LogicProMCP

产品名称为 LogicProMCPKit；导入的模块为 LogicProMCP。from: "3.17.0" 是确保包含该产品的最低版本；所有更早的标签版本都早于该产品。

设置诊断

要让 Agent 可靠地驱动 Logic Pro，主要取决于权限和环境：TCC 授权、正确的 Logic 版本、已打开的文稿、已注册的控制表面，以及没有阻塞操作的模态窗口。LogicProMCP doctor 是一个专为此打造的一流、意图感知型就绪度平台——它不是简单检查“是否已安装”的布尔值，而是一项诊断，可告诉你哪些功能已就绪、哪些受阻、原因是什么，以及接下来该怎么做，并且绝不会对无法实际验证的内容报告就绪。

LogicProMCP doctor                 # human-readable report, color when a TTY
LogicProMCP doctor --json          # stable machine contract (schema logic_pro_mcp_doctor.v4)
LogicProMCP doctor --strict        # exit code encodes overall status (CI gate)
LogicProMCP doctor --profile core --client claude-desktop
LogicProMCP doctor --check-updates # opt-in: also checks for a newer release

意图感知型配置文件。 你无需执行永远用不到的检查。--profile 会根据你实际驱动 Logic 的方式限定必需检查的范围：core（传输控制／音轨／AX）、mixer、keycmd、legacy-scripter 或 full。--client（claude-code、claude-desktop、cursor、vscode、terminal、custom）会添加与该宿主相关的注册检查。汇总状态仅针对所选配置文件的必需检查，因此仅使用 MCU 的工作流不会因为永远不会遇到的 Scripter 缺失而被标记为不健康。

关注功能就绪情况，而不只是检查通过／失败。 每项检查都会映射到其所控制的功能（track_management、midi_import、mixer_ax、mixer_mcu、keycmd_only_ops、verified_plugin_applyback、project_lifecycle 等）。报告会告诉你*“MIDI 导入已就绪；经验证的插件回写受 PostEvent 阻止”*——这种表述能让 Agent（或操作人员）直接采取行动。

因果链——fix_plan 和 blocked_by。 失败项会按顺序列入 fix_plan（最能解除阻塞的操作排在最前），每项下游检查也会指出阻止它的上游检查（blocked_by）——这样你修复的是根因，而不是症状。headline 会重述唯一的下一步操作。

诚实是核心。 无法运行的检查（缺少功能、TCC 数据库不可读）会明确报告为 skipped，并说明原因——绝不会被悄悄算作通过。主动跳过的检查（--skip-channel <MIDIKeyCommands|Scripter>，可选 --skip-note；例如你有意未注册 Scripter）会被记录，并从就绪度评估中排除，不会伪装成就绪。TCC 检查结果会脱敏为服务／主体／状态摘要——报告中不会包含本地原始路径。

严格退出码（用于 CI／Agent 门控的 --strict）：0 正常 · 1 失败 · 2 需要手动操作 · 3 降级。代码 2／3 是状态码，不是用法错误，并且位于 sysexits.h 的取值范围之下。

一台正在进行设置的设备上的真实（已脱敏）运行结果：

{
  "schema": "logic_pro_mcp_doctor.v4",
  "doctor_profile": "core",
  "status": "failed",
  "headline": "Next action [permissions.accessibility]: Accessibility permission is not granted",
  "fix_plan": ["permissions.accessibility", "permissions.post_event_access", "install.binary_inventory"],
  "summary": { "total": 26, "passed": 15, "warnings": 1, "failed": 2, "skipped": 8, "manual": 0, "duration_ms": 333 },
  "checks": [ { "id": "binary.path", "status": "pass", "category": "installation", "severity": "info" } /* … */ ]
}

同一运行在终端中会打印分组、带颜色编码的报告，并为每项检查提供指向 docs/SETUP.md 中修复说明的锚点。完整的标志参考和每项检查的修复说明见 docs/SETUP.md；--json 输出是稳定契约，你可以在自己的入门自动化中对其进行断言。

架构概览

MCP 客户端会启动 Swift 标准输入／输出服务。分发器负责验证工具参数，ChannelRouter 选择当前可用的最强 macOS 通道，资源提供缓存／实时状态，高风险写入则返回明确的已确认／不确定／失败状态封装。核心通道包括 MCU、辅助功能、AppleScript、CoreMIDI、CGEvent、Scripter 和 MIDI Key Commands。

文档

文档	受众	用途
安装指南	终端用户	安装、MCP 注册、Logic Pro 集成、doctor 锚点
API 参考	终端用户、MCP 客户端	全部 10 个工具、19 个资源、12 个模板、诚实契约、已验证的回写
故障排除	终端用户	常见故障及解决方法
安全策略	安全审查人员	威胁模型、报告方式、安全加固
更新日志	所有人	各版本的变更
贡献指南	贡献者	开发环境设置、范围明确的 PR 工作流、PR 验证

公开文档目录有意限定范围：安装、API、故障排除、README 媒体，以及用于说明当前进行中或已发布的面向用户修复的公开问题 PRD/工单。历史发布说明、内部 PRD、私有工单看板、探索性记录和本地实时证据工作文件均不纳入 docs/；公开发布历史请参阅 CHANGELOG.md、GitHub Releases、已合并的 PR 和问题历史。

验证

检查项	检查内容	证据
CI（每次推送/PR）	完整的确定性测试套件、发布构建、仓库检查	上方的 Actions 徽章反映当前 main 分支头部状态
发布构建	swift build -c release	在 CI 和发布工作流中运行
实时 E2E	针对真实运行中的 Logic Pro 会话执行已注册操作，并独立回读	每个版本的证据和带日期的观察记录位于 docs/observations/ 下，并链接自相关 CHANGELOG 条目；不会针对每次提交运行
README 媒体	实际 Logic Pro 屏幕录制的衍生素材	发布在 docs/media/ 下

本 README 不提供固定的测试通过数量：测试套件规模会随每次发布而变化，此处的数字到下一次发布前就会过时。请在本地运行 swift test --no-parallel，或查看 CI 徽章，以了解当前通过/失败状态。各功能的实时证据声明（使用了哪种语言区域、哪个 Logic 版本、测量了什么以及未测量什么）位于 CHANGELOG.md 中对应变更旁边，而非此处。

实时 E2E 默认使用发布二进制文件。协议/安全断言可在任何主机上运行；依赖 Logic/CoreMIDI 的检查仅在检测到真实 Logic Pro 会话时运行，否则会跳过。

重要的 API 契约

• 诚实的契约状态 — 每个变更操作都会返回 A 状态（已确认）、B 状态（不确定，包含 reason）或 C 状态（硬性失败，包含 error）。请参阅 docs/API.md。
• HC v2 插件应用回写 — logic_plugins.get_inventory、set_param_verified 和 insert_verified 会添加 state + hc_schema: 2；C 状态始终包含 verified:false、write_attempted、重试安全性，以及相关时的目标身份。
• 失败即关闭的变更目标 — 混音器推子、插件参数、标记删除/重命名、音轨删除/复制和 MIDI 导入都要求明确的目标参数。
• 精确插槽插件插入 — logic_plugins.insert_verified 以 get_inventory 返回的物理插入索引为目标，验证弹出窗口锚定在该插槽上，并且仅通过写入后的清单差异确认成功。
• 忠实于目标的导航 — 缓存未热时，goto_marker 会返回 element_not_found，而不会跳转到下一个标记。
• 从 1 开始的 MIDI 通道 — send_note、send_cc 和 record_sequence 的 ch 值接受 1..16，与 Logic 的 UI 一致。
• 有界原始 SysEx — send_sysex 会在通过 CoreMIDI 路由前拒绝超过 1024 字节的负载。
• 可听弹出混音防护 — record_sequence 会拒绝未经验证的 GM Device / External MIDI 导入，logic://project/audit 会将包含 MIDI 区域的 External MIDI 音轨标记为导出阻碍项，而 logic_project.bounce 会在打开弹出混音对话框前拒绝这些阻碍项。
• 审计阶段拆分 — 审计日志会区分被拒绝的调用、确认提示和已执行的路由调用。
• 已验证的项目保存 — project.save_as 会验证目标 .logicx 软件包是否存在，并确认现有软件包的修改时间有所更新。
• 实时项目元数据 — logic://project/info 会在可用时优先显示实时传输速度/采样率，并按字段回退到已保存的项目元数据。
• 无副作用的读取 — 资源会公开状态、元数据和缓存清单，而不会修改 Logic。

发布与分发

稳定的生产版本标签使用 GitHub Actions 发布工作流。RELEASE-METADATA.json 记录每个构件的确切签名模式、Team ID 和架构。如果没有 Developer ID 凭据，发布时会提供 ADHOC 构件及 SHA256 元数据和安装验证，而不会冒称已完成公证。

各版本的详细信息见 CHANGELOG.md。安全性和安装程序信任级别见 SECURITY.md。

注册表元数据

仓库提供 server.json，用于官方 MCP 注册表元数据路径。它固定指向当前稳定版本（v3.18.0），并包含用于发现 Logic Pro、DAW 自动化、MIDI、Claude/Cursor MCP 客户端和音乐制作 Agent 的标签。该记录仅包含元数据，因为注册表软件包架构尚未将 Homebrew 公式或 GitHub 发布压缩包建模为一等软件包类型。安装仍以此处上述固定的 GitHub Release/Homebrew 路径为准。

已知限制

• 速度输入：当 Logic 的内联速度输入无法提交时，transport.set_tempo 会使用有界的粗略和精确 AX 滑块回退方案；如果仍无法验证精确回读，则会安全失败。
• MIDI 区域填充：record_sequence 区域从第 1 小节开始，并使用不可听的填充延伸至目标小节；区域内的音符时序精确，但区域看起来可能比乐句更长。
• 外部 MIDI 弹出就绪状态：项目审计或 logic_project.bounce 不会将 GM Device / External MIDI 轨道上的 MIDI 区域视为可听弹出的证据。在声称获得已验证的 Logic Bounce 之前，请将素材移至软件乐器轨道或在其上重新创建。
• MIDI 按键指令：Logic 12.2+ 不接受旧版 .plist 按键指令导入；仅依赖按键指令的操作仍需手动进行 MIDI Learn。在 it-IT、pt-BR 和 zh-TW 中，自动化的录音启用按键指令设置（system.setup_arm_key）会拒绝执行，直到根据 Apple 数据或实时测量确认这些语言的按键指令拼写（参见 CHANGELOG v3.18.0）。
• 标记：创建标记时会使用 Logic 原生的 Navigate 菜单，并在标记列表可读时进行验证。如果标记列表已关闭或不可读，则会报告为不可读，或使用上次可读的缓存，而不会将其标记为已验证的空列表。rename_marker 仍为 not_implemented。
• 插件参数回读：logic_plugins.set_param_verified 会在需要时打开目标插入效果器的插件窗口，并通过该窗口实时验证 Compressor 的 threshold；任意插件参数仍属后续工作，遇到此类参数会以 unsupported_param_readback 安全失败。
• 语言区域覆盖主要基于推导，而非实测：除 en-US、ko-KR、ja-JP 和 de-DE 外，大多数规范 UI 标签都是根据 Apple 的 .strings 表格推导出的 derived，而非从对应语言的 Logic 实时窗口中读取（参见上方的语言区域表）。

开发

当前已验证的工具链要求使用 Xcode 16.4+ / Swift 6.2 进行源码构建。

swift test --no-parallel
swift build -c release

许可证

MIT。请参阅 LICENSE。

贡献

欢迎提交错误报告、PR 和功能讨论。有关开发工作流，请参阅 CONTRIBUTING.md 和未解决的问题。

安全漏洞：请勿公开提交问题。有关私密披露流程，请参阅 SECURITY.md。