idmly: HTML to InDesign (IDML)

idmly-mcp

从你已经在使用的 AI Agent 中，将独立的 HTML 设计转换为可编辑的 Adobe InDesign 文件（.idml）。这是以模型上下文协议服务器形式提供的 idmly 引擎，Claude Code、Cursor、Codex、Windsurf 或 Claude Desktop 可以将完成的设计直接交给 InDesign。

任何设计中最详细的两页都可以免费转换，无需密钥（结果会标明转换的是哪些页面）。49 美元的终身许可证可解锁不限次数的完整文档转换，并同时适用于网站和此工具。

安装

需要 Node 20 或更高版本。此服务通过 npx 运行，无需克隆仓库。无需密钥即可启动，免费试用会直接生效。

Claude Code

claude mcp add idmly -- npx -y idmly-mcp

Cursor、Windsurf、Claude Desktop（mcp.json / claude_desktop_config.json）

{
  "mcpServers": {
    "idmly": { "command": "npx", "args": ["-y", "idmly-mcp"] }
  }
}

Codex CLI（~/.codex/config.toml）

[mcp_servers.idmly]
command = "npx"
args = ["-y", "idmly-mcp"]

使用许可证时，将购买邮件中的密钥添加为环境变量：

claude mcp add idmly -e IDMLY_LICENSE_KEY=<your key> -- npx -y idmly-mcp

"env": { "IDMLY_LICENSE_KEY": "<your key>" }

env = { IDMLY_LICENSE_KEY = "<your key>" }

工具

convert_to_indesign

传入以下参数中的且仅一个：

参数	说明
html	完整 HTML 文档字符串
path	本地 .html 文件（仅上传此文件）
url	托管 .html 文件的公开 https 链接

可选参数：out_dir（写入位置；默认为源文件所在文件夹，或当前目录）、name（输出文件的基本名称）、platform（mac 或 win，指定 InDesign 将在何种平台打开文件；用于选择字形回退字体，默认为当前计算机的平台）。

此工具会写入 <name>.idml，并返回文件路径、已转换的页面、InDesign 需要启用的字体，以及几何检查结果。包含图像的设计会输出为一个文件夹，其中包含 .idml 和 Links/ 目录；请将它们放在一起，InDesign 就能找到所有图像。试用版输出文件名为 <name>-trial.idml。

idmly_status

报告引擎是否可访问，以及是否已配置许可证密钥（仅检查密钥是否存在；首次转换时才会验证密钥）。

编写易于转换的 HTML

• 每个页面都是带有 page（或 slide）类的固定尺寸区块。双页阅读跨页使用 spread 类。常见尺寸：Letter 为 816×1056px，A4 为 794×1123px，幻灯片为 1920×1080px，并设置 overflow: hidden。没有标记的单个固定宽度画布会转换为一页；流式布局的 width: 100% 页面没有固有尺寸。
• 保持文件独立完整：将 CSS 和 JS 内联，字体使用 Google Fonts 或嵌入字体，图像使用数据 URI 或绝对 URL。与文件放在一起的样式表或图像不会上传。
• 使用内联 SVG 或 HTML 绘制图表，而不是栅格图像，这样图表仍可编辑。
• 避免使用永远无法稳定下来的脚本（例如会反复触发自身的 MutationObserver 或 resize 处理程序）。引擎会渲染一次页面、测量页面，然后将其重建为 InDesign 框架。

文本会转换为带段落样式的可编辑文本框，表格仍为表格，SVG 和 CSS 图形会转换为矢量对象。

设计师可以继续编辑的文本

文本的标记方式决定了它会放入多少个框架，以及段落样式会保留哪些设置。

• 同一个框中的连续段落会变成一个文本框架，每个段落对应一段文字。使用 margin-top 或 margin-bottom 设置间距；它们会分别转换为带有相应边距的段落的段前距或段后距。空白间隔段落（<p>&nbsp;</p>）也会保留在同一个框架中。
• padding-left 表示左缩进，text-indent 表示首行缩进，因此 padding-left: 46pt; text-indent: -46pt 就是悬挂缩进。
• 真正的制表符（位于 white-space: pre 或 pre-wrap 内）会按照 CSS 网格设置制表位：将 tab-size 设为长度值（tab-size: 46pt），即可将制表位放在所需位置。
• 两列列表（目录、价格、鸣谢）最好转换为 <table>：它会变成原生 InDesign 表格，每个单元格各有一个段落样式。
• 段落样式根据标签和元素的第一个类命名（<p class="caption"> 会生成“Body · caption”）。若要直接指定名称，请添加 data-idml-style="Cover Dates"。
• 容纳连续文本的框可以链接起来：为每个框指定相同的 data-idml-thread="cv"，它们就会按文档顺序逐框转换为一个串接文本故事（也可以使用 data-idml-thread-order="1"、"2" 等指定顺序）。除最后一个框外，每个框的大小都固定为其文本所需的尺寸，因此新增一行文字会流入下一个框。如果某个框从段落中间开始，请添加 data-idml-thread-continues，这样它的首段就会与前一个框的末段合并。InDesign 会重新排版串接文本故事，因此与 HTML 相比，文字可能会跨越框架边界移动。
• 段落内的行内 display: inline-block 元素会被视为独立的框，并转换为单独的框架。对于仅更改字体或颜色的一段文字，请使用普通的 <span>。

失败时的处理方式

结果	含义	处理方式
不带密钥时出现 402	此设计或当前小时的免费试用额度已用完	结果中会包含价格和结账链接
带密钥时出现 402	密钥未被接受	检查密钥；如果之前有效，请删除 ~/.idmly/instances.json，以便下次调用时重新激活
413	超过大小上限（试用版 15 MB，许可版 50 MB）	缩小图像或重新编码，也可以托管图像并使用绝对 URL
422	没有内容被渲染，或脚本一直未完成	内联缺失的资源；移除无限运行的脚本
429 / 503	达到速率限制，或无法连接许可服务	在 retry_after_seconds 指定的时间后重试

引擎始终处于运行状态，因此没有冷启动。工具仍会在上传前检查引擎是否有响应（最多约 25 s）；如果上传中途被中断（例如正在重新部署），系统会自动再次发送一次。因此，短暂故障只会造成延迟，不会导致错误。

大型设计可能需要几分钟才能完成渲染。有些客户端默认会在 60 秒时终止工具调用；处理大型文档时，请提高客户端的单工具超时时间（例如 Claude Code 中的 MCP_TOOL_TIMEOUT）。

环境变量

变量	默认值	用途
IDMLY_LICENSE_KEY	无（免费试用）	你从 idmly.com 获取的许可证密钥
IDMLY_OUT_DIR	与源文件相邻	默认输出目录
IDMLY_ENGINE_URL	托管引擎	用于覆盖为可自托管引擎

密钥会在首次使用时激活。激活 ID 会以密钥哈希值为索引，保存在 ~/.idmly/instances.json 中；此工具绝不会将密钥本身写入磁盘。运行此服务的每台机器都会占用该许可证额度中的一个激活名额。

托管端点

如果你不想运行本地进程，引擎也支持通过 Streamable HTTP 使用 MCP：

https://idmly-production.up.railway.app/mcp
Authorization: Bearer <your key>      (omit the header for the free trial)

在 claude.ai（或 Claude 桌面应用）中：选择 Customize → Connectors → Add custom connector，粘贴 URL，选择 No sign-in，然后在 Request headers 下选择 authorization，并输入值 Bearer <your key>，即在密钥前加上 Bearer 和一个空格。Claude 会原样发送输入的值，不会自行添加认证方案；引擎也会读取不带前缀的密钥，因此只填写 <your key> 也可以。其他格式（Basic …、Token …）也能连接，但首次转换会提示你应如何更改，而不会按试用版运行。如果对话框中没有 Request headers 部分，说明你的 Claude 组织尚未启用该测试版；请改用上方的本地服务（npx idmly-mcp 并设置 IDMLY_LICENSE_KEY）。

由于远程工具无法写入你的磁盘，该端点会返回一次性下载链接，而不是文件路径：文件会在下载后立即删除，或在无人下载 10 分钟后删除。同一端点也适用于 OpenAI Responses API mcp 工具和 Agents SDK。

纯 REST 接口使用 POST /convert，并传入 multipart 格式的 file（或 url），以及 license_key 和 instance_id。首次授权响应会包含 X-Idmly-Instance 标头；后续每次调用都要将该值作为 instance_id 传回，否则每次调用都会针对许可证激活一台新设备。响应内容为 .idml 文件本身；如果设计中包含图片，则为 application/zip（其中包含 converted.idml 和 Links/）。

隐私

转换后的文件返回后，上传的设计会立即从引擎中删除。在托管 MCP 端点上，转换后的文件会暂存在一次性且无法猜测的链接后，最长等待 10 分钟，供 Agent 获取，之后便会删除。无需账户。引擎会保留第一方使用记录（次数、结果、国家/地区），但绝不会保留你的文件或密钥。

开发

npm install
npm test          # type-checks, bundles, then runs the client against a stub engine (no network)

已发布的软件包没有运行时依赖：npm run build 会将 MCP SDK 和 zod 打包到 dist/index.js 中，因此 npx 用户拿到的文件与测试所用文件完全一致。依赖更新会通过 Dependabot 每周提交一个拉取请求；合并后，GitHub Actions 会通过来源证明发布新的补丁版本。

许可证

此客户端采用 MIT 许可证。idmly 引擎是一项托管服务，详情请参阅 idmly.com/legal。