@syntholoc/mcp 0.1.1 → 0.2.0

package/README.md

@@ -22,6 +22,34 @@ never passed as a tool argument.
 |---|---|---|
 | `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
+> endpoint is versioned at `/mcp/v1` (the legacy `/mcp` path still works).
+
+### Choosing an organization (hosted / OAuth)
+
+An OAuth token is per-user and may belong to several organizations. By default the
+earliest one is used. To pin a specific org, send the `syntholoc-org-id` header
+(verified against your membership). List the ids with the `list_organizations` tool
+or the `syntholoc://organizations` resource, then add it to your client config, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "syntholoc": {
+      "type": "http",
+      "url": "https://api.syntholoc.com/mcp/v1",
+      "headers": { "syntholoc-org-id": "<org-id>" }
+    }
+  }
+}
+```
+
+API-key (stdio) clients don't need this — the key is already scoped to one org.
 
 ## What you can do
 

package/dist/build-server.d.ts

@@ -1,11 +1,33 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { GraphQLClient } from '@syntholoc/sdk';
 
+/**
+ * Server-side tool-filtering options, mirroring Crowdin's `crowdin-tool-sets` /
+ * `crowdin-read-only` / `crowdin-tool-filter` headers. Applied before the tool
+ * list is returned so the agent only sees a focused surface.
+ */
+interface ToolFilterOptions {
+    /** Tool-set names to load (see TOOL_SET_NAMES). Empty / undefined / ['all'] loads everything. */
+    toolSets?: string[];
+    /** When true, only read-only tools (annotations.readOnlyHint) are exposed. */
+    readOnly?: boolean;
+    /** Wildcard patterns matched against tool names (e.g. "list_*", "project*"). */
+    toolFilter?: string[];
+}
+/** Parses a comma-separated header/env value into a trimmed, non-empty string list. */
+declare function parseList(value: string | undefined | null): string[] | undefined;
+
+/** The valid tool-set names clients may request. */
+declare const TOOL_SET_NAMES: string[];
+
 /**
  * Builds a fully-configured Syntholoc MCP server (tools + resources + prompts)
  * bound to the given GraphQL client. Shared by the stdio entrypoint and the
  * NestJS remote `/mcp` (Streamable HTTP) endpoint.
+ *
+ * `opts` optionally narrows the exposed tool surface (tool sets, read-only mode,
+ * name-pattern filter) so the agent sees only what a given client needs.
  */
-declare function buildMcpServer(gql: GraphQLClient): McpServer;
+declare function buildMcpServer(gql: GraphQLClient, opts?: ToolFilterOptions): McpServer;
 
-export { buildMcpServer };
+export { TOOL_SET_NAMES, type ToolFilterOptions, buildMcpServer, parseList };

package/dist/build-server.js

@@ -1,6 +1,10 @@
 import {
-  buildMcpServer
-} from "./chunk-RJ5GG3TT.js";
+  TOOL_SET_NAMES,
+  buildMcpServer,
+  parseList
+} from "./chunk-DZKWHV2O.js";
 export {
-  buildMcpServer
+  TOOL_SET_NAMES,
+  buildMcpServer,
+  parseList
 };

package/dist/{chunk-RJ5GG3TT.js → chunk-DZKWHV2O.js}

@@ -1,6 +1,35 @@
 // src/build-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// src/filter.ts
+function wildcardToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function matchesAnyPattern(name, patterns) {
+  return patterns.some((re) => re.test(name));
+}
+function applyToolFilter(server, opts) {
+  const patterns = (opts.toolFilter ?? []).filter(Boolean).map(wildcardToRegExp);
+  if (!opts.readOnly && patterns.length === 0) return server;
+  const original = server.registerTool.bind(server);
+  const filtered = (name, config, handler) => {
+    const readOnly = config.annotations?.readOnlyHint;
+    if (opts.readOnly && !readOnly) return void 0;
+    if (patterns.length > 0 && !matchesAnyPattern(name, patterns)) {
+      return void 0;
+    }
+    return original(name, config, handler);
+  };
+  server.registerTool = filtered;
+  return server;
+}
+function parseList(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+
 // src/prompts.ts
 import { z } from "zod";
 function userMessage(text) {
@@ -20,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")
     )
@@ -55,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")
     )
@@ -67,7 +112,20 @@ function registerPrompts(server) {
 
 // src/resources.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CONFIG_RESOURCE, PROJECTS_RESOURCE, PROJECT_RESOURCE } from "@syntholoc/sdk";
+import {
+  CONFIG_RESOURCE,
+  LIST_GLOSSARY,
+  LIST_JOBS,
+  LIST_KEYS,
+  LIST_LOCALES,
+  LIST_QA_ISSUES,
+  LIST_STYLE_GUIDES,
+  MY_ORGANIZATIONS,
+  PROJECT_ANALYTICS,
+  TM_STATS,
+  PROJECT_RESOURCE,
+  PROJECTS_RESOURCE
+} from "@syntholoc/sdk";
 function json(uri, data) {
   return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
 }
@@ -82,6 +140,16 @@ function registerResources(server, gql) {
     },
     async (uri) => json(uri, (await gql.request(CONFIG_RESOURCE)).appInfo)
   );
+  server.registerResource(
+    "organizations",
+    "syntholoc://organizations",
+    {
+      title: "Organizations",
+      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 })))
+  );
   server.registerResource(
     "projects",
     "syntholoc://projects",
@@ -102,11 +170,99 @@ function registerResources(server, gql) {
     },
     async (uri, { projectId }) => json(uri, await gql.request(PROJECT_RESOURCE, { id: String(projectId) }))
   );
+  server.registerResource(
+    "project-keys",
+    new ResourceTemplate("syntholoc://project/{projectId}/keys", { list: void 0 }),
+    {
+      title: "Project source keys",
+      description: "Source keys in a project (first 100).",
+      mimeType: "application/json"
+    },
+    async (uri, { projectId }) => json(uri, (await gql.request(LIST_KEYS, { projectId: String(projectId), skip: 0, take: 100 })).keys)
+  );
+  server.registerResource(
+    "project-locales",
+    new ResourceTemplate("syntholoc://project/{projectId}/locales", { list: void 0 }),
+    {
+      title: "Project locales",
+      description: "Target locales configured for a project.",
+      mimeType: "application/json"
+    },
+    async (uri, { projectId }) => json(uri, (await gql.request(LIST_LOCALES, { projectId: String(projectId) })).locales)
+  );
+  server.registerResource(
+    "project-progress",
+    new ResourceTemplate("syntholoc://project/{projectId}/progress", { list: void 0 }),
+    {
+      title: "Project progress",
+      description: "Per-locale translation progress and open QA issues for a project.",
+      mimeType: "application/json"
+    },
+    async (uri, { projectId }) => json(uri, (await gql.request(PROJECT_ANALYTICS, { projectId: String(projectId) })).projectAnalytics)
+  );
+  server.registerResource(
+    "project-jobs",
+    new ResourceTemplate("syntholoc://project/{projectId}/jobs", { list: void 0 }),
+    {
+      title: "Project jobs",
+      description: "Recent background jobs (translate / QA / git sync) for a project.",
+      mimeType: "application/json"
+    },
+    async (uri, { projectId }) => json(uri, (await gql.request(LIST_JOBS, { projectId: String(projectId), skip: 0, take: 25 })).jobs)
+  );
+  server.registerResource(
+    "project-qa-issues",
+    new ResourceTemplate("syntholoc://project/{projectId}/locale/{localeId}/qa-issues", { list: void 0 }),
+    {
+      title: "Locale QA issues",
+      description: "Open QA issues for a locale, with issue-type facets.",
+      mimeType: "application/json"
+    },
+    async (uri, { projectId, localeId }) => json(
+      uri,
+      await gql.request(LIST_QA_ISSUES, {
+        projectId: String(projectId),
+        localeId: String(localeId),
+        skip: 0,
+        take: 25
+      })
+    )
+  );
+  server.registerResource(
+    "glossary",
+    "syntholoc://glossary",
+    {
+      title: "Glossary",
+      description: "Organization-wide glossary terms (first 100).",
+      mimeType: "application/json"
+    },
+    async (uri) => json(uri, (await gql.request(LIST_GLOSSARY, { skip: 0, take: 100 })).glossaryTerms)
+  );
+  server.registerResource(
+    "style-guides",
+    "syntholoc://style-guides",
+    {
+      title: "Style guides",
+      description: "Organization-wide style guides.",
+      mimeType: "application/json"
+    },
+    async (uri) => json(uri, (await gql.request(LIST_STYLE_GUIDES, {})).styleGuides)
+  );
+  server.registerResource(
+    "tm",
+    "syntholoc://tm",
+    {
+      title: "Translation memory",
+      description: "Organization-wide Translation Memory coverage: entry counts per target locale.",
+      mimeType: "application/json"
+    },
+    async (uri) => json(uri, (await gql.request(TM_STATS, {})).tmStats)
+  );
 }
 
 // src/tools/analytics.ts
 import { z as z2 } from "zod";
-import { COST_ANALYTICS, LOCALE_PROGRESS, PROJECT_ANALYTICS, USAGE } from "@syntholoc/sdk";
+import { COST_ANALYTICS, LOCALE_PROGRESS, PROJECT_ANALYTICS as PROJECT_ANALYTICS2, USAGE } from "@syntholoc/sdk";
 
 // src/util.ts
 function jsonResult(data) {
@@ -123,7 +279,7 @@ function registerAnalyticsTools(server, gql) {
       inputSchema: { projectId: z2.string() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async ({ projectId }) => jsonResult((await gql.request(PROJECT_ANALYTICS, { projectId })).projectAnalytics)
+    async ({ projectId }) => jsonResult((await gql.request(PROJECT_ANALYTICS2, { projectId })).projectAnalytics)
   );
   server.registerTool(
     "cost_analytics",
@@ -238,7 +394,7 @@ import { z as z4 } from "zod";
 import {
   CREATE_GLOSSARY_TERM,
   DELETE_GLOSSARY_TERM,
-  LIST_GLOSSARY,
+  LIST_GLOSSARY as LIST_GLOSSARY2,
   SUGGEST_GLOSSARY_TERMS,
   UPDATE_GLOSSARY_TERM
 } from "@syntholoc/sdk";
@@ -255,7 +411,7 @@ function registerGlossaryTools(server, gql) {
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async (vars) => jsonResult((await gql.request(LIST_GLOSSARY, vars)).glossaryTerms)
+    async (vars) => jsonResult((await gql.request(LIST_GLOSSARY2, vars)).glossaryTerms)
   );
   server.registerTool(
     "upsert_glossary_term",
@@ -310,7 +466,7 @@ function registerGlossaryTools(server, gql) {
 
 // src/tools/jobs.ts
 import { z as z5 } from "zod";
-import { GET_JOB, LIST_JOBS, waitForJob } from "@syntholoc/sdk";
+import { GET_JOB, LIST_JOBS as LIST_JOBS2, waitForJob } from "@syntholoc/sdk";
 function registerJobTools(server, gql) {
   server.registerTool(
     "get_job",
@@ -334,7 +490,7 @@ function registerJobTools(server, gql) {
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async (vars) => jsonResult((await gql.request(LIST_JOBS, vars)).jobs)
+    async (vars) => jsonResult((await gql.request(LIST_JOBS2, vars)).jobs)
   );
   server.registerTool(
     "wait_for_job",
@@ -361,7 +517,7 @@ import { z as z6 } from "zod";
 import {
   DELETE_KEY,
   IMPORT_SOURCE_STRINGS,
-  LIST_KEYS,
+  LIST_KEYS as LIST_KEYS2,
   UPDATE_KEY,
   UPSERT_KEYS
 } from "@syntholoc/sdk";
@@ -382,7 +538,7 @@ function registerKeyTools(server, gql) {
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async (vars) => jsonResult((await gql.request(LIST_KEYS, vars)).keys)
+    async (vars) => jsonResult((await gql.request(LIST_KEYS2, vars)).keys)
   );
   server.registerTool(
     "upsert_keys",
@@ -435,24 +591,29 @@ 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
     )
   );
 }
 
 // src/tools/locales.ts
 import { z as z7 } from "zod";
-import { ADD_LOCALE, LIST_LOCALES, REMOVE_LOCALE, SEED_STARTER_LOCALES } from "@syntholoc/sdk";
+import { ADD_LOCALE, LIST_LOCALES as LIST_LOCALES2, REMOVE_LOCALE, SEED_STARTER_LOCALES } from "@syntholoc/sdk";
 function registerLocaleTools(server, gql) {
   server.registerTool(
     "list_locales",
@@ -462,16 +623,19 @@ function registerLocaleTools(server, gql) {
       inputSchema: { projectId: z7.string() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async ({ projectId }) => jsonResult((await gql.request(LIST_LOCALES, { projectId })).locales)
+    async ({ projectId }) => jsonResult((await gql.request(LIST_LOCALES2, { projectId })).locales)
   );
   server.registerTool(
     "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(),
@@ -479,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)
@@ -505,8 +681,29 @@ function registerLocaleTools(server, gql) {
 
 // src/tools/projects.ts
 import { z as z8 } from "zod";
-import { CREATE_PROJECT, GET_PROJECT, LIST_PROJECTS, UPDATE_PROJECT } from "@syntholoc/sdk";
+import {
+  CREATE_PROJECT,
+  GET_PROJECT,
+  LIST_PROJECTS,
+  MY_ORGANIZATIONS as MY_ORGANIZATIONS2,
+  UPDATE_PROJECT
+} from "@syntholoc/sdk";
 function registerProjectTools(server, gql) {
+  server.registerTool(
+    "list_organizations",
+    {
+      title: "List organizations",
+      description: "Organizations you belong to (id, name, slug, your role). To act in a specific org, set the `syntholoc-org-id` request header (hosted transport); otherwise the earliest org is used.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async () => jsonResult(
+      (await gql.request(MY_ORGANIZATIONS2)).myProjects.map((g) => ({
+        ...g.organization,
+        viewerRole: g.viewerRole
+      }))
+    )
+  );
   server.registerTool(
     "list_projects",
     {
@@ -604,7 +801,7 @@ function registerProviderTools(server, gql) {
 
 // src/tools/qa.ts
 import { z as z10 } from "zod";
-import { LIST_QA_ISSUES, RUN_LOCALE_QA, RUN_QA } from "@syntholoc/sdk";
+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",
@@ -640,13 +837,13 @@ function registerQaTools(server, gql) {
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async (vars) => jsonResult(await gql.request(LIST_QA_ISSUES, vars))
+    async (vars) => jsonResult(await gql.request(LIST_QA_ISSUES2, vars))
   );
 }
 
 // src/tools/styleguides.ts
 import { z as z11 } from "zod";
-import { CREATE_STYLE_GUIDE, GENERATE_STYLE_GUIDE, LIST_STYLE_GUIDES } from "@syntholoc/sdk";
+import { CREATE_STYLE_GUIDE, GENERATE_STYLE_GUIDE, LIST_STYLE_GUIDES as LIST_STYLE_GUIDES2 } from "@syntholoc/sdk";
 function registerStyleGuideTools(server, gql) {
   server.registerTool(
     "list_style_guides",
@@ -656,7 +853,7 @@ function registerStyleGuideTools(server, gql) {
       inputSchema: { projectId: z11.string().optional() },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    async ({ projectId }) => jsonResult((await gql.request(LIST_STYLE_GUIDES, { projectId })).styleGuides)
+    async ({ projectId }) => jsonResult((await gql.request(LIST_STYLE_GUIDES2, { projectId })).styleGuides)
   );
   server.registerTool(
     "generate_style_guide",
@@ -687,8 +884,54 @@ function registerStyleGuideTools(server, gql) {
   );
 }
 
-// src/tools/translations.ts
+// src/tools/tm.ts
 import { z as z12 } from "zod";
+import { TM_ENTRIES, TM_SEARCH, TM_STATS as TM_STATS2 } from "@syntholoc/sdk";
+function registerTmTools(server, gql) {
+  server.registerTool(
+    "tm_search",
+    {
+      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)
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async ({ sourceText, targetLocale, projectId, limit }) => jsonResult((await gql.request(TM_SEARCH, { sourceText, targetLocale, projectId, limit })).tmSearch)
+  );
+  server.registerTool(
+    "tm_stats",
+    {
+      title: "Translation memory stats",
+      description: "Entry counts per target locale (org-wide, or for a project with `projectId`).",
+      inputSchema: { projectId: z12.string().optional() },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async ({ projectId }) => jsonResult((await gql.request(TM_STATS2, { projectId })).tmStats)
+  );
+  server.registerTool(
+    "list_tm",
+    {
+      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)
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (vars) => jsonResult((await gql.request(TM_ENTRIES, vars)).tmEntries)
+  );
+}
+
+// src/tools/translations.ts
+import { z as z13 } from "zod";
 import {
   APPROVE_TRANSLATION,
   EXPORT_LOCALE,
@@ -707,9 +950,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: z12.string(),
-        localeId: z12.string(),
-        scope: z12.enum(["ALL", "UNAPPROVED", "UNTRANSLATED"]).default("UNTRANSLATED")
+        projectId: z13.string(),
+        localeId: z13.string(),
+        scope: z13.enum(["ALL", "UNAPPROVED", "UNTRANSLATED"]).default("UNTRANSLATED")
       },
       annotations: { openWorldHint: true }
     },
@@ -720,7 +963,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Translate key",
       description: "Queues AI translation of a single key into a locale. Returns tracking `jobIds`.",
-      inputSchema: { projectId: z12.string(), keyId: z12.string(), localeId: z12.string() },
+      inputSchema: { projectId: z13.string(), keyId: z13.string(), localeId: z13.string() },
       annotations: { openWorldHint: true }
     },
     async (vars) => jsonResult((await gql.request(TRANSLATE_KEY, vars)).translateKey)
@@ -731,11 +974,11 @@ function registerTranslationTools(server, gql) {
       title: "Set translation",
       description: "Manually sets the translation text for a key in a locale.",
       inputSchema: {
-        projectId: z12.string(),
-        keyId: z12.string(),
-        localeId: z12.string(),
-        text: z12.string(),
-        origin: z12.string().optional()
+        projectId: z13.string(),
+        keyId: z13.string(),
+        localeId: z13.string(),
+        text: z13.string(),
+        origin: z13.string().optional()
       },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
@@ -749,10 +992,10 @@ function registerTranslationTools(server, gql) {
       title: "List translations",
       description: "Lists translations for a locale with status, origin, model and QA score.",
       inputSchema: {
-        projectId: z12.string(),
-        localeId: z12.string(),
-        skip: z12.number().int().min(0).default(0),
-        take: z12.number().int().min(1).max(200).default(25)
+        projectId: z13.string(),
+        localeId: z13.string(),
+        skip: z13.number().int().min(0).default(0),
+        take: z13.number().int().min(1).max(200).default(25)
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -763,7 +1006,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Approve translation",
       description: "Marks a translation APPROVED.",
-      inputSchema: { projectId: z12.string(), translationId: z12.string() },
+      inputSchema: { projectId: z13.string(), translationId: z13.string() },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
     async ({ projectId, translationId }) => jsonResult((await gql.request(APPROVE_TRANSLATION, { projectId, id: translationId })).approveTranslation)
@@ -773,7 +1016,7 @@ function registerTranslationTools(server, gql) {
     {
       title: "Reject translation",
       description: "Marks a translation REJECTED (queued for re-translation).",
-      inputSchema: { projectId: z12.string(), translationId: z12.string() },
+      inputSchema: { projectId: z13.string(), translationId: z13.string() },
       annotations: { idempotentHint: true, openWorldHint: true }
     },
     async ({ projectId, translationId }) => jsonResult((await gql.request(REJECT_TRANSLATION, { projectId, id: translationId })).rejectTranslation)
@@ -782,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: z12.string(),
-        localeId: z12.string(),
-        format: z12.enum(FORMATS2).default("JSON"),
-        onlyApproved: z12.boolean().optional()
+        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".')
       },
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
@@ -797,53 +1042,68 @@ 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: z12.string(),
-        localeId: z12.string(),
-        content: z12.string(),
-        format: z12.enum(FORMATS2),
-        autoApprove: z12.boolean().default(false),
-        conflict: z12.enum(["OVERWRITE", "SKIP_EXISTING", "KEEP_APPROVED"]).default("OVERWRITE"),
-        dryRun: z12.boolean().default(false)
+        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
     )
   );
 }
 
 // src/tools/index.ts
-function registerAllTools(server, gql) {
-  registerConfigTools(server, gql);
-  registerProjectTools(server, gql);
-  registerLocaleTools(server, gql);
-  registerKeyTools(server, gql);
-  registerTranslationTools(server, gql);
-  registerQaTools(server, gql);
-  registerGlossaryTools(server, gql);
-  registerStyleGuideTools(server, gql);
-  registerGitTools(server, gql);
-  registerProviderTools(server, gql);
-  registerJobTools(server, gql);
-  registerAnalyticsTools(server, gql);
+var TOOL_SETS = {
+  config: registerConfigTools,
+  projects: registerProjectTools,
+  locales: registerLocaleTools,
+  keys: registerKeyTools,
+  translations: registerTranslationTools,
+  qa: registerQaTools,
+  glossary: registerGlossaryTools,
+  styleguides: registerStyleGuideTools,
+  tm: registerTmTools,
+  git: registerGitTools,
+  providers: registerProviderTools,
+  jobs: registerJobTools,
+  analytics: registerAnalyticsTools
+};
+var TOOL_SET_NAMES = Object.keys(TOOL_SETS);
+function selectSets(requested) {
+  if (!requested || requested.length === 0 || requested.includes("all")) return TOOL_SET_NAMES;
+  return TOOL_SET_NAMES.filter((name) => requested.includes(name));
+}
+function registerAllTools(server, gql, opts = {}) {
+  const target = applyToolFilter(server, opts);
+  for (const name of selectSets(opts.toolSets)) {
+    TOOL_SETS[name]?.(target, gql);
+  }
 }
 
 // src/build-server.ts
-function buildMcpServer(gql) {
+function buildMcpServer(gql, opts = {}) {
   const server = new McpServer({ name: "syntholoc", version: "0.1.0" });
-  registerAllTools(server, gql);
+  registerAllTools(server, gql, opts);
   registerResources(server, gql);
   registerPrompts(server);
   return server;
 }
 
 export {
+  parseList,
+  TOOL_SET_NAMES,
   buildMcpServer
 };

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
-  buildMcpServer
-} from "./chunk-RJ5GG3TT.js";
+  buildMcpServer,
+  parseList
+} from "./chunk-DZKWHV2O.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -14,12 +15,19 @@ function loadConfig(env = process.env) {
     apiKey: env.SYNTHOLOC_API_KEY
   };
 }
+function loadToolOptions(env = process.env) {
+  return {
+    toolSets: parseList(env.SYNTHOLOC_TOOL_SETS),
+    readOnly: env.SYNTHOLOC_READ_ONLY === "true",
+    toolFilter: parseList(env.SYNTHOLOC_TOOL_FILTER)
+  };
+}
 
 // src/index.ts
 async function main() {
   const config = loadConfig();
   const gql = new GraphQLClient(config);
-  const server = buildMcpServer(gql);
+  const server = buildMcpServer(gql, loadToolOptions());
   await server.connect(new StdioServerTransport());
   console.error(`[syntholoc-mcp] ready (api: ${config.apiUrl}${config.apiKey ? "" : ", no API key set"})`);
 }

package/package.json

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