@syntholoc/mcp 0.1.2 → 0.2.0

package/dist/build-server.js

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

package/dist/{chunk-QOVGANRN.js → chunk-DZKWHV2O.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")
     )
@@ -84,10 +89,21 @@ 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.",
+        "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 import each file 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`.',
+        "3. Import the source strings:",
+        "   - 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`.",
+        "4. 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.',
         "5. Offer to run the localize_changed flow next."
       ].join("\n")
     )
@@ -575,17 +591,22 @@ 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 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
     )
   );
 }
@@ -608,10 +629,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).",
       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,14 +643,26 @@ 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 input = { code: resolvedCode, name, formality, gender, variant };
+      return jsonResult((await gql.request(ADD_LOCALE, { projectId, input })).addLocale);
+    }
   );
   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.',
+      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)
@@ -989,12 +1025,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 +1042,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
     )
   );

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntholoc/mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Syntholoc MCP server — manage AI localization and translation from Claude Code.",
   "homepage": "https://syntholoc.com",
   "keywords": [