内容
# ditto-workflows-mcp
适用于 [Ditto](https://dittowords.com) 的 MCP 服务器 — 通过 Claude 驱动复制工作流：列出项目、查找未翻译的字符串、编写词典感知的翻译（Claude 翻译 — 无 DeepL），并更新工作流状态。
与任何 Ditto 工作区配合使用 — 认证是您自己的工作区 API 密钥。
## 工具列表
| 工具 | 功能 |
|---|---|
| `list_projects` | 工作区中的项目（ID + 名称） |
| `set_default_variant(variantId)` | 设置默认变体（例如 `ar`、`fr`）；保存到 `.ditto-config.json` |
| `list_untranslated(projectId, variantId?)` | 缺少变体的基本项目 |
| `write_translations(translations[], variantId?, status='WIP')` | 写回变体（如果缺少则创建） |
| `list_for_review(projectId, variantId?, statuses=['WIP','REVIEW'])` | 待审翻译与基本文本结合 — 驱动批准/编辑/跳过审阅循环；编辑通过 `write_translations` 返回，批准通过 `update_status` |
| `update_status(projectId, status, ids?/fromStatus?, variantId?)` | 设置基本项目或变体的状态；未知 ID 被跳过 |
| `update_text(projectId, updates[], status?)` | 重写基本项目文本（复制编辑、`{{variable}}` 替换）；未知 ID 被跳过 |
| `list_variablisation_candidates(projectId)` | 具有硬编码动态值的基本项目（日期、金额、%、卡片后 4 位、电子邮件）+ 工作区的变量 — Claude 建议 `{{variable}}` 替换，通过 `update_text` 应用 |
| `list_components(folderId?)` | 工作区的组件库（共享字符串）— 在编写新复制内容之前检查 |
| `search_text(query, projectId?, limit=50)` | 基本项目 + 组件的子字符串搜索 — 查找现有复制内容以重用，或定位字符串的位置 |
| `refresh_translation_assets(variantId?)` | 将整个工作区的基本→变体对拉取到本地翻译记忆文件中 — 用于提炼词典的原材料 |
在省略 `variantId` 的情况下，应用默认变体（配置文件或 `.env` 中的 `DITTO_DEFAULT_VARIANT`）。
**资源：** `ditto://glossary/{variantId}` — 锁定术语 + Claude 翻译时应用的语音规则。由 `translation-assets/{variantId}-glossary.md` + `{variantId}-voice-rules.md` 或 `translation-assets/{variantId}/` 文件夹的 Markdown 文件支持（gitignored — 团队特定，从不提交）。从您自己的工作区启动：运行 `refresh_translation_assets`，然后让 Claude 将配对内容提炼成词典 + 语音规则文件。翻译记忆文件本身故意 *不* 通过资源提供 — 它可以是几百 KB。
## 技能
两个 Claude Code 技能在 `.claude/skills/` 中提供，编码标准剧本，因此整个工作流是一个命令而不是一个段落：
| 技能 | 功能 |
|---|---|
| `/ditto-translate [projectId] [variantId]` | 全翻译循环：刷新资产 → 读取词典 → 分批翻译并自我审阅 → 写回为 WIP → 报告已编写 + 跳过 |
| `/ditto-review [projectId] [variantId]` | 审阅者循环：按批次显示待审翻译与基本文本；批准/编辑/跳过；编辑和批准变为 FINAL；之后刷新翻译记忆 |
它们在您在此仓库打开 Claude Code 时自动加载。如果您在用户范围内安装了 MCP 服务器并从其他目录工作，请将技能文件夹复制到 `~/.claude/skills/` 以使其在任何地方都可用。
## 安装
**先决条件：** Node.js 18+，Ditto 工作区 API 密钥（Ditto → 工作区设置 → API）。
### npx（推荐 — 无需克隆）
**Claude Code：**
```bash
claude mcp add ditto-workflows -s user \
-e DITTO_API_KEY=<您的密钥> \
-e DITTO_DEFAULT_VARIANT=<变体> \
-- npx -y ditto-workflows-mcp@latest
```
（`DITTO_DEFAULT_VARIANT` 是可选的 — 您可以调用 `set_default_variant` 一次代替。）
**其他 MCP 客户端**（Claude Desktop，Cursor，Windsurf，…）— 添加到客户端的 MCP 配置：
```json
{
"mcpServers": {
"ditto-workflows": {
"command": "npx",
"args": ["-y", "ditto-workflows-mcp@latest"],
"env": {
"DITTO_API_KEY": "<您的密钥>",
"DITTO_DEFAULT_VARIANT": "<变体>"
}
}
}
}
```
### 从克隆（开发）
```bash
git clone https://github.com/gojenaya/ditto-workflows-mcp && cd ditto-workflows-mcp
npm install
echo 'DITTO_API_KEY=<您的密钥>' > .env # 服务器本身加载
echo 'DITTO_DEFAULT_VARIANT=<变体>' >> .env # 可选
claude mcp add ditto-workflows -s user -- node "$PWD/mcp-server.js"
```
`npm test` 运行实时烟雾测试（仅限本地，不提交；需要 API 密钥）。
### 状态存储位置
| 内容 | 存储位置 |
|---|---|
| 默认变体配置 | `~/.ditto-workflows-mcp/config.json` |
| 词典 + 翻译记忆文件 | `~/.ditto-workflows-mcp/translation-assets/` — 或克隆安装中服务器旁边的 `translation-assets/` 目录，优先 |
| 覆盖整个数据目录 | `DITTO_DATA_DIR` 环境变量（资产目录单独：`DITTO_ASSETS_DIR`） |
### 首次运行
重启您的客户端，运行 `/mcp` — `ditto-workflows` 应该显示已连接。然后直接询问：
> "列出 *项目* 中的未翻译字符串，使用词典翻译它们，并将它们写回为 WIP。"
## 备注
- 每次 GET 请求都带有缓存破坏器：Ditto 的 CDN 按确切 URL 缓存响应并忽略 `no-cache` 头部，在写入后提供陈旧数据。
- 通过 API 编写的 `{{variable}}` 占位符作为字面文本出现 — 公共 API 无法链接工作区变量到项目（已验证：`variableIds` 在 PATCH 中被静默忽略）。链接、变量创建和开发 ID 重命名发生在 Ditto 网页应用中。
- v1 仅限公共 API。浏览器会话操作（Figma 链接传递、开发 ID 重命名）位于配套管道仓库中，可能稍后加入。
