i18n-mcp-server 0.0.1 → 0.0.2

package/README.md

@@ -1,63 +1,241 @@
 # i18n-MCP-Server
 
-面向前端国际化工作流的 MCP Server，提供以下四类能力：
+`i18n-mcp-server` 是一个面向前端国际化工作流的 MCP Server，帮助你在 Vue / React / TS 项目里完成文案提取、翻译健康检查、Key 重构和同步扩展。
 
-- `extract_replace`：提取硬编码文本并返回源码与语言文件 diff。
-- `doctor_lint`：检查缺失 key、死 key 和硬编码风险点。
-- `refactor_key`：批量重命名 i18n key。
-- `sync_catalog`：预留翻译平台同步适配器接口。
+## Features
 
-## 设计原则
+- 提取代码中的硬编码中日韩文本，替换为 `t('key')`
+- 自动生成 i18n key，并更新本地语言 JSON
+- 检查缺失翻译、死 key、残留硬编码文本
+- 批量重命名 i18n key，并同步更新代码与 JSON
+- 预留 Lokalise / 通用 JSON 同步能力
 
-- 默认不静默写入文件，所有修改都先以 unified diff 返回。
-- JS / TS 使用 Babel AST，Vue 使用 SFC 解析器。
-- 保留 JSON 原始缩进风格，减少 Git 噪音。
-- 默认以 `zh-CN.json` 作为基准语言。
+## Installation
 
-## 快速开始
+### 方式 1：通过 `npx` 直接运行
+
+这是最推荐的方式，不需要全局安装：
 
 ```bash
-npm install
-npm run build
-npm start
+npx -y i18n-mcp-server
 ```
 
-## MCP 工具
+### 方式 2：全局安装
+
+```bash
+npm install -g i18n-mcp-server
+```
+
+安装后可以直接运行：
+
+```bash
+i18n-mcp-server
+```
+
+## MCP Client 配置
+
+这个包是一个标准的 `stdio` MCP Server，适用于 Claude Desktop、Cherry Studio、Cline、Cursor MCP 插件等支持 MCP 的客户端。
+
+### 通用配置示例
+
+使用 `npx`：
+
+```json
+{
+  "mcpServers": {
+    "i18n": {
+      "command": "npx",
+      "args": ["-y", "i18n-mcp-server"]
+    }
+  }
+}
+```
+
+使用全局安装命令：
+
+```json
+{
+  "mcpServers": {
+    "i18n": {
+      "command": "i18n-mcp-server"
+    }
+  }
+}
+```
+
+### Windows 兼容写法
+
+如果你的 MCP 客户端在 Windows 下对命令解析比较严格，可以这样配置：
+
+```json
+{
+  "mcpServers": {
+    "i18n": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "i18n-mcp-server"]
+    }
+  }
+}
+```
+
+## Quick Start
+
+把 MCP Server 接入客户端后，你可以直接让 AI 调用这些工具。
+
+示例指令：
+
+- “调用 `project_info`，检查当前项目的 i18n 框架”
+- “调用 `doctor_lint`，扫描 `src` 和 `src/locales`”
+- “调用 `extract_replace`，处理 `src/pages/UserProfile.tsx`”
+- “调用 `refactor_key`，把 `common.btn.save` 改成 `common.actions.save`”
+
+## Tools
 
 ### `project_info`
 
-读取项目 `package.json`，自动识别 `vue-i18n`、`react-i18next`、`@angular/localize` 等国际化方案。
+读取项目 `package.json`，自动识别当前项目使用的国际化方案：
+
+- `vue-i18n`
+- `react-i18next`
+- `@angular/localize`
+
+示例参数：
+
+```json
+{
+  "cwd": "C:\\your-project"
+}
+```
 
 ### `extract_replace`
 
-输入源码文件与语言目录，扫描静态文本并返回：
+从源码文件中提取静态文本，生成 key，并返回源码与语言文件的 unified diff。
 
-- 提议生成的 key
-- 源码 diff
-- 语言 JSON diff
+支持文件类型：
 
-默认只生成补丁，不直接写盘。
+- `.vue`
+- `.tsx`
+- `.jsx`
+- `.ts`
+- `.js`
+
+示例参数：
+
+```json
+{
+  "cwd": "C:\\your-project",
+  "filePath": "src/pages/UserProfile.tsx",
+  "localesDir": "src/locales",
+  "baseLocale": "zh-CN",
+  "targetLocales": ["zh-CN", "en-US", "ja-JP"],
+  "keyStrategy": "semantic",
+  "namespace": "userProfile"
+}
+```
+
+说明：
+
+- 默认只返回 diff，不静默写盘
+- `keyStrategy` 支持 `semantic` 和 `hash`
+- 当前版本默认假设源码上下文中已经可以使用 `t()`
 
 ### `doctor_lint`
 
-以 `zh-CN.json` 为基准：
+检查翻译文件健康状况，包括：
+
+- 缺失翻译 key
+- 死 key
+- 未国际化的中日韩硬编码文本
 
-- 对比其他语言缺失 key
-- 扫描代码中未引用的死 key
-- 检测剩余的中日韩硬编码文本
+示例参数：
+
+```json
+{
+  "cwd": "C:\\your-project",
+  "srcDir": "src",
+  "localesDir": "src/locales",
+  "baseLocale": "zh-CN",
+  "compareLocales": ["en-US", "ja-JP"]
+}
+```
 
 ### `refactor_key`
 
-对代码中的 `t('oldKey')` 与多语言 JSON 做联动重命名，返回完整影响文件列表和统一 diff。
+批量重命名 i18n key，并联动更新代码引用和语言文件。
+
+示例参数：
+
+```json
+{
+  "cwd": "C:\\your-project",
+  "srcDir": "src",
+  "localesDir": "src/locales",
+  "locales": ["zh-CN", "en-US", "ja-JP"],
+  "oldKey": "common.btn.save",
+  "newKey": "common.actions.save"
+}
+```
 
 ### `sync_catalog`
 
-MVP 先保留 provider 适配器入口，后续可继续接入 Lokalise / Crowdin / 本地 JSON 导入导出。
+当前是 MVP 预留接口，用于未来对接：
+
+- Lokalise
+- Crowdin
+- 本地 JSON 导入导出
+
+示例参数：
+
+```json
+{
+  "provider": "json",
+  "mode": "pull",
+  "lang": "de"
+}
+```
+
+## Output Behavior
+
+为了降低误改代码和误写翻译文件的风险，当前版本默认采用“建议变更”模式：
+
+- 返回结构化 JSON 结果
+- 返回受影响文件列表
+- 返回 unified diff
+- 不默认直接改写文件
+
+这让 MCP Client 可以在应用补丁前先做确认。
+
+## Recommended Project Structure
+
+推荐项目目录类似这样：
+
+```text
+src/
+  pages/
+  components/
+  locales/
+    zh-CN.json
+    en-US.json
+    ja-JP.json
+```
+
+## Local Development
+
+如果你要在本地开发这个 MCP Server：
+
+```bash
+npm install
+npm run check
+npm run build
+npm start
+```
+
+## Current Limitations
 
-## 当前边界
+- Vue 模板替换目前是偏保守的 MVP 实现
+- `extract_replace` 还不会自动补 `t()` 的 import 或 hook 注入
+- `sync_catalog` 目前还没有接入真实 provider API
 
-这一版已经具备可编译、可接入的服务骨架，但仍有几项明确的后续增强点：
+## License
 
-- Vue 模板替换当前是偏保守的 MVP 方案，复杂模板场景还可以继续细化 AST 级改写。
-- `extract_replace` 目前默认依赖调用侧已有 `t()` 上下文，尚未自动补充 import / hook 注入。
-- `sync_catalog` 目前只保留接口和返回结构，尚未接入真实 provider API。
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-mcp-server",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "MCP server for frontend i18n extraction, linting, refactoring, and sync workflows.",
   "type": "module",
   "main": "dist/index.js",