使用说明内容（Markdown 格式）

i18n CodeLens MCP 服务端使用手册

项目简介

该仓库实现了一个基于 Model Context Protocol（MCP）的服务端，用于向 MCP 客户端提供资源管理、工具执行和引用信息等能力，支持对本地化资源（Locales）进行托管、查询、修改，以及暴露一组对翻译工作流有用的工具。

主要功能点

资源管理与查询
- 读取以及解析 locales 目录下的 JSON 资源文件，支持扁平（flat）和嵌套（nested）两种结构，自动检测并保持写入时的结构一致性。
- 提供资源键的定位、引用和变更等能力，支持多语言资源的对比、差异诊断、占位符对齐等操作。
MCP 工具注册与执行
- 注册并实现一组工具（如 i18n_list_locales、i18n_get_translations、i18n_upsert_translations 等），客户端可通过 MCP 调用执行并获得 JSON 结果。
- 工具支持批量更新、删除、命名空间移动、占位符验证等高级功能，帮助自动化国际化工作流。
Standalone 与 VS Code 集成
- 内置 stdio MCP 服务器，支持与 Copilot、Claude for VS Code 等 MCP 客户端对接。
- 也可通过 npm run mcp 以独立模式启动服务器，便于本地开发与调试。
日志与健壮性
- 提供日志输出、错误处理和错误上报，确保在工作流中可追踪的行为记录。
安全与可扩展
- 服务器端负责会话与能力声明，支持多种传输方式（如 stdio），并通过环境变量和工作区设置进行可配置化控制。

安装步骤

克隆仓库并进入项目目录
安装依赖
- npm install
启动 MCP 服务器
- 以独立模式运行（推荐用于开发/调试）：
  - npm run mcp
- 或在工作区根目录直接运行（使用编译产物 server.js）：
  - node ./out/mcp/server.js
备注
- 运行前可以通过环境变量配置 MCP 服务行为（如 I18N_GLOB、I18N_CODE_REGEX、I18N_IGNORE、I18N_STRUCTURE、I18N_INSERT_ORDER 等等），具体请参考代码中的使用说明和 README 提示。

服务器配置

MCP 客户端需要的配置信息，以 JSON 形式示例（注释说明紧随其后，不作为代码块呈现以便理解）： { "servers": { "i18n-codelens": { "type": "stdio", "command": "node", "args": ["out/mcp/server.js"] } // 说明: // - servers: MCP 服务器集合，在客户端配置中需要指定一个服务器条目 // - i18n-codelens: 服务器名称，与扩展中使用的 label 一致 // - type: stdio，表示使用标准输入/输出传输 // - command: 启动服务器的可执行程序，在此示例为 node // - args: 启动参数，指向 MCP 服务器实现的入口脚本 } }

备注与解释
- 该配置示例对应仓库内实现的 MCP 服务器（out/mcp/server.js），用于与 MCP 客户端建立通信。
- 客户端部署时不需要仓库中的具体实现细节，只需该服务器的启动命令与参数即可连接。
- 该 MCP 服务器在 README/源码中也支持通过 VS Code 的自动注册方式、Copilot/Claude 等工具链进行接入。若使用 VS Code LM API，服务器会自动注册并暴露工具集合。

基本使用方法

启动后，客户端（如 Copilot 或其他 MCP 客户端）可以：
- 请求列出可用工具（i18n_list_locales 等），获取工具描述和输入要求。
- 调用具体工具（如 i18n_upsert_translations、i18n_diff_locales 等），传入所需参数，获取执行结果。
- 查询并修改本地化资源（读取、写入 locale 文件），并对嵌套结构进行保留与重排。
运行环境与依赖
- 需要 Node.js 环境，并在工作区内正确配置工作区根路径（WORKSPACE_ROOT 或 CLI 参数）。
- 服务器可在独立模式运行，或通过 VS Code 内部 MCP API 进行注册与协作。

关键词：翻译管理, 本地化资源, 工具执行, 代码上下文, CodeLens 集成
分类ID：6

i18n CodeLens MCP 服务端

i18n CodeLens MCP 服务端 使用手册