JinDaGe - xcstrings_mcp MCP Details

article

README

🚀 xcstrings-mcp

xcstrings-mcp 是一个用 Rust 实现的 模型上下文协议（MCP）服务器，专为处理 Xcode 的 .xcstrings 文件而设计。它将翻译目录作为 MCP 工具公开，同时还提供一个 轻量级的 Web 编辑器，方便团队通过浏览器浏览、搜索和编辑字符串。

GitHub Stars

注意：本项目在创建过程中借助了 Codex 和 Claude Code 等 AI 工具。尽管我们努力保证质量，但可能仍存在问题或有改进空间。欢迎通过 GitHub Issues 提交 bug 报告、功能请求和贡献代码。

screenshot_alpha

✨ 主要特性

核心翻译功能：提供了一系列用于管理 Xcode Localizable.xcstrings 文件的翻译操作，如列出翻译条目、获取单个翻译、创建或更新翻译、删除翻译等。
键管理功能：支持删除整个翻译键、设置或清除开发者注释以及设置或清除字符串键的提取状态。
语言管理功能：可以列出 .xcstrings 文件中存在的所有语言。
异步安全存储：每次更改时加载并持久化 Localizable.xcstrings 的 JSON 数据。
嵌入式 Axum Web UI：可用于浏览翻译、按查询条件过滤、编辑值、处理复数/设备变体以及管理注释。
自动发现功能：当未提供默认路径时，会自动扫描 .xcstrings 文件，并在 Web UI 中提供选择器以在运行时切换目录。
设备特定变体支持：支持 iPhone、iPad、Mac、Apple Watch 等设备特定变体，并在复数和设备变体之间实现互斥逻辑。
内联编辑功能：支持对提取状态、翻译状态和替换占位符进行内联编辑。
JSON 优先响应：所有工具都以 JSON 格式响应，便于自动化和调试。
基于模式的验证：使用 xcstrings.schema.json 进行模式验证，确保生成的目录与 Apple 的格式一致。

📦 安装指南

前提条件

Rust 1.75 或更高版本：可以使用 Homebrew（推荐在 macOS 上使用）进行安装：

brew install rust

也可以使用官方安装程序进行安装：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装完成后，重启终端或运行 source ~/.cargo/env 以更新 PATH。

运行服务器

cargo run -- [path-to/Localizable.xcstrings] [port]
# 这将构建并运行服务器，针对指定文件在给定端口（默认：8787）上运行

cargo install --path .
# 这将把 `xcstrings-mcp` 安装到 `~/.cargo/bin/` 目录下

path-to/Localizable.xcstrings：可选参数。如果省略，服务器将扫描工作区中的 .xcstrings 文件。Web UI 仍可使用选择器（如果未找到文件则显示占位符），而 MCP 工具调用仍需提供 path 参数。
port：可选参数。默认为 8787。

你还可以通过环境变量配置服务器： | 变量 | 描述 | 默认值 | | ------------ | ---------------------------- | ------------------------ | | STRINGS_PATH | .xcstrings 文件的路径 | 未设置（动态模式） | | WEB_HOST | Web UI 的主机/接口 | 127.0.0.1 | | WEB_PORT | Web UI 的端口 | 8787 |

Web 界面可通过 http://<host>:<port>/ 访问。

💻 使用示例

MCP 使用方法

使用标准输入输出传输（默认）运行二进制文件，并将其连接到支持 MCP 的客户端。以下工具已公开（每个工具都需要一个指向目标 .xcstrings 文件的 path 参数）：

list_translations(path, query?, limit?, include_values?)
get_translation(path, key, language)
upsert_translation(path, key, language, value?, state?, variations?)
delete_translation(path, key, language)
delete_key(path, key)
set_comment(path, key, comment?)
set_extraction_state(path, key, extractionState?)
list_languages(path)

每个工具返回的 JSON 有效负载都编码为文本内容，便于使用。

list_translations 现在返回紧凑摘要（key、comment、extractionState、languages 和 hasVariations），即使对于大型目录，响应也能保持轻量级。使用 limit（默认为 100，设置为 0 表示无限制）对结果进行分页，并在需要内联完整翻译有效负载时传递 include_values: true。将其与 get_translation 结合使用，可在不使客户端上下文过载的情况下获取每种语言的详细信息。

调用 upsert_translation 时，你可以发送：

variations — 将选择器（例如 "plural"）映射到其案例；每个案例都是另一个翻译更新。
substitutions — 将替换标识符（"arg1"、"device" 等）映射到包含 value、state、argNum、formatSpecifier 和嵌套 variations 的更新。缺少的选择器或替换项将保持不变，因此你可以在不重新发送整个本地化有效负载的情况下修补单个部分。

如果服务器在没有默认路径的情况下启动（没有 CLI 参数且没有 STRINGS_PATH），它将扫描工作树中的 .xcstrings 文件，并通过 Web UI 选择器显示这些文件。如果未找到文件，UI 将显示占位符，直到找到文件为止。在这种模式下，MCP 工具仍需要显式的 path 参数。提供默认路径会将选择器固定到该文件，并允许工具调用省略 path 参数。

与 AI 工具集成

现代支持 MCP 的 AI 客户端允许你通过 JSON 清单注册外部服务器。例如，以下代码片段将 xcstrings-mcp 添加到 Claude Code：

claude mcp add-json xcstrings '{"command":"/Users/you/.cargo/bin/xcstrings-mcp","transport":"stdio","env":{"WEB_HOST": "127.0.0.1","WEB_PORT": "8787"}}'

你也可以手动将其添加到 ~/.claude.json：

{
  "mcpServers": {
    "xcstrings": {
      "command": "/Users/you/.cargo/bin/xcstrings-mcp",
      "transport": "stdio",
      "env": {
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "8787"
      }
    }
  }
}

保存后重启客户端，使其加载新的 MCP 服务器定义。在工具调用中，path 参数是可选的 — 如果未提供，服务器将自动发现项目中的所有 .xcstrings 文件，并在 Web 编辑器中列出这些文件以供选择。

若要使用默认本地化文件运行（启用嵌入式 Web UI 并允许工具省略 path），可将位置信息嵌入定义中：

{
  "mcpServers": {
    "xcstrings": {
      "command": "/Users/you/.cargo/bin/xcstrings-mcp",
      "args": ["--", "/Users/you/Projects/Localizable.xcstrings"],
      "transport": "stdio",
      "env": {
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "8787"
      }
    }
  }
}

如果你愿意，也可以通过 STRINGS_PATH 提供路径。无论哪种方式，工具调用都可以省略 path，Web UI 将挂载默认文件。

注意：为了向后兼容，仍然接受带有 XCSTRINGS_ 前缀的旧环境变量，但建议今后使用上述较短的名称。

🔧 技术细节

开发

安装依赖并运行完整的测试套件：

cargo test

提交更改前，建议运行 cargo fmt --all。

仓库将官方模式作为 Git 子模块存储在 schema/ 下。更新验证逻辑时，使用 git submodule update --init --remote 拉取最新定义。

项目结构

src/store.rs：.xcstrings 文件的异步存储层。
src/mcp_server.rs：公开翻译功能的 MCP 工具定义。
src/web/mod.rs：Axum HTTP 路由和 HTML/JS 单页视图。
src/main.rs：启动 Web 和 MCP 服务的入口点。

📄 许可证

本项目基于 MIT 许可证进行分发。

支持

如果你觉得这个项目有用，可以请我喝杯咖啡来支持我。

xcstrings_mcp