{"_id":"@chaoswise/intl-platform-mcp","name":"@chaoswise/intl-platform-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@chaoswise/intl-platform-mcp","version":"0.1.0","description":"MCP server wrapping the ChaosWise i18n platform HTTP API for AI agents. stdio transport, L1 read + L2 own-domain write (dry-run) tools. Shared-domain writes are not exposed - use the platform admin UI.","type":"module","main":"dist/index.js","bin":{"intl-platform-mcp":"dist/index.js"},"engines":{"node":">=18"},"license":"MIT","author":{"name":"ChaosWise"},"repository":{"type":"git","url":"ssh://git@git.cloudwise.com:36000/DOCP/aops_web_commons.git","directory":"packages/intl-platform-mcp/server"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","prepare":"tsc","start":"node dist/index.js","dev":"tsc && node dist/index.js","smoke":"tsc && node scripts/smoke.mjs","smoke:full":"tsc && node scripts/full-chain.mjs","smoke:all":"tsc && node scripts/smoke.mjs && node scripts/full-chain.mjs","test":"vitest run"},"vitest":{"include":["src/**/*.test.ts"]},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","axios":"^1.7.9","form-data":"^4.0.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.10.0","exceljs":"^4.4.0","typescript":"^5.7.0","vitest":"^4.1.10"},"_id":"@chaoswise/intl-platform-mcp@0.1.0","gitHead":"c4d9353fe31b2e544676fcad3c6b0fe12b9bec17","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-viwWRNsFH88FLqLvtoeRmKBIVORs8AfR5NeuUjGFlq2x7FN2So1cTzikakp4TnIm4OxBgK+ee/mGS9uUx0nsLw==","shasum":"9b155ab1eae6f2d445d8010c060ceb709f1e392d","tarball":"https://registry.npmjs.org/@chaoswise/intl-platform-mcp/-/intl-platform-mcp-0.1.0.tgz","fileCount":10,"unpackedSize":43183,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCH3SaSi2bIYJq4TC21AYeM+htURCpPvm4pxj33GfKiXwIhAOBETfqPdhXiZDwq1x3+Krj54M7wBy3AI7TfL6+8iAoK"}]},"_npmUser":{"name":"cloudwise","email":"harry.lang@cloudwise.com"},"directories":{},"maintainers":[{"name":"cloudwise","email":"harry.lang@cloudwise.com"},{"name":"howard.gu","email":"howard.gu@yunzhihui.com"},{"name":"andrew.qiao","email":"1095210210@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/intl-platform-mcp_0.1.0_1783931972813_0.11191744283765837"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-13T08:39:32.630Z","0.1.0":"2026-07-13T08:39:32.955Z","modified":"2026-07-13T08:39:33.354Z"},"maintainers":[{"name":"cloudwise","email":"harry.lang@cloudwise.com"},{"name":"howard.gu","email":"howard.gu@yunzhihui.com"},{"name":"andrew.qiao","email":"1095210210@qq.com"}],"description":"MCP server wrapping the ChaosWise i18n platform HTTP API for AI agents. stdio transport, L1 read + L2 own-domain write (dry-run) tools. Shared-domain writes are not exposed - use the platform admin UI.","repository":{"type":"git","url":"ssh://git@git.cloudwise.com:36000/DOCP/aops_web_commons.git","directory":"packages/intl-platform-mcp/server"},"author":{"name":"ChaosWise"},"license":"MIT","readme":"# @chaoswise/intl-platform-mcp\n\n让 AI 直接驱动 ChaosWise 国际化平台,把原流程里「需要人肉操作平台 Web 界面」的环节(上传 xlsx、确认导入、回传 relationKey、查重)自动化。\n\nMCP server 包装平台的 HTTP API,stdio 传输,按风险分层授权。平台 `checkLogin:false` 无强鉴权,直连明文调 API,无需登录/token 配置。\n\n## 设计核心:风险分层授权\n\n平台是**跨产品共享词条池**,改一条译文会波及所有关联产品。最大风险不是技术,是数据污染。所有工具按写副作用分三层:\n\n| 层 | 含义 | 自动化 | 行为 |\n|----|------|--------|------|\n| **L1 只读** | 不改平台任何数据 | ✅ AI 全自动 | 直接调用,返回结果 |\n| **L2 本产品域写** | 只动本 `groupName` 关联 + 追加新词条(追加不覆盖共享) | ✅ 自动 + dry-run | 默认 `dryRun:true` 返回 diff,`confirm:true` 才真写 |\n| **L3 共享域写** | 改/删已有译文、覆盖多产品共用词条、删语种/分组 | ⛔ 不经 MCP | MCP 不提供此类工具;由平台 Web 后台人工治理 |\n\n守住「L1 全开、L2 带 dry-run、共享域写不经 MCP」,平台数据就不会被 AI 搞乱。\n\n## 安装\n\n```bash\nnpm install @chaoswise/intl-platform-mcp\n```\n\n> 需要 Node 18+。包自带预构建产物(`dist/`),安装后无需再 build。\n\n## 配置\n\n### 环境变量\n\n| 变量 | 必填 | 默认 | 说明 |\n|------|:----:|------|------|\n| `INTL_PLATFORM_BASE_URL` | ✅ | (无,必填) | 平台地址,如 `http://your-platform-host:18000`。缺失即抛错,不硬编码内网地址 |\n| `INTL_RELATION_KEY_PATH` | ❌ | `cwd/relationKey.json` | `write_relation_key` 默认落盘路径 |\n| `INTL_TIMEOUT_MS` | ❌ | `60000` | 请求超时(ms) |\n| `INTL_AUDIT_LOG_PATH` | ❌ | `cwd/.intl-audit.log` | 审计日志(JSONL);设为 `off` 关闭 |\n\n### Claude Code (`.mcp.json`)\n\n放在工程根或 `~/.claude.json`。`args` 指向包内的 `dist/index.js`(用绝对路径):\n\n```json\n{\n  \"mcpServers\": {\n    \"intl-platform\": {\n      \"command\": \"node\",\n      \"args\": [\"/abs/path/to/node_modules/@chaoswise/intl-platform-mcp/dist/index.js\"],\n      \"env\": {\n        \"INTL_PLATFORM_BASE_URL\": \"http://your-platform-host:18000\"\n      }\n    }\n  }\n}\n```\n\n或用 `npx` 免路径:\n\n```json\n{\n  \"mcpServers\": {\n    \"intl-platform\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@chaoswise/intl-platform-mcp\"],\n      \"env\": {\n        \"INTL_PLATFORM_BASE_URL\": \"http://your-platform-host:18000\"\n      }\n    }\n  }\n}\n```\n\n### Cursor (`.cursor/mcp.json`)\n\n同上结构,改 `args` 路径即可。\n\n### 共享域写不经 MCP\n\n改/删共享词条译文、删词条、清分组、增删语种等**波及所有关联产品**的操作,MCP **不提供工具**--这类高风险治理归属平台 Web 后台人工操作,不交给 AI。需要时直接去平台后台做,不在此配任何 token。\n\n配好后重启客户端,`/mcp` 应显示 `intl-platform` = connected。\n\n## 工具一览(11 个)\n\n| 层 | 工具 | 风险 |\n|----|------|------|\n| L1 只读 | `search_words` `list_words` `get_word` `list_groups` `list_languages` `analyze_upload` `export_words` `get_history` | AI 全自动 |\n| L2 本产品域写 | `import_words` `download_locale_by_keys` `write_relation_key` | 默认 dryRun,`dryRun:false` + `confirm:true` 才真写 |\n\n> 共享域写(原 L3:`update_word_translation`/`delete_word`/`clear_group`/`add_language`/`delete_language`)不经 MCP,走平台 Web 后台。\n\n### 工具语义要点\n\n- **`analyze_upload`**(L1):上传 xlsx/json 仅查重分析,不落库。是 `import_words` 的前置 dry-run。结果可能很大,传 `saveToPath` 落盘后用 `import_words(analyzedDataPath=该路径)` 导入,避免撑爆 LLM 上下文。\n- **`import_words`**(L2):默认 `dryRun:true` 返回「将新建/关联/不覆盖」diff;`dryRun:false` + `confirm:true` 才真落库,返回 `relationKey` 映射。\n- **multipleProduct 词条**:import 时一律只新增关联、不覆盖译文;需覆盖走平台 Web 后台(MCP 不提供共享域写)。\n\n## 典型链路(AI 视角)\n\n```\nsearch_words        -> 查平台是否已有某中文\nanalyze_upload      -> 上传 collect 产出的 xlsx,拿查重分类\nimport_words(dryRun)-> 看将新建/关联/不覆盖的 diff\n  ↓ 人审翻译草案\nimport_words(confirm)-> 落库,拿 relationKey\nwrite_relation_key  -> 写 relationKey.json 到仓库根\ndownload_locale_by_keys(confirm) -> 拉 locale 给 update 用\n```\n\n## 安全模型\n\n1. **共享域写不经 MCP**--改/删共享词条、增删语种等高危操作,MCP 直接不提供工具,归平台 Web 后台人工治理。能力不存在,而非被 token 闸挡住。\n2. **import 前必须先 analyze**--不允许跳过查重直接 import(防重复建条)。\n3. **multipleProduct 永不覆盖**--只新增关联。\n4. **所有真写记审计日志**:`.intl-audit.log`(JSONL),记录 `action`/`layer`(L2)/`actor`(ai)/`outcome`/`target`/`affectedGroups`/`at`。dry-run 不记。\n5. **baseURL 走环境变量**,不硬编码。\n6. **dry-run 是默认值**,`confirm` 必须显式传。\n\n## 开发\n\n```bash\ncd server\nnpm install\nnpm run build        # tsc -> dist/\nnpm test             # vitest 单测(mock 平台,不连真实平台)\nnpm run smoke        # 安全冒烟(连真实平台,11 工具不落库路径 + 错误用例)\nnpm run smoke:full   # 完整写链路(连真实平台,会真写 + 自清理)\n```\n\n`smoke` / `smoke:full` 需连真实平台,用 `INTL_PLATFORM_BASE_URL` 指向你的实例。\n\n## 与 CLI 的职责切分\n\n`chaoswise-intl` CLI 负责源码 AST 改写(collect/update/verify/nozhcn);本 MCP 负责平台 HTTP I/O(查重、上传、导入、下载 locale、写 relationKey)。两者不重叠,MCP 不调 CLI,CLI 也不经 MCP。\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-2f5b18dc0d0889f944687e9ad694e3ea"}