Xcstrings MCP

🚀 xcstrings-mcp

xcstrings-mcp 是一個用 Rust 實現的 模型上下文協議（MCP）服務器，專為處理 Xcode 的 .xcstrings 文件而設計。它將翻譯目錄作為 MCP 工具公開，同時還提供一個 輕量級的 Web 編輯器，方便團隊通過瀏覽器瀏覽、搜索和編輯字符串。

注意：本項目在創建過程中藉助了 Codex 和 Claude Code 等 AI 工具。儘管我們努力保證質量，但可能仍存在問題或有改進空間。歡迎通過 GitHub Issues 提交 bug 報告、功能請求和貢獻代碼。

✨ 主要特性

• 核心翻譯功能：提供了一系列用於管理 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。

你還可以通過環境變量配置服務器：

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 許可證 進行分發。

支持

如果你覺得這個項目有用，可以請我喝杯咖啡來支持我。