@syntholoc/mcp 0.3.1 → 0.5.0

package/README.md

@@ -113,6 +113,27 @@ 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
 single request.
 
+## Contributing: adding a tool
+
+Tools are authored by hand — the curated descriptions, input aliases, and
+validation are what make an LLM use them well, so they are deliberately not
+generated one-per-operation. Two mechanisms keep the manual layer honest:
+
+- **Generated input shapes.** `bun run codegen` emits zod schemas for every
+  GraphQL input type into `src/generated/input-schemas.ts` from the API's
+  committed SDL. Compose a schema's `.shape` instead of re-typing a mutation's
+  fields, then curate on top — see `configure_llm_provider` in
+  `src/tools/providers.ts`, which spreads `ConfigureProviderInputSchema().shape`
+  and tightens the API's free-form `type: String` down to a concrete enum.
+- **Drift guard.** `src/operation-coverage.spec.ts` fails the build when an
+  operation exported by `@syntholoc/sdk` is not surfaced by any tool or resource
+  (or explicitly exempted). Add an operation to the SDK and you must either wire
+  up a tool/resource or record why it is MCP-exempt.
+
+Every tool set has contract tests (`src/tools/*.spec.ts`) that pin both the
+GraphQL operation + variables a tool emits and the JSON it returns, via an
+in-memory MCP client against a mock GraphQL client (`src/spec-helpers.ts`).
+
 ## License
 
 MIT

package/dist/build-server.js

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

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

@@ -115,6 +115,12 @@ function registerPrompts(server) {
         `      - 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.',
+        "      - CRITICAL: `.syntholoc/config.json` MUST be committed and tracked \u2014 it is the mapping source of",
+        "        truth the server reads from the branch. NEVER add `.syntholoc` (or the config file) to `.gitignore`.",
+        "        If `.gitignore` already ignores it (a common reflex, next to `.claude`), remove that line. After",
+        "        committing, VERIFY it is tracked (e.g. `git ls-files .syntholoc/config.json` returns the path, or",
+        "        `git check-ignore` reports nothing) \u2014 an ignored config means every sync/pull/write-back resolves",
+        "        zero files and silently opens no PR.",
         "   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).",
@@ -300,6 +306,9 @@ import { COST_ANALYTICS, LOCALE_PROGRESS, PROJECT_ANALYTICS as PROJECT_ANALYTICS
 function jsonResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
 
 // src/tools/analytics.ts
 function registerAnalyticsTools(server, gql) {
@@ -440,8 +449,12 @@ function registerGitTools(server, gql) {
         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. 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."),
+        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>)."),
@@ -507,7 +520,7 @@ function registerGitTools(server, gql) {
     "pull_translations",
     {
       title: "Pull translations",
-      description: "Pulls translation files from the connected repo and imports them per locale. `autoApprove` lands them as APPROVED; `conflict` is OVERWRITE | SKIP_EXISTING | KEEP_APPROVED.",
+      description: "Queues a pull of translation files from the connected repo, importing them per locale. Returns the tracking job ids \u2014 the import itself runs in the background. `autoApprove` lands them as APPROVED; `conflict` is OVERWRITE | SKIP_EXISTING | KEEP_APPROVED.",
       inputSchema: {
         projectId: z3.string(),
         repositoryId: z3.string(),
@@ -654,7 +667,8 @@ import {
   UPDATE_KEY,
   UPSERT_KEYS
 } from "@syntholoc/sdk";
-var FORMATS = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
+var FORMATS = ["JSON", "YAML", "MARKDOWN", "MDX", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
+var DOCUMENT_FORMATS = /* @__PURE__ */ new Set(["MARKDOWN", "MDX"]);
 function registerKeyTools(server, gql) {
   server.registerTool(
     "list_keys",
@@ -724,7 +738,7 @@ function registerKeyTools(server, gql) {
     "import_source_strings",
     {
       title: "Import source strings",
-      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.',
+      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. For MARKDOWN and MDX `sourceFile` is REQUIRED: the document is split into per-block segments, and without the file path a re-import cannot tell a moved paragraph from an edited one.',
       inputSchema: {
         projectId: z6.string(),
         content: z6.string(),
@@ -737,12 +751,17 @@ function registerKeyTools(server, gql) {
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
-    async ({ projectId, content, format, keyPrefix, sourceFile, dryRun }) => jsonResult(
-      (await gql.request(IMPORT_SOURCE_STRINGS, {
-        projectId,
-        input: { content, format, keyPrefix, sourceFile, dryRun }
-      })).importSourceStrings
-    )
+    async ({ projectId, content, format, keyPrefix, sourceFile, dryRun }) => {
+      if (DOCUMENT_FORMATS.has(format) && !sourceFile?.trim()) {
+        return errorResult(`${format} needs a sourceFile \u2014 a document's segments only have an identity within a file.`);
+      }
+      return jsonResult(
+        (await gql.request(IMPORT_SOURCE_STRINGS, {
+          projectId,
+          input: { content, format, keyPrefix, sourceFile, dryRun }
+        })).importSourceStrings
+      );
+    }
   );
 }
 
@@ -900,6 +919,21 @@ function resolveLocaleCodes(raw) {
   return out;
 }
 
+// ../../packages/shared/src/constants.ts
+var ORG_PLANS = ["FREE", "PRO", "ENTERPRISE"];
+function isPaidPlan(plan) {
+  switch (plan) {
+    case "PRO":
+    case "ENTERPRISE":
+      return true;
+    case "FREE":
+      return false;
+    default:
+      return false;
+  }
+}
+var PAID_PLANS = ORG_PLANS.filter(isPaidPlan);
+
 // src/tools/locales.ts
 function registerLocaleTools(server, gql) {
   server.registerTool(
@@ -1081,8 +1115,27 @@ function registerProjectTools(server, gql) {
 }
 
 // src/tools/providers.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 import { CONFIGURE_LLM_PROVIDER, LIST_LLM_PROVIDERS } from "@syntholoc/sdk";
+
+// src/generated/input-schemas.ts
+import { z as z9 } from "zod";
+var isDefinedNonNullAny = (v) => v !== void 0 && v !== null;
+var definedNonNullAnySchema = z9.any().refine((v) => isDefinedNonNullAny(v));
+var CoverageCategorySchema = z9.enum(["DYNAMIC", "NOT_CAPTURED", "NOT_IN_CODE", "SCREENSHOT", "SERVER", "TEST", "UNKNOWN"]);
+var QaCriticScopeSchema = z9.enum(["ALL", "UNREVIEWED"]);
+var TranslateScopeSchema = z9.enum(["ALL", "DRAFT", "UNAPPROVED", "UNTRANSLATED"]);
+function ConfigureProviderInputSchema() {
+  return z9.object({
+    apiKey: z9.string(),
+    baseUrl: z9.string().nullish(),
+    defaultModel: z9.string().nullish(),
+    label: z9.string(),
+    type: z9.string()
+  });
+}
+
+// src/tools/providers.ts
 function registerProviderTools(server, gql) {
   server.registerTool(
     "list_llm_providers",
@@ -1099,12 +1152,12 @@ function registerProviderTools(server, gql) {
     {
       title: "Configure LLM provider",
       description: "Adds a BYOK LLM provider (OPENROUTER | OPENAI | ANTHROPIC). The key is stored encrypted at rest.",
+      // Base field shapes (apiKey/label/baseUrl/defaultModel) are generated from
+      // the GraphQL ConfigureProviderInput; we curate `type` from the API's
+      // free-form String down to the concrete provider set.
       inputSchema: {
-        type: z9.enum(["OPENROUTER", "OPENAI", "ANTHROPIC"]),
-        label: z9.string(),
-        apiKey: z9.string(),
-        baseUrl: z9.string().optional(),
-        defaultModel: z9.string().optional()
+        ...ConfigureProviderInputSchema().shape,
+        type: z10.enum(["OPENROUTER", "OPENAI", "ANTHROPIC"])
       },
       annotations: { openWorldHint: true }
     },
@@ -1113,15 +1166,19 @@ function registerProviderTools(server, gql) {
 }
 
 // src/tools/qa.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 import { LIST_QA_ISSUES as LIST_QA_ISSUES2, RUN_LOCALE_QA, RUN_QA } from "@syntholoc/sdk";
 function registerQaTools(server, gql) {
   server.registerTool(
     "run_locale_qa",
     {
       title: "Run locale QA",
-      description: "Queues an LLM QA-critic pass over a locale's non-approved translations. Returns tracking `jobIds`.",
-      inputSchema: { projectId: z10.string(), localeId: z10.string() },
+      description: "Queues an LLM QA-critic pass over a locale's non-approved translations. `scope` UNREVIEWED (default) critiques only translations not yet reviewed at their current text; ALL re-critiques every one. Returns tracking `jobIds`.",
+      inputSchema: {
+        projectId: z11.string(),
+        localeId: z11.string(),
+        scope: z11.enum(["UNREVIEWED", "ALL"]).optional()
+      },
       annotations: { openWorldHint: true }
     },
     async (vars) => jsonResult((await gql.request(RUN_LOCALE_QA, vars)).runLocaleQa)
@@ -1131,7 +1188,7 @@ function registerQaTools(server, gql) {
     {
       title: "Run QA on a translation",
       description: "Runs QA on one translation and returns its score and issues (synchronous).",
-      inputSchema: { projectId: z10.string(), translationId: z10.string() },
+      inputSchema: { projectId: z11.string(), translationId: z11.string() },
       annotations: { openWorldHint: true }
     },
     async (vars) => jsonResult((await gql.request(RUN_QA, vars)).runQa)
@@ -1142,11 +1199,11 @@ function registerQaTools(server, gql) {
       title: "List QA issues",
       description: "Open QA issues for a locale, plus the issue-type facets (filter tabs).",
       inputSchema: {
-        projectId: z10.string(),
-        localeId: z10.string(),
-        type: z10.string().optional(),
-        skip: z10.number().int().min(0).default(0),
-        take: z10.number().int().min(1).max(100).default(25)
+        projectId: z11.string(),
+        localeId: z11.string(),
+        type: z11.string().optional(),
+        skip: z11.number().int().min(0).default(0),
+        take: z11.number().int().min(1).max(100).default(25)
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -1155,7 +1212,7 @@ function registerQaTools(server, gql) {
 }
 
 // src/tools/styleguides.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 import { CREATE_STYLE_GUIDE, GENERATE_STYLE_GUIDE, LIST_STYLE_GUIDES as LIST_STYLE_GUIDES2 } from "@syntholoc/sdk";
 function registerStyleGuideTools(server, gql) {
   server.registerTool(
@@ -1163,7 +1220,7 @@ function registerStyleGuideTools(server, gql) {
     {
       title: "List style guides",
       description: "Lists style guides (project-scoped if projectId given, else org-wide).",
-      inputSchema: { projectId: z11.string().optional() },
+      inputSchema: { projectId: z12.string().optional() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
     async ({ projectId }) => jsonResult((await gql.request(LIST_STYLE_GUIDES2, { projectId })).styleGuides)
@@ -1173,7 +1230,7 @@ function registerStyleGuideTools(server, gql) {
     {
       title: "Generate style guide (draft)",
       description: "Drafts a tone/rules/prompt-fragment style guide from the project (optionally per locale). Returns a draft \u2014 persist it with create_style_guide.",
-      inputSchema: { projectId: z11.string(), localeCode: z11.string().optional() },
+      inputSchema: { projectId: z12.string(), localeCode: z12.string().optional() },
       annotations: { openWorldHint: true }
     },
     async ({ projectId, localeCode }) => jsonResult((await gql.request(GENERATE_STYLE_GUIDE, { input: { projectId, localeCode } })).generateStyleGuide)
@@ -1184,12 +1241,12 @@ function registerStyleGuideTools(server, gql) {
       title: "Create style guide",
       description: "Persists a style guide (tone, rules JSON, prompt fragment), project- or locale-scoped.",
       inputSchema: {
-        name: z11.string(),
-        projectId: z11.string().optional(),
-        localeCode: z11.string().optional(),
-        tone: z11.string().optional(),
-        promptFragment: z11.string().optional(),
-        rules: z11.array(z11.string()).optional()
+        name: z12.string(),
+        projectId: z12.string().optional(),
+        localeCode: z12.string().optional(),
+        tone: z12.string().optional(),
+        promptFragment: z12.string().optional(),
+        rules: z12.array(z12.string()).optional()
       },
       annotations: { openWorldHint: true }
     },
@@ -1198,7 +1255,7 @@ function registerStyleGuideTools(server, gql) {
 }
 
 // src/tools/tm.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 import { TM_ENTRIES, TM_SEARCH, TM_STATS as TM_STATS2 } from "@syntholoc/sdk";
 function registerTmTools(server, gql) {
   server.registerTool(
@@ -1207,10 +1264,10 @@ function registerTmTools(server, gql) {
       title: "Search translation memory",
       description: "Concordance search \u2014 the nearest prior translations for a source string in a target locale, with cosine distance (0 = identical). Scope to a project with `projectId` (includes its group siblings); omit for the whole organization. Requires an embedding-capable provider.",
       inputSchema: {
-        sourceText: z12.string(),
-        targetLocale: z12.string(),
-        projectId: z12.string().optional(),
-        limit: z12.number().int().min(1).max(20).default(5)
+        sourceText: z13.string(),
+        targetLocale: z13.string(),
+        projectId: z13.string().optional(),
+        limit: z13.number().int().min(1).max(20).default(5)
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -1221,7 +1278,7 @@ function registerTmTools(server, gql) {
     {
       title: "Translation memory stats",
       description: "Entry counts per target locale (org-wide, or for a project with `projectId`).",
-      inputSchema: { projectId: z12.string().optional() },
+      inputSchema: { projectId: z13.string().optional() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
     async ({ projectId }) => jsonResult((await gql.request(TM_STATS2, { projectId })).tmStats)
@@ -1232,10 +1289,10 @@ function registerTmTools(server, gql) {
       title: "Browse translation memory",
       description: "Lists stored TM entries (paginated, newest first), optionally filtered by project and locale.",
       inputSchema: {
-        projectId: z12.string().optional(),
-        targetLocale: z12.string().optional(),
-        skip: z12.number().int().min(0).default(0),
-        take: z12.number().int().min(1).max(100).default(25)
+        projectId: z13.string().optional(),
+        targetLocale: z13.string().optional(),
+        skip: z13.number().int().min(0).default(0),
+        take: z13.number().int().min(1).max(100).default(25)
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -1244,9 +1301,10 @@ function registerTmTools(server, gql) {
 }
 
 // src/tools/translations.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 import {
   APPROVE_TRANSLATION,
+  EXPORT_DOCUMENT_LOCALE,
   EXPORT_LOCALE,
   IMPORT_TRANSLATIONS,
   LIST_TRANSLATIONS,
@@ -1255,7 +1313,8 @@ import {
   TRANSLATE_KEY,
   TRANSLATE_LOCALE
 } from "@syntholoc/sdk";
-var FORMATS2 = ["JSON", "YAML", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
+var FORMATS2 = ["JSON", "YAML", "MARKDOWN", "MDX", "CSV", "PO", "XLIFF", "ANDROID_XML", "IOS_STRINGS", "NJK"];
+var DOCUMENT_FORMATS2 = /* @__PURE__ */ new Set(["MARKDOWN", "MDX"]);
 function registerTranslationTools(server, gql) {
   server.registerTool(
     "translate_locale",
@@ -1263,9 +1322,9 @@ function registerTranslationTools(server, gql) {
       title: "Translate locale",
       description: "Queues AI translation of a locale (scope ALL | UNAPPROVED | UNTRANSLATED) and returns the tracking `jobIds`. Executes immediately and unconditionally \u2014 the batch threshold is a client-side policy for PROACTIVE syncs, not for this tool.",
       inputSchema: {
-        projectId: z13.string(),
-        localeId: z13.string(),
-        scope: z13.enum(["ALL", "UNAPPROVED", "UNTRANSLATED"]).default("UNTRANSLATED")
+        projectId: z14.string(),
+        localeId: z14.string(),
+        scope: z14.enum(["ALL", "UNAPPROVED", "UNTRANSLATED"]).default("UNTRANSLATED")
       },
       annotations: { openWorldHint: true }
     },
@@ -1276,7 +1335,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Translate key",
       description: "Queues AI translation of a single key into a locale. Returns tracking `jobIds`.",
-      inputSchema: { projectId: z13.string(), keyId: z13.string(), localeId: z13.string() },
+      inputSchema: { projectId: z14.string(), keyId: z14.string(), localeId: z14.string() },
       annotations: { openWorldHint: true }
     },
     async (vars) => jsonResult((await gql.request(TRANSLATE_KEY, vars)).translateKey)
@@ -1287,11 +1346,11 @@ function registerTranslationTools(server, gql) {
       title: "Set translation",
       description: "Manually sets the translation text for a key in a locale.",
       inputSchema: {
-        projectId: z13.string(),
-        keyId: z13.string(),
-        localeId: z13.string(),
-        text: z13.string(),
-        origin: z13.string().optional()
+        projectId: z14.string(),
+        keyId: z14.string(),
+        localeId: z14.string(),
+        text: z14.string(),
+        origin: z14.string().optional()
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
@@ -1305,10 +1364,10 @@ function registerTranslationTools(server, gql) {
       title: "List translations",
       description: "Lists translations for a locale with status, origin, model and QA score.",
       inputSchema: {
-        projectId: z13.string(),
-        localeId: z13.string(),
-        skip: z13.number().int().min(0).default(0),
-        take: z13.number().int().min(1).max(200).default(25)
+        projectId: z14.string(),
+        localeId: z14.string(),
+        skip: z14.number().int().min(0).default(0),
+        take: z14.number().int().min(1).max(200).default(25)
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -1319,7 +1378,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Approve translation",
       description: "Marks a translation APPROVED.",
-      inputSchema: { projectId: z13.string(), translationId: z13.string() },
+      inputSchema: { projectId: z14.string(), translationId: z14.string() },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
     async ({ projectId, translationId }) => jsonResult((await gql.request(APPROVE_TRANSLATION, { projectId, id: translationId })).approveTranslation)
@@ -1329,7 +1388,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Reject translation",
       description: "Marks a translation REJECTED (queued for re-translation).",
-      inputSchema: { projectId: z13.string(), translationId: z13.string() },
+      inputSchema: { projectId: z14.string(), translationId: z14.string() },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
     async ({ projectId, translationId }) => jsonResult((await gql.request(REJECT_TRANSLATION, { projectId, id: translationId })).rejectTranslation)
@@ -1338,43 +1397,72 @@ 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. 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.',
+      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. For MARKDOWN and MDX use `export_document` instead: a document is spliced into its original file, which the server reads from the connected repository.',
       inputSchema: {
-        projectId: z13.string(),
-        localeId: z13.string(),
-        format: z13.enum(FORMATS2).default("JSON"),
-        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".')
+        projectId: z14.string(),
+        localeId: z14.string(),
+        format: z14.enum(FORMATS2).default("JSON"),
+        onlyApproved: z14.boolean().optional(),
+        sourceFile: z14.string().optional().describe('Real source file path to export, e.g. "messages/en/home.json" (reliable, preferred).'),
+        keyPrefix: z14.string().optional().describe('Legacy namespace prefix, e.g. "home".')
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
     async (vars) => jsonResult({ content: (await gql.request(EXPORT_LOCALE, vars)).exportLocale })
   );
+  server.registerTool(
+    "export_document",
+    {
+      title: "Export document locale",
+      description: "Exports one locale of a Markdown or MDX source document. Unlike `export_locale` this returns the whole translated document: the server reads the original file from the connected repository and splices the translations into it, so headings, list markers, code fences and indentation are preserved byte for byte. Segments with no translation keep their source text.",
+      inputSchema: {
+        projectId: z14.string(),
+        localeId: z14.string(),
+        sourceFile: z14.string().describe('Path of the source document in the repository, e.g. "docs/guide.md".'),
+        repositoryId: z14.string().optional().describe("Only needed when the project has several repositories and the path is ambiguous."),
+        onlyApproved: z14.boolean().optional()
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (vars) => {
+      if (!vars.sourceFile.trim()) {
+        return errorResult("export_document needs a sourceFile \u2014 the path of the document in the repository.");
+      }
+      return jsonResult({ content: (await gql.request(EXPORT_DOCUMENT_LOCALE, vars)).exportDocumentLocale });
+    }
+  );
   server.registerTool(
     "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. For a multi-file / namespaced project pass `keyPrefix` (the namespace) to match prefixed source keys.",
+      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. For MARKDOWN and MDX `sourceFile` is REQUIRED: a translated document has translated headings, so it is matched to the source by segment position and the two must have the same structure.",
       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)
+        projectId: z14.string(),
+        localeId: z14.string(),
+        content: z14.string(),
+        format: z14.enum(FORMATS2),
+        keyPrefix: z14.string().optional().describe('Namespace prefix, e.g. "home" (per-file, multi-file projects).'),
+        sourceFile: z14.string().optional().describe('Source file these translations belong to; REQUIRED for MARKDOWN/MDX, e.g. "docs/guide.md".'),
+        autoApprove: z14.boolean().default(false),
+        conflict: z14.enum(["OVERWRITE", "SKIP_EXISTING", "KEEP_APPROVED"]).default("OVERWRITE"),
+        dryRun: z14.boolean().default(false)
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
-    async ({ projectId, localeId, content, format, keyPrefix, autoApprove, conflict, dryRun }) => jsonResult(
-      (await gql.request(IMPORT_TRANSLATIONS, {
-        projectId,
-        localeId,
-        input: { content, format, keyPrefix, autoApprove, conflict, dryRun }
-      })).importTranslations
-    )
+    async ({ projectId, localeId, content, format, keyPrefix, sourceFile, autoApprove, conflict, dryRun }) => {
+      if (DOCUMENT_FORMATS2.has(format) && !sourceFile?.trim()) {
+        return errorResult(
+          `${format} needs a sourceFile \u2014 a translated document is aligned to its source by position.`
+        );
+      }
+      return jsonResult(
+        (await gql.request(IMPORT_TRANSLATIONS, {
+          projectId,
+          localeId,
+          input: { content, format, keyPrefix, sourceFile, autoApprove, conflict, dryRun }
+        })).importTranslations
+      );
+    }
   );
 }
 
@@ -1407,7 +1495,7 @@ function registerAllTools(server, gql, opts = {}) {
 }
 
 // package.json
-var version = "0.3.1";
+var version = "0.5.0";
 
 // src/build-server.ts
 function buildMcpServer(gql, opts = {}) {

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   buildMcpServer,
   parseList
-} from "./chunk-MUY33R6O.js";
+} from "./chunk-V5AAF2RJ.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.1",
+  "version": "0.5.0",
   "description": "Syntholoc MCP server — manage AI localization and translation from Codex, Claude Code, and other MCP clients.",
   "homepage": "https://syntholoc.com",
   "keywords": [
@@ -47,14 +47,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.22.0",
-    "@syntholoc/sdk": "0.3.0",
+    "@syntholoc/sdk": "0.3.1",
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "@graphql-codegen/cli": "7.1.2",
+    "@graphql-codegen/typescript": "5.0.2",
     "@syntholoc/shared": "0.1.0",
     "@types/bun": "1.3.14",
     "@types/node": "22.19.21",
     "graphql": "16.14.2",
+    "graphql-codegen-typescript-validation-schema": "0.19.0",
     "tsup": "8.5.1",
     "typescript": "6.0.3"
   }