@chaoswise/intl-platform-mcp

让 AI 直接驱动 ChaosWise 国际化平台,把原流程里「需要人肉操作平台 Web 界面」的环节(上传 xlsx、确认导入、回传 relationKey、查重)自动化。

MCP server 包装平台的 HTTP API,stdio 传输,按风险分层授权。平台 checkLogin:false 无强鉴权,直连明文调 API,无需登录/token 配置。

设计核心:风险分层授权

平台是跨产品共享词条池,改一条译文会波及所有关联产品。最大风险不是技术,是数据污染。所有工具按写副作用分三层:

| 层 | 含义 | 自动化 | 行为 | |----|------|--------|------| | L1 只读 | 不改平台任何数据 | ✅ AI 全自动 | 直接调用,返回结果 | | L2 本产品域写 | 只动本 groupName 关联 + 追加新词条(追加不覆盖共享) | ✅ 自动 + dry-run | 默认 dryRun:true 返回 diff,confirm:true 才真写 | | L3 共享域写 | 改/删已有译文、覆盖多产品共用词条、删语种/分组 | ⛔ 不经 MCP | MCP 不提供此类工具;由平台 Web 后台人工治理 |

守住「L1 全开、L2 带 dry-run、共享域写不经 MCP」,平台数据就不会被 AI 搞乱。

安装

npm install @chaoswise/intl-platform-mcp

需要 Node 18+。包自带预构建产物(dist/),安装后无需再 build。

配置

环境变量

| 变量 | 必填 | 默认 | 说明 | |------|:----:|------|------| | INTL_PLATFORM_BASE_URL | ✅ | (无,必填) | 平台地址,如 http://your-platform-host:18000。缺失即抛错,不硬编码内网地址 | | INTL_RELATION_KEY_PATH | ❌ | cwd/relationKey.json | write_relation_key 默认落盘路径 | | INTL_TIMEOUT_MS | ❌ | 60000 | 请求超时(ms) | | INTL_AUDIT_LOG_PATH | ❌ | cwd/.intl-audit.log | 审计日志(JSONL);设为 off 关闭 |

Claude Code (.mcp.json)

放在工程根或 ~/.claude.json。args 指向包内的 dist/index.js(用绝对路径):

{
  "mcpServers": {
    "intl-platform": {
      "command": "node",
      "args": ["/abs/path/to/node_modules/@chaoswise/intl-platform-mcp/dist/index.js"],
      "env": {
        "INTL_PLATFORM_BASE_URL": "http://your-platform-host:18000"
      }
    }
  }
}

或用 npx 免路径:

{
  "mcpServers": {
    "intl-platform": {
      "command": "npx",
      "args": ["-y", "@chaoswise/intl-platform-mcp"],
      "env": {
        "INTL_PLATFORM_BASE_URL": "http://your-platform-host:18000"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

同上结构,改 args 路径即可。

共享域写不经 MCP

改/删共享词条译文、删词条、清分组、增删语种等波及所有关联产品的操作,MCP 不提供工具--这类高风险治理归属平台 Web 后台人工操作,不交给 AI。需要时直接去平台后台做,不在此配任何 token。

配好后重启客户端,/mcp 应显示 intl-platform = connected。

工具一览(11 个)

| 层 | 工具 | 风险 | |----|------|------| | L1 只读 | search_words list_words get_word list_groups list_languages analyze_upload export_words get_history | AI 全自动 | | L2 本产品域写 | import_words download_locale_by_keys write_relation_key | 默认 dryRun,dryRun:false + confirm:true 才真写 |

共享域写(原 L3:update_word_translation/delete_word/clear_group/add_language/delete_language)不经 MCP,走平台 Web 后台。

工具语义要点

• analyze_upload(L1):上传 xlsx/json 仅查重分析,不落库。是 import_words 的前置 dry-run。结果可能很大,传 saveToPath 落盘后用 import_words(analyzedDataPath=该路径) 导入,避免撑爆 LLM 上下文。
• import_words(L2):默认 dryRun:true 返回「将新建/关联/不覆盖」diff;dryRun:false + confirm:true 才真落库,返回 relationKey 映射。
• multipleProduct 词条:import 时一律只新增关联、不覆盖译文;需覆盖走平台 Web 后台(MCP 不提供共享域写)。

典型链路(AI 视角)

search_words        -> 查平台是否已有某中文
analyze_upload      -> 上传 collect 产出的 xlsx,拿查重分类
import_words(dryRun)-> 看将新建/关联/不覆盖的 diff
  ↓ 人审翻译草案
import_words(confirm)-> 落库,拿 relationKey
write_relation_key  -> 写 relationKey.json 到仓库根
download_locale_by_keys(confirm) -> 拉 locale 给 update 用

安全模型

1. 共享域写不经 MCP--改/删共享词条、增删语种等高危操作,MCP 直接不提供工具,归平台 Web 后台人工治理。能力不存在,而非被 token 闸挡住。
2. import 前必须先 analyze--不允许跳过查重直接 import(防重复建条)。
3. multipleProduct 永不覆盖--只新增关联。
4. 所有真写记审计日志:.intl-audit.log(JSONL),记录 action/layer(L2)/actor(ai)/outcome/target/affectedGroups/at。dry-run 不记。
5. baseURL 走环境变量,不硬编码。
6. dry-run 是默认值,confirm 必须显式传。

开发

cd server
npm install
npm run build        # tsc -> dist/
npm test             # vitest 单测(mock 平台,不连真实平台)
npm run smoke        # 安全冒烟(连真实平台,11 工具不落库路径 + 错误用例)
npm run smoke:full   # 完整写链路(连真实平台,会真写 + 自清理)

smoke / smoke:full 需连真实平台,用 INTL_PLATFORM_BASE_URL 指向你的实例。

与 CLI 的职责切分

chaoswise-intl CLI 负责源码 AST 改写(collect/update/verify/nozhcn);本 MCP 负责平台 HTTP I/O(查重、上传、导入、下载 locale、写 relationKey)。两者不重叠,MCP 不调 CLI,CLI 也不经 MCP。

License

MIT