@syntholoc/mcp 0.1.2 → 0.3.0

package/README.md

@@ -1,10 +1,55 @@
 # @syntholoc/mcp
 
 The [Syntholoc](https://syntholoc.com) MCP server — manage AI localization and
-translation straight from [Claude Code](https://claude.com/claude-code) (or any
-MCP client), without leaving your editor.
+translation straight from Codex, Claude Code, or any MCP client without leaving
+your editor.
 
-## Add to Claude Code
+## Hosted OAuth
+
+Use the hosted Streamable HTTP endpoint when your MCP client supports OAuth.
+
+### Codex
+
+Add this to `~/.codex/config.toml` (or project `.codex/config.toml` in a trusted
+project):
+
+```toml
+[mcp_servers.syntholoc]
+url = "https://api.syntholoc.com/mcp/v1"
+```
+
+Then authorize:
+
+```bash
+codex mcp login syntholoc
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport http syntholoc https://api.syntholoc.com/mcp/v1
+```
+
+## Local stdio
+
+Use local stdio when you want to run the MCP server as a local process with a
+machine API key.
+
+### Codex
+
+Add this to `~/.codex/config.toml` (or project `.codex/config.toml`):
+
+```toml
+[mcp_servers.syntholoc]
+command = "bunx"
+args = ["@syntholoc/mcp"]
+
+[mcp_servers.syntholoc.env]
+SYNTHOLOC_API_KEY = "<your-api-key>"
+SYNTHOLOC_API_URL = "https://api.syntholoc.com/graphql"
+```
+
+### Claude Code
 
 ```bash
 claude mcp add --transport stdio syntholoc \
@@ -18,13 +63,13 @@ never passed as a tool argument.
 
 ### Environment variables
 
-| Variable | Default | Description |
-|---|---|---|
-| `SYNTHOLOC_API_KEY` | – | Machine API key (`x-api-key`). Required for most tools. |
-| `SYNTHOLOC_API_URL` | `https://api.syntholoc.com/graphql` | GraphQL endpoint. Override to target a self-hosted or local instance. |
-| `SYNTHOLOC_TOOL_SETS` | *(all)* | Comma-separated tool sets to load (`projects,keys,translations,qa,glossary,styleguides,tm,git,providers,jobs,analytics,locales,config`). Fewer tools = a more focused agent. |
-| `SYNTHOLOC_READ_ONLY` | `false` | Set `true` to expose only read-only tools (list/get) — safe exploration and onboarding. |
-| `SYNTHOLOC_TOOL_FILTER` | *(none)* | Comma-separated wildcard patterns matched against tool names (e.g. `list_*,get_*`). |
+| Variable                | Default                             | Description                                                                                                                                                                  |
+| ----------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SYNTHOLOC_API_KEY`     | –                                   | Machine API key (`x-api-key`). Required for most tools.                                                                                                                      |
+| `SYNTHOLOC_API_URL`     | `https://api.syntholoc.com/graphql` | GraphQL endpoint. Override to target a self-hosted or local instance.                                                                                                        |
+| `SYNTHOLOC_TOOL_SETS`   | _(all)_                             | Comma-separated tool sets to load (`projects,keys,translations,qa,glossary,styleguides,tm,git,providers,jobs,analytics,locales,config`). Fewer tools = a more focused agent. |
+| `SYNTHOLOC_READ_ONLY`   | `false`                             | Set `true` to expose only read-only tools (list/get) — safe exploration and onboarding.                                                                                      |
+| `SYNTHOLOC_TOOL_FILTER` | _(none)_                            | Comma-separated wildcard patterns matched against tool names (e.g. `list_*,get_*`).                                                                                          |
 
 > The remote (HTTP) transport accepts the same controls as request headers:
 > `syntholoc-tool-sets`, `syntholoc-read-only`, `syntholoc-tool-filter`. The hosted
@@ -59,10 +104,10 @@ and analytics — plus MCP resources and prompts for common workflows.
 
 Typical asks, one sentence each:
 
-- *"Translate the untranslated German strings and wait for it to finish."*
-- *"Show project progress and the QA score."*
-- *"Add these glossary terms and re-run QA on French."*
-- *"Export the Spanish locale."*
+- _"Translate the untranslated German strings and wait for it to finish."_
+- _"Show project progress and the QA score."_
+- _"Add these glossary terms and re-run QA on French."_
+- _"Export the Spanish locale."_
 
 Translation runs asynchronously and returns a job id; a `wait_for_job` tool
 blocks until completion, so you can chain "translate → wait → export" in a

package/dist/build-server.js

@@ -2,7 +2,7 @@ import {
   TOOL_SET_NAMES,
   buildMcpServer,
   parseList
-} from "./chunk-QOVGANRN.js";
+} from "./chunk-GNXMB53B.js";
 export {
   TOOL_SET_NAMES,
   buildMcpServer,

package/dist/{chunk-QOVGANRN.js → chunk-GNXMB53B.js}

@@ -49,10 +49,15 @@ function registerPrompts(server) {
         "1. Read `.syntholoc/config.json` for the source file(s) and project.",
         projectId ? `   (Use project ${projectId} if config is missing.)` : "",
         "2. From `git diff` on the source file(s), collect added/changed keys and `upsert_keys` (dryRun first to preview).",
+        "   - MULTI-FILE / namespaced project (a file per namespace, e.g. messages/en/home.json): import each",
+        "     changed file with `import_source_strings` passing `keyPrefix` = the namespace (the filename",
+        '     without extension, e.g. "home"). This keeps overlapping keys from different files distinct.',
         "3. Call `get_config` for `maxBulkSize`. For EACH target locale check `locale_progress` \u2192 `untranslated`.",
         "   - If untranslated >= maxBulkSize: `translate_locale` (scope UNTRANSLATED) and `wait_for_job`.",
         "   - If below the threshold: tell me the counts and ASK whether to translate now or accumulate.",
         "4. `export_locale` for each translated locale and write the result back into the mapped local files.",
+        "   - Namespaced project: call `export_locale` once per namespace with the same `keyPrefix` (the prefix",
+        "     is stripped on export) and write each result to its file, e.g. messages/{locale}/home.json.",
         "5. Summarize keys added, locales translated, and the cost from the job usage."
       ].filter(Boolean).join("\n")
     )
@@ -83,12 +88,47 @@ function registerPrompts(server) {
     },
     () => userMessage(
       [
-        "Set up Syntholoc for this repository:",
-        "1. Find the i18n source files (e.g. messages/en.json, locales/en/*.json) and infer the source locale.",
-        "2. `create_project`, then `seed_starter_locales` (or `add_locale`) for the target languages.",
-        "3. `import_source_strings` from the source file(s).",
-        "4. Write `.syntholoc/config.json` mapping source \u2192 translation file patterns and the project id.",
-        "5. Offer to run the localize_changed flow next."
+        "Set up Syntholoc for this repository. PREFER the Git-sync path \u2014 it pulls every",
+        "source string (and any existing translations) in one server-side sync and keeps",
+        "the repo in sync going forward. Only fall back to manual imports if the user",
+        "declines Git or the code lives outside a supported host.",
+        "",
+        "1. Find the i18n source files and infer the source locale. Note the LAYOUT:",
+        "   - Single file per locale (e.g. messages/en.json) \u2192 one mapping, no namespace.",
+        "   - A directory per locale with many namespace files (e.g. messages/en/home.json, common.json) \u2192",
+        "     each file is a NAMESPACE. Syntholoc stores a flat key space, so each file is imported under a",
+        "     `keyPrefix` = its namespace to avoid collisions between files.",
+        "2. `create_project`, then `seed_starter_locales` (or `add_locale`) for the target languages. Use valid",
+        '   BCP-47 codes (e.g. "zh-CN", not "cn"); `add_locale` accepts `code` or `locale`. Region-ambiguous',
+        '   languages MUST be qualified \u2014 "pt" \u2192 "pt-BR" or "pt-PT", "zh" \u2192 "zh-CN" or "zh-TW". The tools reject',
+        '   ambiguous codes and return the candidates; if a source filename is just "pt", ask which region (or',
+        "   default to the likeliest) and record the file\u2192locale mapping in the config `translation` pattern.",
+        "   (Target locales must exist before a Git pull so their translation files import.)",
+        "3. RECOMMENDED \u2014 connect the repo and sync, instead of pushing strings one by one:",
+        "   a. `list_repositories`. If one is already connected, skip to (d).",
+        "   b. Otherwise connect it yourself with `connect_repository`. Ask the user which method they prefer:",
+        "      - GitHub App (no token, recommended): `get_github_app_install_url` \u2192 give the URL to the user",
+        "        to open and authorize (you cannot click it for them; you may offer to open it via the shell).",
+        "        Once they confirm, `list_github_installations` \u2192 `list_github_installation_repos` to pick the",
+        "        repo, then `connect_repository` with that `installationId`.",
+        "      - Token (any host): ask the user to paste a personal access token (repo read + PR scope), then",
+        "        `connect_repository` with `token`. Treat the token as a secret \u2014 do not echo it back.",
+        "   c. Pass `files` = Crowdin-style mappings matching the layout from step 1. NOTE the placeholder",
+        "      syntax differs from the config file: here use %two_letters_code% / %locale% / %original_file_name%",
+        '      (e.g. source "messages/en/home.json", translation "messages/%two_letters_code%/%original_file_name%").',
+        "   d. `sync_repository` \u2014 imports ALL source strings from the repo at once and opens the translation PR.",
+        "      Then `pull_translations` to import any translation files already in the repo (choose `conflict`",
+        "      KEEP_APPROVED to preserve in-app edits).",
+        "   e. `wait_for_job` on the returned job id, then report keys imported and the PR url.",
+        "4. FALLBACK \u2014 file-based import when the user does NOT want Git integration:",
+        "   - Single file \u2192 `import_source_strings` once.",
+        "   - Namespaced \u2192 `import_source_strings` once PER FILE with `keyPrefix` set to the namespace",
+        "     (filename without extension). Keys become e.g. `home.title`, `common.title`.",
+        "5. Write `.syntholoc/config.json` (schema https://syntholoc.com/schemas/config.json): the `projectId` and",
+        "   a Crowdin-style `files` array of `{ source, translation }` patterns with a `{locale}` placeholder,",
+        '   e.g. { "source": "messages/en/home.json", "translation": "messages/{locale}/home.json", "namespace": "home" }.',
+        '   Do NOT invent fields like `i18nDir`, `format: "nested-dirs"`, or `localeMapping` \u2014 they are not read.',
+        "6. Offer to run the localize_changed flow next."
       ].join("\n")
     )
   );
@@ -132,7 +172,10 @@ function registerResources(server, gql) {
       description: "Organizations you belong to (id, name, slug, your role). Pin one for a request with the `syntholoc-org-id` header; otherwise the earliest org is used.",
       mimeType: "application/json"
     },
-    async (uri) => json(uri, (await gql.request(MY_ORGANIZATIONS)).myProjects.map((g) => ({ ...g.organization, viewerRole: g.viewerRole })))
+    async (uri) => json(
+      uri,
+      (await gql.request(MY_ORGANIZATIONS)).myProjects.map((g) => ({ ...g.organization, viewerRole: g.viewerRole }))
+    )
   );
   server.registerResource(
     "projects",
@@ -318,11 +361,23 @@ function registerConfigTools(server, gql) {
 // src/tools/git.ts
 import { z as z3 } from "zod";
 import {
+  CONNECT_REPOSITORY,
+  DISCONNECT_REPOSITORY,
+  GITHUB_APP,
+  GITHUB_INSTALLATIONS,
+  GITHUB_INSTALLATION_REPOS,
   LIST_REPOSITORIES,
   PULL_TRANSLATIONS,
   PUSH_TRANSLATIONS,
-  SYNC_REPOSITORY
+  SYNC_REPOSITORY,
+  UPDATE_REPOSITORY
 } from "@syntholoc/sdk";
+var fileMapping = z3.object({
+  source: z3.string().describe('Source file path or glob, e.g. "messages/en.json" or "locales/en/*.json".'),
+  translation: z3.string().describe(
+    'Translation pattern with Crowdin placeholders, e.g. "messages/%two_letters_code%/%original_file_name%" or "locales/%locale%/%original_file_name%".'
+  )
+});
 function registerGitTools(server, gql) {
   server.registerTool(
     "list_repositories",
@@ -334,6 +389,92 @@ function registerGitTools(server, gql) {
     },
     async ({ projectId }) => jsonResult((await gql.request(LIST_REPOSITORIES, { projectId })).repositories)
   );
+  server.registerTool(
+    "get_github_app_install_url",
+    {
+      title: "GitHub App install URL",
+      description: "Returns whether the Syntholoc GitHub App is available and a signed install URL for this project. GitHub App connect flow, step 1: give this URL to the user to open in a browser and authorize Syntholoc on the repositories they want (this authorize click cannot be automated). After they finish, call `list_github_installations` to see the new installation. If `enabled` is false, the server has no GitHub App configured \u2014 fall back to the token (PAT) path via `connect_repository`.",
+      inputSchema: { projectId: z3.string() },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async ({ projectId }) => jsonResult((await gql.request(GITHUB_APP, { projectId })).githubApp)
+  );
+  server.registerTool(
+    "list_github_installations",
+    {
+      title: "List GitHub installations",
+      description: "Lists GitHub App installations available to the active organization. GitHub App connect flow, step 2: run this after the user authorized the App (see `get_github_app_install_url`) to get the `installationId` to pass to `list_github_installation_repos` and `connect_repository`.",
+      inputSchema: { projectId: z3.string() },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async ({ projectId }) => jsonResult((await gql.request(GITHUB_INSTALLATIONS, { projectId })).githubInstallations)
+  );
+  server.registerTool(
+    "list_github_installation_repos",
+    {
+      title: "List installation repositories",
+      description: "Lists the repositories Syntholoc can access through a GitHub App installation. GitHub App connect flow, step 3: pick the target repo (its `fullName` and `defaultBranch`) before calling `connect_repository` with the same `installationId`.",
+      inputSchema: {
+        projectId: z3.string(),
+        installationId: z3.number().int().describe("From `list_github_installations`.")
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async ({ projectId, installationId }) => jsonResult((await gql.request(GITHUB_INSTALLATION_REPOS, { projectId, installationId })).githubInstallationRepos)
+  );
+  server.registerTool(
+    "connect_repository",
+    {
+      title: "Connect repository",
+      description: "Connects a git repository to the project so syncs can pull source strings and push translation PRs. Provide EITHER `installationId` (GitHub App mode \u2014 after the browser authorize flow: `get_github_app_install_url` \u2192 `list_github_installations` \u2192 `list_github_installation_repos`) OR `token` (PAT mode \u2014 a personal access token with repo read + pull-request scope; works for GitHub, GitLab and Bitbucket, no browser needed). Set `files` to Crowdin-style mappings that match the project layout. After connecting, call `sync_repository` to import all source strings at once.",
+      inputSchema: {
+        projectId: z3.string(),
+        provider: z3.enum(["GITHUB", "GITLAB", "BITBUCKET"]).default("GITHUB"),
+        fullName: z3.string().describe('owner/repo, e.g. "acme/webapp".'),
+        branch: z3.string().optional().describe('Source branch (default "main").'),
+        files: z3.array(fileMapping).optional().describe("Crowdin-style source\u2192translation mappings."),
+        paths: z3.array(z3.string()).optional().describe("Simple mode: source file paths/globs to track (use instead of `files`)."),
+        installationId: z3.number().int().optional().describe("GitHub App installation id. Mutually exclusive with `token`."),
+        token: z3.string().optional().describe("Access token (PAT mode), stored encrypted. Mutually exclusive with `installationId`."),
+        translationBranch: z3.string().optional().describe("Branch translations are committed to (default l10n_<branch>)."),
+        prTargetBranch: z3.string().optional().describe("Branch translation PRs target (default = branch)."),
+        autoSyncEnabled: z3.boolean().optional().describe("Enable scheduled auto-sync.")
+      },
+      annotations: { openWorldHint: true }
+    },
+    async ({ projectId, ...input }) => jsonResult((await gql.request(CONNECT_REPOSITORY, { projectId, input })).connectRepository)
+  );
+  server.registerTool(
+    "update_repository",
+    {
+      title: "Update repository",
+      description: "Updates the configuration of an already-connected repository in place \u2014 no disconnect/reconnect, stored credentials and webhooks are preserved. Use this to fix or change file mappings (`files` or `paths`), the source `branch`, the translation/PR branches, or auto-sync settings. Only the fields you pass are changed. After changing mappings, call `sync_repository` to re-import source strings.",
+      inputSchema: {
+        projectId: z3.string(),
+        repositoryId: z3.string(),
+        branch: z3.string().optional().describe("Source branch."),
+        files: z3.array(fileMapping).optional().describe("Crowdin-style source\u2192translation mappings (replaces existing)."),
+        paths: z3.array(z3.string()).optional().describe("Simple mode: source file paths/globs to track (replaces existing; use instead of `files`)."),
+        translationBranch: z3.string().optional().describe("Branch translations are committed to."),
+        prTargetBranch: z3.string().optional().describe("Branch translation PRs target."),
+        pushSources: z3.boolean().optional().describe("Rewrite the source file(s) in the repo from in-app keys."),
+        autoSyncEnabled: z3.boolean().optional().describe("Enable scheduled auto-sync."),
+        syncIntervalHours: z3.number().int().optional().describe("Auto-sync interval in hours.")
+      },
+      annotations: { openWorldHint: true }
+    },
+    async ({ projectId, repositoryId, ...input }) => jsonResult((await gql.request(UPDATE_REPOSITORY, { projectId, id: repositoryId, input })).updateRepository)
+  );
+  server.registerTool(
+    "disconnect_repository",
+    {
+      title: "Disconnect repository",
+      description: "Removes the link to a connected repository and its stored credentials. The repository itself is not affected. Destructive \u2014 confirm with the user first.",
+      inputSchema: { projectId: z3.string(), repositoryId: z3.string() },
+      annotations: { destructiveHint: true, openWorldHint: true }
+    },
+    async ({ projectId, repositoryId }) => jsonResult((await gql.request(DISCONNECT_REPOSITORY, { projectId, id: repositoryId })).disconnectRepository)
+  );
   server.registerTool(
     "sync_repository",
     {
@@ -505,7 +646,7 @@ import {
   UPDATE_KEY,
   UPSERT_KEYS
 } from "@syntholoc/sdk";
-var FORMATS = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS"];
+var FORMATS = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
 function registerKeyTools(server, gql) {
   server.registerTool(
     "list_keys",
@@ -575,17 +716,24 @@ function registerKeyTools(server, gql) {
     "import_source_strings",
     {
       title: "Import source strings",
-      description: "Imports source strings from a file (paste the raw content) and returns the diff summary. Use `dryRun` to preview. For a structured delta prefer upsert_keys.",
+      description: 'Imports source strings from ONE file (paste the raw content) and returns the diff summary. For initial setup of a repo-hosted project, PREFER connecting the repo and running `sync_repository` \u2014 it imports every source file server-side in one pass; use this tool only for file-based projects with no Git integration, or for one-off single-file imports. For a multi-file / namespaced project (a file per namespace, e.g. messages/en/home.json), pass `keyPrefix` (the namespace, e.g. "home") so keys become `home.title` and files with overlapping top-level keys do not collide \u2014 call once per file. Use `dryRun` to preview.',
       inputSchema: {
         projectId: z6.string(),
         content: z6.string(),
         format: z6.enum(FORMATS),
+        keyPrefix: z6.string().optional().describe('Namespace prefix, e.g. "home" (per-file, multi-file projects).'),
+        sourceFile: z6.string().optional().describe(
+          'Real source file path, e.g. "messages/en/home.json" \u2014 stored for the file tree + reliable export.'
+        ),
         dryRun: z6.boolean().default(false)
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
-    async ({ projectId, content, format, dryRun }) => jsonResult(
-      (await gql.request(IMPORT_SOURCE_STRINGS, { projectId, input: { content, format, dryRun } })).importSourceStrings
+    async ({ projectId, content, format, keyPrefix, sourceFile, dryRun }) => jsonResult(
+      (await gql.request(IMPORT_SOURCE_STRINGS, {
+        projectId,
+        input: { content, format, keyPrefix, sourceFile, dryRun }
+      })).importSourceStrings
     )
   );
 }
@@ -593,6 +741,158 @@ function registerKeyTools(server, gql) {
 // src/tools/locales.ts
 import { z as z7 } from "zod";
 import { ADD_LOCALE, LIST_LOCALES as LIST_LOCALES2, REMOVE_LOCALE, SEED_STARTER_LOCALES } from "@syntholoc/sdk";
+
+// ../../packages/shared/src/locales.ts
+var STARTER_LOCALES = [
+  { code: "ar", name: "Arabic", nativeName: "\u0627\u0644\u0639\u0631\u0628\u064A\u0629", rtl: true },
+  { code: "az", name: "Azerbaijani", nativeName: "Az\u0259rbaycan" },
+  { code: "be", name: "Belarusian", nativeName: "\u0411\u0435\u043B\u0430\u0440\u0443\u0441\u043A\u0430\u044F" },
+  { code: "bn", name: "Bengali", nativeName: "\u09AC\u09BE\u0982\u09B2\u09BE" },
+  { code: "cs", name: "Czech", nativeName: "\u010Ce\u0161tina" },
+  { code: "de", name: "German", nativeName: "Deutsch" },
+  { code: "el", name: "Greek", nativeName: "\u0395\u03BB\u03BB\u03B7\u03BD\u03B9\u03BA\u03AC" },
+  { code: "en", name: "English", nativeName: "English" },
+  { code: "es", name: "Spanish", nativeName: "Espa\xF1ol" },
+  { code: "es-419", name: "Spanish (Latin America)", nativeName: "Espa\xF1ol (Latinoam\xE9rica)" },
+  { code: "fa", name: "Persian", nativeName: "\u0641\u0627\u0631\u0633\u06CC", rtl: true },
+  { code: "fr", name: "French", nativeName: "Fran\xE7ais" },
+  { code: "hi", name: "Hindi", nativeName: "\u0939\u093F\u0928\u094D\u0926\u0940" },
+  { code: "hy", name: "Armenian", nativeName: "\u0540\u0561\u0575\u0565\u0580\u0565\u0576" },
+  { code: "id", name: "Indonesian", nativeName: "Bahasa Indonesia" },
+  { code: "it", name: "Italian", nativeName: "Italiano" },
+  { code: "ja", name: "Japanese", nativeName: "\u65E5\u672C\u8A9E" },
+  { code: "ka", name: "Georgian", nativeName: "\u10E5\u10D0\u10E0\u10D7\u10E3\u10DA\u10D8" },
+  { code: "kk", name: "Kazakh", nativeName: "\u049A\u0430\u0437\u0430\u049B \u0442\u0456\u043B\u0456" },
+  { code: "ko", name: "Korean", nativeName: "\uD55C\uAD6D\uC5B4" },
+  { code: "lv", name: "Latvian", nativeName: "Latvie\u0161u" },
+  { code: "ms", name: "Malay", nativeName: "Bahasa Melayu" },
+  { code: "nl", name: "Dutch", nativeName: "Nederlands" },
+  { code: "pl", name: "Polish", nativeName: "Polski" },
+  { code: "pt-BR", name: "Portuguese (Brazil)", nativeName: "Portugu\xEAs (Brasil)" },
+  { code: "pt-PT", name: "Portuguese (Portugal)", nativeName: "Portugu\xEAs (Portugal)" },
+  { code: "ro", name: "Romanian", nativeName: "Rom\xE2n\u0103" },
+  { code: "ru", name: "Russian", nativeName: "\u0420\u0443\u0441\u0441\u043A\u0438\u0439" },
+  { code: "sk", name: "Slovak", nativeName: "Sloven\u010Dina" },
+  { code: "sl", name: "Slovenian", nativeName: "Sloven\u0161\u010Dina" },
+  { code: "sw", name: "Swahili", nativeName: "Kiswahili" },
+  { code: "th", name: "Thai", nativeName: "\u0E44\u0E17\u0E22" },
+  { code: "tl", name: "Filipino", nativeName: "Filipino" },
+  { code: "tr", name: "Turkish", nativeName: "T\xFCrk\xE7e" },
+  { code: "uk", name: "Ukrainian", nativeName: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430" },
+  { code: "ur", name: "Urdu", nativeName: "\u0627\u0631\u062F\u0648", rtl: true },
+  { code: "uz", name: "Uzbek", nativeName: "O\u02BBzbek" },
+  { code: "vi", name: "Vietnamese", nativeName: "Ti\u1EBFng Vi\u1EC7t" },
+  { code: "zh-CN", name: "Chinese (Simplified)", nativeName: "\u7B80\u4F53\u4E2D\u6587" },
+  { code: "zh-TW", name: "Chinese (Traditional)", nativeName: "\u7E41\u9AD4\u4E2D\u6587" }
+];
+var STARTER_LOCALE_CODES = STARTER_LOCALES.map((l) => l.code);
+var STARTER_BY_CODE = new Map(STARTER_LOCALES.map((l) => [l.code, l]));
+function findStarterLocale(code) {
+  return STARTER_BY_CODE.get(code);
+}
+
+// ../../packages/shared/src/locale-resolve.ts
+var ALIASES = {
+  cn: "zh-CN",
+  "zh-hans": "zh-CN",
+  "zh-hant": "zh-TW",
+  jp: "ja",
+  kr: "ko",
+  ua: "uk",
+  cz: "cs",
+  gr: "el",
+  iw: "he",
+  // legacy Hebrew
+  in: "id"
+  // legacy Indonesian
+};
+var VARIANTS_BY_LANG = (() => {
+  const map = /* @__PURE__ */ new Map();
+  for (const { code } of STARTER_LOCALES) {
+    const lang = code.split("-")[0].toLowerCase();
+    (map.get(lang) ?? map.set(lang, []).get(lang)).push(code);
+  }
+  return map;
+})();
+function canonicalize(input) {
+  try {
+    return Intl.getCanonicalLocales(input)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function isRealLanguage(code) {
+  try {
+    const name = new Intl.DisplayNames(["en"], { type: "language" }).of(code);
+    return !!name && name.toLowerCase() !== code.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+function resolveLocaleCode(raw) {
+  const input = raw.trim();
+  if (!input) {
+    return { status: "unknown", input: raw, message: "Empty locale code." };
+  }
+  const alias = ALIASES[input.toLowerCase()];
+  if (alias) {
+    return { status: "normalized", code: alias, from: input, reason: `mapped "${input}" to catalog code "${alias}"` };
+  }
+  const canonical = canonicalize(input);
+  if (!canonical) {
+    return { status: "unknown", input, message: `"${input}" is not a valid BCP-47 locale code.` };
+  }
+  if (findStarterLocale(canonical)) {
+    return canonical === input ? { status: "ok", code: canonical } : { status: "normalized", code: canonical, from: input, reason: `casing normalized to "${canonical}"` };
+  }
+  const lang = canonical.split("-")[0].toLowerCase();
+  const hasRegionOrScript = canonical.includes("-");
+  const variants = VARIANTS_BY_LANG.get(lang) ?? [];
+  if (!hasRegionOrScript) {
+    if (variants.length > 1) {
+      return {
+        status: "ambiguous",
+        input,
+        candidates: variants,
+        message: `"${input}" is ambiguous \u2014 the catalog has ${variants.join(", ")}. Pick one.`
+      };
+    }
+    if (variants.length === 1) {
+      return {
+        status: "normalized",
+        code: variants[0],
+        from: input,
+        reason: `expanded "${input}" to "${variants[0]}"`
+      };
+    }
+    return isRealLanguage(canonical) ? { status: "ok", code: canonical } : { status: "unknown", input, message: `"${input}" is not a recognized language.` };
+  }
+  if (!isRealLanguage(canonical)) {
+    return { status: "unknown", input, message: `"${input}" is not a valid locale.` };
+  }
+  return canonical === input ? { status: "ok", code: canonical } : { status: "normalized", code: canonical, from: input, reason: `canonicalized to "${canonical}"` };
+}
+function resolveLocaleCodes(raw) {
+  const out = { codes: [], normalized: [], rejected: [] };
+  const seen = /* @__PURE__ */ new Set();
+  for (const code of raw) {
+    const res = resolveLocaleCode(code);
+    if (res.status === "ambiguous") {
+      out.rejected.push({ input: res.input, message: res.message, candidates: res.candidates });
+    } else if (res.status === "unknown") {
+      out.rejected.push({ input: res.input, message: res.message });
+    } else {
+      if (res.status === "normalized") out.normalized.push({ from: res.from, code: res.code, reason: res.reason });
+      if (!seen.has(res.code)) {
+        seen.add(res.code);
+        out.codes.push(res.code);
+      }
+    }
+  }
+  return out;
+}
+
+// src/tools/locales.ts
 function registerLocaleTools(server, gql) {
   server.registerTool(
     "list_locales",
@@ -608,10 +908,13 @@ function registerLocaleTools(server, gql) {
     "add_locale",
     {
       title: "Add locale",
-      description: "Adds a target locale (BCP-47 code) to a project.",
+      description: 'Adds ONE target locale to a project. To add several at once, prefer seed_starter_locales (one call for the whole list). Codes are validated: aliases/casing are normalized (e.g. "cn" \u2192 "zh-CN"), and ambiguous macro-languages (e.g. "pt", "zh") are rejected with the concrete variants to choose from (pt-BR / pt-PT, zh-CN / zh-TW).',
       inputSchema: {
         projectId: z7.string(),
-        code: z7.string().describe('BCP-47 code, e.g. "de-DE"'),
+        // `code` and `locale` are aliases — accept either so the natural
+        // `locale: "de-DE"` form works as well as `code`.
+        code: z7.string().optional().describe('BCP-47 code, e.g. "de-DE" or "ru". Alias: `locale`.'),
+        locale: z7.string().optional().describe("Alias for `code`."),
         name: z7.string().optional(),
         formality: z7.string().optional(),
         gender: z7.string().optional(),
@@ -619,17 +922,55 @@ function registerLocaleTools(server, gql) {
       },
       annotations: { openWorldHint: true }
     },
-    async ({ projectId, ...input }) => jsonResult((await gql.request(ADD_LOCALE, { projectId, input })).addLocale)
+    async ({ projectId, code, locale, name, formality, gender, variant }) => {
+      const resolvedCode = code ?? locale;
+      if (!resolvedCode) {
+        return jsonResult({
+          error: 'Missing locale code. Pass `code` (BCP-47, e.g. "de-DE" or "ru"). To add several locales at once, use seed_starter_locales with a `codes` array.'
+        });
+      }
+      const res = resolveLocaleCode(resolvedCode);
+      if (res.status === "ambiguous") {
+        return jsonResult({
+          error: res.message,
+          hint: `Retry add_locale with one of: ${res.candidates.join(", ")}.`,
+          candidates: res.candidates
+        });
+      }
+      if (res.status === "unknown") {
+        return jsonResult({ error: res.message, hint: 'Use a valid BCP-47 code, e.g. "de-DE" or "zh-CN".' });
+      }
+      const input = { code: res.code, name, formality, gender, variant };
+      const added = (await gql.request(ADD_LOCALE, { projectId, input })).addLocale;
+      return res.status === "normalized" ? jsonResult({ ...added, note: `Interpreted "${res.from}" as "${res.code}" (${res.reason}).` }) : jsonResult(added);
+    }
   );
   server.registerTool(
     "seed_starter_locales",
     {
       title: "Seed starter locales",
-      description: "Adds a set of common starter locales to a project (omit codes for the defaults).",
-      inputSchema: { projectId: z7.string(), codes: z7.array(z7.string()).optional() },
+      description: 'Adds MULTIPLE target locales in one call \u2014 pass `codes` (BCP-47, e.g. ["ru","de-DE","fr"]), or omit for a common starter set. Prefer this over repeated add_locale calls. Codes are validated as a batch: if any are ambiguous (e.g. "pt", "zh") or invalid, NONE are added and the response lists what to fix; aliases like "cn" are normalized to "zh-CN".',
+      inputSchema: {
+        projectId: z7.string(),
+        codes: z7.array(z7.string()).optional().describe('BCP-47 codes to add, e.g. ["ru","de-DE","fr"].')
+      },
       annotations: { openWorldHint: true }
     },
-    async ({ projectId, codes }) => jsonResult((await gql.request(SEED_STARTER_LOCALES, { projectId, codes })).seedStarterLocales)
+    async ({ projectId, codes }) => {
+      if (codes && codes.length > 0) {
+        const resolved = resolveLocaleCodes(codes);
+        if (resolved.rejected.length > 0) {
+          return jsonResult({
+            error: "Some locale codes are ambiguous or invalid; nothing was added.",
+            hint: "Fix the codes below and retry. For ambiguous ones, pick a listed candidate.",
+            rejected: resolved.rejected
+          });
+        }
+        const seeded = (await gql.request(SEED_STARTER_LOCALES, { projectId, codes: resolved.codes })).seedStarterLocales;
+        return resolved.normalized.length > 0 ? jsonResult({ locales: seeded, normalized: resolved.normalized }) : jsonResult(seeded);
+      }
+      return jsonResult((await gql.request(SEED_STARTER_LOCALES, { projectId, codes })).seedStarterLocales);
+    }
   );
   server.registerTool(
     "remove_locale",
@@ -906,7 +1247,7 @@ import {
   TRANSLATE_KEY,
   TRANSLATE_LOCALE
 } from "@syntholoc/sdk";
-var FORMATS2 = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS"];
+var FORMATS2 = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
 function registerTranslationTools(server, gql) {
   server.registerTool(
     "translate_locale",
@@ -989,12 +1330,14 @@ function registerTranslationTools(server, gql) {
     "export_locale",
     {
       title: "Export locale",
-      description: "Exports a locale to a file string in the chosen format \u2014 the basis for writing translations back into local files. Set `onlyApproved` to exclude drafts.",
+      description: 'Exports a locale to a file string in the chosen format \u2014 the basis for writing translations back into local files. Set `onlyApproved` to exclude drafts. For a multi-file project prefer `sourceFile` (the real path, e.g. "messages/en/home.json") to export exactly that file with file-local key names \u2014 reliable. `keyPrefix` is the legacy name-prefix heuristic.',
       inputSchema: {
         projectId: z13.string(),
         localeId: z13.string(),
         format: z13.enum(FORMATS2).default("JSON"),
-        onlyApproved: z13.boolean().optional()
+        onlyApproved: z13.boolean().optional(),
+        sourceFile: z13.string().optional().describe('Real source file path to export, e.g. "messages/en/home.json" (reliable, preferred).'),
+        keyPrefix: z13.string().optional().describe('Legacy namespace prefix, e.g. "home".')
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -1004,23 +1347,24 @@ function registerTranslationTools(server, gql) {
     "import_translations",
     {
       title: "Import translations",
-      description: "Imports ready-made translations for a locale (paste file content). `autoApprove` lands them as APPROVED; `conflict` is OVERWRITE | SKIP_EXISTING | KEEP_APPROVED; `dryRun` previews.",
+      description: "Imports ready-made translations for a locale (paste file content). `autoApprove` lands them as APPROVED; `conflict` is OVERWRITE | SKIP_EXISTING | KEEP_APPROVED; `dryRun` previews. For a multi-file / namespaced project pass `keyPrefix` (the namespace) to match prefixed source keys.",
       inputSchema: {
         projectId: z13.string(),
         localeId: z13.string(),
         content: z13.string(),
         format: z13.enum(FORMATS2),
+        keyPrefix: z13.string().optional().describe('Namespace prefix, e.g. "home" (per-file, multi-file projects).'),
         autoApprove: z13.boolean().default(false),
         conflict: z13.enum(["OVERWRITE", "SKIP_EXISTING", "KEEP_APPROVED"]).default("OVERWRITE"),
         dryRun: z13.boolean().default(false)
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
-    async ({ projectId, localeId, content, format, autoApprove, conflict, dryRun }) => jsonResult(
+    async ({ projectId, localeId, content, format, keyPrefix, autoApprove, conflict, dryRun }) => jsonResult(
       (await gql.request(IMPORT_TRANSLATIONS, {
         projectId,
         localeId,
-        input: { content, format, autoApprove, conflict, dryRun }
+        input: { content, format, keyPrefix, autoApprove, conflict, dryRun }
       })).importTranslations
     )
   );
@@ -1054,9 +1398,12 @@ function registerAllTools(server, gql, opts = {}) {
   }
 }
 
+// package.json
+var version = "0.3.0";
+
 // src/build-server.ts
 function buildMcpServer(gql, opts = {}) {
-  const server = new McpServer({ name: "syntholoc", version: "0.1.0" });
+  const server = new McpServer({ name: "syntholoc", version });
   registerAllTools(server, gql, opts);
   registerResources(server, gql);
   registerPrompts(server);

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   buildMcpServer,
   parseList
-} from "./chunk-QOVGANRN.js";
+} from "./chunk-GNXMB53B.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@syntholoc/mcp",
-  "version": "0.1.2",
-  "description": "Syntholoc MCP server — manage AI localization and translation from Claude Code.",
+  "version": "0.3.0",
+  "description": "Syntholoc MCP server — manage AI localization and translation from Codex, Claude Code, and other MCP clients.",
   "homepage": "https://syntholoc.com",
   "keywords": [
     "syntholoc",
@@ -10,6 +10,7 @@
     "translation",
     "mcp",
     "model-context-protocol",
+    "codex",
     "claude-code"
   ],
   "type": "module",
@@ -46,12 +47,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.22.0",
-    "@syntholoc/sdk": "0.1.1",
+    "@syntholoc/sdk": "0.2.0",
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "@syntholoc/shared": "0.1.0",
     "@types/bun": "1.3.14",
     "@types/node": "22.19.21",
+    "graphql": "16.14.2",
     "tsup": "8.5.1",
     "typescript": "6.0.3"
   }