@syntholoc/mcp 0.3.1 → 0.4.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-P7LZNIW2.js";
 export {
   TOOL_SET_NAMES,
   buildMcpServer,

package/dist/{chunk-MUY33R6O.js → chunk-P7LZNIW2.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).",
@@ -440,8 +446,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 +517,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(),
@@ -900,6 +910,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 +1106,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 +1143,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 +1157,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 +1179,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 +1190,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 +1203,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 +1211,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 +1221,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 +1232,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 +1246,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 +1255,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 +1269,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 +1280,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,7 +1292,7 @@ function registerTmTools(server, gql) {
 }
 
 // src/tools/translations.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 import {
   APPROVE_TRANSLATION,
   EXPORT_LOCALE,
@@ -1263,9 +1311,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 +1324,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 +1335,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 +1353,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 +1367,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 +1377,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)
@@ -1340,12 +1388,12 @@ function registerTranslationTools(server, gql) {
       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.',
       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 }
     },
@@ -1357,14 +1405,14 @@ function registerTranslationTools(server, gql) {
       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.",
       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).'),
+        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 }
     },
@@ -1407,7 +1455,7 @@ function registerAllTools(server, gql, opts = {}) {
 }
 
 // package.json
-var version = "0.3.1";
+var version = "0.4.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-P7LZNIW2.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.4.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"
   }