Indesign Scripting MCP

InDesign脚本MCP（DOM+Exec）

Done with a single prompt from within Claude Desktop in 20 seconds (and some tinkering afterwards).

Some chats with theInDesign agent

Adobe InDesign的两个MCP服务器：

• InDesign DOM MCP (server.py)：从XML源构建的本地SQLite数据库中查询InDesign DOM+ExtendScript JavaScript核心+ScriptUI类。
• InDesign Exec MCP (exec_server.py)：通过Windows COM/OLE在正在运行的InDesign实例中执行ExtendScript（JSX），并返回结构化的JSON结果。

这是什么

此项目向代理公开了两个互补的服务器：

• DOM服务器：快速、只读地访问对象模型，而无需将整个DOM加载到模型上下文中。
• Exec服务器：使用撤消分组和DOM安全JSON序列化安全执行JSX。

这与基于UXP的方法有何不同

建筑

flowchart LR
  DOM_XML["omv$indesign-*.xml"] --> Parser[parser.py]
  JS_XML[javascript.xml] --> Parser
  SUI_XML[scriptui.xml] --> Parser
  Parser --> SQLite[(extendscript.db)]
  SQLite --> DomServer["server.py (InDesign DOM MCP)"]
  Agent[Agent] --> DomServer
  Agent --> ExecServer["exec_server.py (InDesign Exec MCP)"]
  ExecServer --> COM[COM/OLE]
  COM --> InDesign["Adobe InDesign (running)"]

核心文件：

• server.py：用于查询DOM数据库的MCP工具
• exec_server.py：InDesign中用于执行JSX的MCP工具
• parser.py：OMV XML解析器+数据库构建器（SQLite+FTS5）
• db.py：DOM工具的数据库查询层
• manage.py：CLI用于分析/构建/更新/验证数据库
• indesign_com.py：COM/OLE自动化层+安全JSX包装器
• json_polyfill.jsx：ExtendScript JSON polyfill+ __safeStringify() （DOM安全）
• gotchas.json：精心策划的陷阱和最佳实践知识库（通过PR实现社区增长）

MCP工具参考

InDesign DOM MCP(server.py)

• lookup_class(name, source?)
• get_properties(class_name, source?, filter?, include_inherited?)
• get_methods(class_name, source?, filter?, include_inherited?)
• get_method_detail(class_name, method_name, source?)
• get_enum_values(enum_name, source?)
• get_hierarchy(class_name, source?)
• search_dom(query, source?)
• list_classes(suite?, type=all, source?)
• dom_info()
• list_sources()
• knowledge_overview()

InDesign Exec MCP(exec_server.py)

• run_jsx(code, undo_name="Agent Script", undo_mode="entire")
• get_document_info()
• get_selection(detail_level="basic"|"full")
• eval_expression(expression)
• undo(steps=1)
• report_learning(problem, solution, triggers, category?, severity?, error_message?, jsx_context?)
• get_gotchas(context?)
• get_quick_reference()

代理使用/关键模式

1） 知识概述->查找->代码生成->执行

1. 使用DOM MCP查找正确的类/方法签名。
2. 对于不明确的类名(Window, Group, Panel, Event)通行证 source="dom" 或 source="scriptui".
3. 对于特定于ExtendScript的API(UnitValue, $, File, Folder, Socket, XML, XMLList)使用 source="javascript".
4. 编写JSX，为其分配一个普通值 __result （不要 return).
5. 执行 run_jsx 并验证 eval_expression 或 get_document_info.
6. 如果需要，请使用回滚 undo.

2） 推荐的代理启动顺序

1. knowledge_overview()
2. list_sources()
3. search_dom(query, source=...)
4. lookup_class(...) / get_method_detail(...)
5. indesign-exec 工具(run_jsx, eval_expression, undo)

3） ScriptUI定位

ScriptUI仍然记录了遗留脚本和小对话框。对于新的UI密集型开发，更喜欢现代的UXP插件。

4) __result 惯例

包装器序列化 __result JSON。例子：

var doc = app.activeDocument;
__result = { name: doc.name, pages: doc.pages.length };

5） 撤消分组

使用 undo_mode="entire" 以及描述性 undo_name 因此一个Ctrl+Z将恢复整个操作。

6） JSON polyfill/安全序列化

ExtendScript引擎可能缺少 JSON.stringify 或者在遍历DOM对象时崩溃。 该项目始终提供 __safeStringify() （并安装 JSON.stringify 如果缺失）。

数据源

解析器支持三个XML源：

• InDesign DOM OMV XML(omv$indesign-*.xml)
• ExtendScript JavaScript核心(javascript.xml)
• ScriptUI(scriptui.xml)

常见源位置：

• macOS：

- /Library/Application Support/Adobe/Scripting Dictionaries CC/CommonFiles - ~/Library/Preferences/ExtendScript Toolkit/4.0/omv$indesign-9.064$9.0.xml

• 窗户：

- \\Users\\[Username]\\AppData\\Roaming\\Adobe\\ExtendScript Toolkit\\4.0\\omv$indesign-10.064$10.0.xml - C:\\Program Files (x86)\\Common Files\\Adobe\\Scripting Dictionaries CC\\CommonFiles

构建命令

构建所有来源（推荐）

python manage.py build-all --dom "C:\\path\\to\\omv$indesign-21.064$21.0.xml" --js "C:\\path\\to\\javascript.xml" --sui "C:\\path\\to\\scriptui.xml"

构建单一来源

python manage.py build --source dom --xml "C:\\path\\to\\omv$indesign-21.064$21.0.xml"

验证源覆盖率

python manage.py validate --expect-sources dom,javascript,scriptui

1. 编写JSX，为其分配一个普通值 __result （不要 return).
2. 执行 run_jsx 并验证 eval_expression 或 get_document_info.
3. 如果需要，请使用回滚 undo.

先决条件

• Windows（执行服务器使用COM/OLE）
• Adobe InDesign桌面（正在运行）
• Python 3.11+
• uv （推荐）或 pip
• 来自ExtendScript Toolkit缓存的OMV XML，例如：

- 窗户： %APPDATA%\\Adobe\\ExtendScript Toolkit\\4.0\\omv$indesign-*.xml

安装

1） 创建/更新DOM数据库

python manage.py build-all --dom "C:\\path\\to\\omv$indesign-21.064$21.0.xml" --js "C:\\path\\to\\javascript.xml" --sui "C:\\path\\to\\scriptui.xml"

结果 extendscript.db 是在本地生成的，不应提交。

2） 运行MCP服务器（stdio传输）

随着 uv:

uv run server.py
uv run exec_server.py

随着 pip /普通Python：

python server.py
python exec_server.py

MCP客户端配置

光标

添加从该repo目录运行的两台服务器（使用stdio传输）：

{
  "mcpServers": {
    "indesign-dom": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "D:\\\\path\\\\to\\\\indesign_scripting_MCP"
    },
    "indesign-exec": {
      "command": "uv",
      "args": ["run", "exec_server.py"],
      "cwd": "D:\\\\path\\\\to\\\\indesign_scripting_MCP"
    }
  }
}

克劳德桌面版

将相同的服务器定义添加到 claude_desktop_config.json （确切的文件位置取决于您的操作系统安装）。

可选：Claude Skill（InDesign MCP操作员）

提高AI的使用能力 indesign-dom 和 indesign-exec 工具。实际上，我们提供 克劳德技能 这教会了它一个强大的“检查-查找-执行-验证”工作流。这有助于防止常见的脚本错误，并确保更安全的执行。如果没有它，代理将很好地使用MCP，但它会使事情变得顺利。

技能档案位于 claude-skills/indesign-mcp-operator/:

• indesign-mcp-operator.skill：用于直接安装的技能定义文件。
• SKILL.md：技能说明的标记来源。
• reference.md：可重用的模式和提示模板。

使用较新的DOM更新数据库

要更新一个源，请执行以下操作：

python manage.py update --source dom --xml "C:\\path\\to\\omv$indesign-22.064$22.0.xml"

要重建所有三个源：

python manage.py build-all --dom "C:\\path\\to\\omv$indesign-22.064$22.0.xml" --js "C:\\path\\to\\javascript.xml" --sui "C:\\path\\to\\scriptui.xml"

贡献Gotchas

gotchas系统是此MCP的共享调试内存：

• gotchas.json 是致力于Git的经过策划、版本化的知识库。
• 条目描述了用于上下文匹配的重复陷阱、修复和触发关键字。
• 代理商将通过以下方式查询相关项目 get_gotchas(context, min_severity?, top_n?) 在编写JSX之前。
• get_quick_reference() 包括静态指导，并在运行时附加社区陷阱。
• 在故障排除过程中，代理可以并将通过以下方式提交新解决的问题 report_learning(...) 您的MCP。

请将它们作为PR提交给此回购，以使所有人受益！它使成功的调试结果在未来的会话和用户之间可重用。

支持两种贡献路径：

A） 通过GitHub PR直接策划更新

1. 分叉+克隆此存储库
2. 编辑 gotchas.json 并添加新条目
3. 用新的gotcha打开PR
4. 维护人员审查和合并

B） 代理提交->维护人员审核

1. 你的代理人打电话来了 report_learning(...)
2. 条目已写入 submissions/pending.jsonl （本地队列，未提交）
3. 维护者（您）运行：

python manage.py review-submissions

1. 已批准的条目将升级为 gotchas.json
2. 提交并打开公关，分享精心策划的学习成果

许可证

MIT。看 LICENSE.

第三方通知

该存储库引用了受IdExtenso（Marc Autret，麻省理工学院）启发的安全/序列化模式。 看 THIRD_PARTY_NOTICES.md.

致谢

• Gregor Fellenz： https://github.com/grefel/extendscriptApiDocTransformations
• 本项目采用了该知识库的概念性学习：

- InDesign DOM+JavaScript+ScriptUI中的XML合并策略 - 解析前的命名空间规范化 - ScriptUI命名冲突的显式处理 - 参考意识转换思维