@syntholoc/mcp 0.3.0 → 0.3.1

package/dist/build-server.js

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

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

@@ -105,30 +105,35 @@ function registerPrompts(server) {
         "   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:",
+        "   a. `list_repositories`. If one is already connected, skip to (e).",
+        "   b. Write `.syntholoc/config.json` FIRST and commit it to the source branch \u2014 the server reads it",
+        "      from the repo as the SOURCE OF TRUTH for mappings on every sync/pull/write-back (Crowdin-style),",
+        "      so it must land in the branch before the first sync. Schema (https://syntholoc.com/schemas/config.json):",
+        "      the `projectId`, `sourceLocale`, and a Crowdin-style `files` array of `{ source, translation }`",
+        '      patterns, e.g. { "source": "messages/en/*.json", "translation": "messages/{locale}/%original_file_name%" }.',
+        "      - Placeholders: `{locale}` (or %locale% / %two_letters_code% / %original_file_name% / %original_path%).",
+        `      - If a locale's ON-DISK code differs from its BCP-47 code (e.g. "zh-CN" stored as "cn", "pt-BR" as "pt"),`,
+        '        add `languagesMapping`, e.g. { "two_letters_code": { "zh-CN": "cn", "pt-BR": "pt" } }.',
+        '      - Do NOT invent fields like `i18nDir`, `format: "nested-dirs"`, or `localeMapping` \u2014 they are not read.',
+        "   c. Connect it 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.",
+        "   d. `files`/`paths` on `connect_repository` are an OPTIONAL fallback used only when the repo has no",
+        "      committed `.syntholoc/config.json`. If you committed the config in (b) you may pass the same `files`",
+        "      for redundancy, but the in-repo config wins. Same Crowdin placeholders as the config file.",
+        "   e. `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.",
+        "   f. `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."
+        "5. Offer to run the localize_changed flow next."
       ].join("\n")
     )
   );
@@ -376,6 +381,9 @@ 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%".'
+  ),
+  languagesMapping: z3.record(z3.string(), z3.record(z3.string(), z3.string())).optional().describe(
+    'Crowdin `languages_mapping`: per-placeholder, per-locale path overrides. Keyed by placeholder name without % (e.g. "two_letters_code", "locale"), then by locale code, to the on-disk replacement. E.g. { "two_letters_code": { "zh-CN": "cn" } } writes Chinese under "cn" instead of "zh".'
   )
 });
 function registerGitTools(server, gql) {
@@ -426,14 +434,14 @@ function registerGitTools(server, gql) {
     "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.",
+      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). Mappings come from the repo's `.syntholoc/config.json` when present (the source of truth); `files`/`paths` here are an optional fallback used only when that file is absent. 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`)."),
+        files: z3.array(fileMapping).optional().describe("Crowdin-style source\u2192translation mappings. Fallback only \u2014 an in-repo `.syntholoc/config.json` wins."),
+        paths: z3.array(z3.string()).optional().describe("Simple mode: source file paths/globs to track (use instead of `files`). Fallback for in-repo config."),
         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>)."),
@@ -448,7 +456,7 @@ function registerGitTools(server, gql) {
     "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.",
+      description: "Updates an already-connected repository in place \u2014 no disconnect/reconnect, stored credentials and webhooks are preserved. Use it for integration settings (source `branch`, translation/PR branches, `pushSources`, auto-sync), and for `files`/`paths` only as the DB fallback. IMPORTANT: to change file MAPPINGS, prefer editing the repo's `.syntholoc/config.json` and opening a PR \u2014 that file is the source of truth and, when present, overrides `files`/`paths` here (they are ignored). So do NOT use this tool to change mappings of a config-managed repo; edit the file, open a PR, and after it merges call `sync_repository`. Only the fields you pass are changed.",
       inputSchema: {
         projectId: z3.string(),
         repositoryId: z3.string(),
@@ -1399,7 +1407,7 @@ function registerAllTools(server, gql, opts = {}) {
 }
 
 // package.json
-var version = "0.3.0";
+var version = "0.3.1";
 
 // src/build-server.ts
 function buildMcpServer(gql, opts = {}) {

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntholoc/mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Syntholoc MCP server — manage AI localization and translation from Codex, Claude Code, and other MCP clients.",
   "homepage": "https://syntholoc.com",
   "keywords": [
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.22.0",
-    "@syntholoc/sdk": "0.2.0",
+    "@syntholoc/sdk": "0.3.0",
     "zod": "3.25.76"
   },
   "devDependencies": {