@syntholoc/mcp 0.1.0 → 0.1.1

package/src/tools/glossary.ts

@@ -1,84 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import {
-  CREATE_GLOSSARY_TERM,
-  DELETE_GLOSSARY_TERM,
-  LIST_GLOSSARY,
-  SUGGEST_GLOSSARY_TERMS,
-  UPDATE_GLOSSARY_TERM,
-  type GraphQLClient,
-} from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerGlossaryTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_glossary',
-    {
-      title: 'List glossary terms',
-      description: 'Lists glossary terms (project-scoped if projectId given, else org-wide).',
-      inputSchema: {
-        projectId: z.string().optional(),
-        skip: z.number().int().min(0).default(0),
-        take: z.number().int().min(1).max(100).default(25),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async (vars) => jsonResult((await gql.request(LIST_GLOSSARY, vars)).glossaryTerms),
-  );
-
-  server.registerTool(
-    'upsert_glossary_term',
-    {
-      title: 'Create or update glossary term',
-      description:
-        'Creates a glossary term, or updates it when `termId` is given. `translations` is a ' +
-        'per-locale map, e.g. {"de-DE":"…"}. `forbidden` lists disallowed renderings.',
-      inputSchema: {
-        termId: z.string().optional().describe('Provide to update an existing term'),
-        projectId: z.string().optional().describe('Project scope; omit for org-wide (create only)'),
-        term: z.string().optional(),
-        description: z.string().optional(),
-        partOfSpeech: z.string().optional(),
-        doNotTranslate: z.boolean().optional(),
-        forbidden: z.array(z.string()).optional(),
-        translations: z.record(z.string(), z.string()).optional(),
-      },
-      annotations: { idempotentHint: true, openWorldHint: true },
-    },
-    async ({ termId, projectId, ...rest }) => {
-      if (termId) {
-        const data = await gql.request(UPDATE_GLOSSARY_TERM, { id: termId, input: rest });
-        return jsonResult(data.updateGlossaryTerm);
-      }
-      if (!rest.term) throw new Error('`term` is required when creating a glossary term');
-      const data = await gql.request(CREATE_GLOSSARY_TERM, {
-        input: { term: rest.term, ...rest, projectId },
-      });
-      return jsonResult(data.createGlossaryTerm);
-    },
-  );
-
-  server.registerTool(
-    'delete_glossary_term',
-    {
-      title: 'Delete glossary term',
-      description: 'Deletes a glossary term. Destructive — confirm first.',
-      inputSchema: { termId: z.string() },
-      annotations: { destructiveHint: true, openWorldHint: true },
-    },
-    async ({ termId }) =>
-      jsonResult((await gql.request(DELETE_GLOSSARY_TERM, { id: termId })).deleteGlossaryTerm),
-  );
-
-  server.registerTool(
-    'suggest_glossary_terms',
-    {
-      title: 'Suggest glossary terms',
-      description: 'AI-suggested glossary terms extracted from the project source strings.',
-      inputSchema: { projectId: z.string() },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ projectId }) =>
-      jsonResult((await gql.request(SUGGEST_GLOSSARY_TERMS, { projectId })).suggestGlossaryTerms),
-  );
-}

package/src/tools/index.ts

@@ -1,30 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { GraphQLClient } from '@syntholoc/sdk';
-import { registerAnalyticsTools } from './analytics';
-import { registerConfigTools } from './config';
-import { registerGitTools } from './git';
-import { registerGlossaryTools } from './glossary';
-import { registerJobTools } from './jobs';
-import { registerKeyTools } from './keys';
-import { registerLocaleTools } from './locales';
-import { registerProjectTools } from './projects';
-import { registerProviderTools } from './providers';
-import { registerQaTools } from './qa';
-import { registerStyleGuideTools } from './styleguides';
-import { registerTranslationTools } from './translations';
-
-/** Registers the full Syntholoc tool surface on the given MCP server. */
-export function registerAllTools(server: McpServer, gql: GraphQLClient): void {
-  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);
-}

package/src/tools/jobs.ts

@@ -1,53 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { GET_JOB, LIST_JOBS, waitForJob, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerJobTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'get_job',
-    {
-      title: 'Get job',
-      description: 'Status, progress, token usage and cost of a background job by id.',
-      inputSchema: { jobId: z.string(), projectId: z.string() },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ jobId, projectId }) => jsonResult((await gql.request(GET_JOB, { id: jobId, projectId })).job),
-  );
-
-  server.registerTool(
-    'list_jobs',
-    {
-      title: 'List jobs',
-      description: 'Recent background jobs for a project (translate / QA / git sync).',
-      inputSchema: {
-        projectId: z.string(),
-        skip: z.number().int().min(0).default(0),
-        take: z.number().int().min(1).max(100).default(25),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async (vars) => jsonResult((await gql.request(LIST_JOBS, vars)).jobs),
-  );
-
-  server.registerTool(
-    'wait_for_job',
-    {
-      title: 'Wait for job',
-      description:
-        'Polls a job until it reaches a terminal state (COMPLETED/FAILED/CANCELLED) or the timeout ' +
-        'elapses, then returns its final detail. Use after translate/QA to follow a run.',
-      inputSchema: {
-        jobId: z.string(),
-        projectId: z.string(),
-        timeoutSec: z.number().int().min(1).max(900).default(180),
-        pollIntervalSec: z.number().int().min(1).max(30).default(2),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ jobId, projectId, timeoutSec, pollIntervalSec }) => {
-      const { job, timedOut } = await waitForJob(gql, projectId, jobId, { timeoutSec, pollIntervalSec });
-      return jsonResult({ ...job, timedOut });
-    },
-  );
-}

package/src/tools/keys.ts

@@ -1,114 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import {
-  DELETE_KEY,
-  IMPORT_SOURCE_STRINGS,
-  LIST_KEYS,
-  UPDATE_KEY,
-  UPSERT_KEYS,
-  type GraphQLClient,
-} from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-const FORMATS = ['JSON', 'YAML', 'CSV', 'PO', 'XLIFF', 'ANDROID_XML', 'IOS_STRINGS'] as const;
-
-export function registerKeyTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_keys',
-    {
-      title: 'List keys',
-      description:
-        'Lists source keys. With `localeId` + `status` (untranslated | flagged | approved) the ' +
-        'result `totalCount` is the pending count for that status — use it for the batch threshold.',
-      inputSchema: {
-        projectId: z.string(),
-        localeId: z.string().optional(),
-        status: z.enum(['untranslated', 'flagged', 'approved']).optional(),
-        search: z.string().optional(),
-        skip: z.number().int().min(0).default(0),
-        take: z.number().int().min(1).max(200).default(25),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async (vars) => jsonResult((await gql.request(LIST_KEYS, vars)).keys),
-  );
-
-  server.registerTool(
-    'upsert_keys',
-    {
-      title: 'Upsert keys (bulk)',
-      description:
-        'Bulk-upserts source keys by name (delta sync from local i18n files). Keys not listed are ' +
-        'left untouched. Returns added/updated/unchanged counts; set `dryRun` to preview.',
-      inputSchema: {
-        projectId: z.string(),
-        keys: z
-          .array(
-            z.object({
-              key: z.string(),
-              sourceText: z.string(),
-              context: z.string().optional(),
-              maxLength: z.number().int().positive().optional(),
-            }),
-          )
-          .min(1),
-        dryRun: z.boolean().default(false),
-      },
-      annotations: { idempotentHint: true, openWorldHint: true },
-    },
-    async ({ projectId, keys, dryRun }) =>
-      jsonResult((await gql.request(UPSERT_KEYS, { projectId, input: keys, dryRun })).upsertKeys),
-  );
-
-  server.registerTool(
-    'update_key',
-    {
-      title: 'Update key',
-      description: 'Updates a single key (source text, context, max length).',
-      inputSchema: {
-        projectId: z.string(),
-        keyId: z.string(),
-        sourceText: z.string().optional(),
-        context: z.string().optional(),
-        maxLength: z.number().int().positive().optional(),
-      },
-      annotations: { idempotentHint: true, openWorldHint: true },
-    },
-    async ({ projectId, keyId, ...input }) =>
-      jsonResult((await gql.request(UPDATE_KEY, { projectId, id: keyId, input })).updateKey),
-  );
-
-  server.registerTool(
-    'delete_key',
-    {
-      title: 'Delete key',
-      description: 'Deletes a key and its translations. Destructive — confirm first.',
-      inputSchema: { projectId: z.string(), keyId: z.string() },
-      annotations: { destructiveHint: true, openWorldHint: true },
-    },
-    async ({ projectId, keyId }) =>
-      jsonResult((await gql.request(DELETE_KEY, { projectId, id: keyId })).deleteKey),
-  );
-
-  server.registerTool(
-    '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.',
-      inputSchema: {
-        projectId: z.string(),
-        content: z.string(),
-        format: z.enum(FORMATS),
-        dryRun: z.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,
-      ),
-  );
-}

package/src/tools/locales.ts

@@ -1,60 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { ADD_LOCALE, LIST_LOCALES, REMOVE_LOCALE, SEED_STARTER_LOCALES, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerLocaleTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_locales',
-    {
-      title: 'List locales',
-      description: 'Lists the target locales configured for a project.',
-      inputSchema: { projectId: z.string() },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ projectId }) => jsonResult((await gql.request(LIST_LOCALES, { projectId })).locales),
-  );
-
-  server.registerTool(
-    'add_locale',
-    {
-      title: 'Add locale',
-      description: 'Adds a target locale (BCP-47 code) to a project.',
-      inputSchema: {
-        projectId: z.string(),
-        code: z.string().describe('BCP-47 code, e.g. "de-DE"'),
-        name: z.string().optional(),
-        formality: z.string().optional(),
-        gender: z.string().optional(),
-        variant: z.string().optional(),
-      },
-      annotations: { openWorldHint: true },
-    },
-    async ({ projectId, ...input }) =>
-      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: z.string(), codes: z.array(z.string()).optional() },
-      annotations: { openWorldHint: true },
-    },
-    async ({ projectId, codes }) =>
-      jsonResult((await gql.request(SEED_STARTER_LOCALES, { projectId, codes })).seedStarterLocales),
-  );
-
-  server.registerTool(
-    'remove_locale',
-    {
-      title: 'Remove locale',
-      description: 'Removes a target locale and its translations. Destructive — confirm first.',
-      inputSchema: { projectId: z.string(), localeId: z.string() },
-      annotations: { destructiveHint: true, openWorldHint: true },
-    },
-    async ({ projectId, localeId }) =>
-      jsonResult((await gql.request(REMOVE_LOCALE, { projectId, id: localeId })).removeLocale),
-  );
-}

package/src/tools/projects.ts

@@ -1,74 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { CREATE_PROJECT, GET_PROJECT, LIST_PROJECTS, UPDATE_PROJECT, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerProjectTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_projects',
-    {
-      title: 'List projects',
-      description: 'Lists localization projects in the active organization (paginated).',
-      inputSchema: {
-        skip: z.number().int().min(0).default(0),
-        take: z.number().int().min(1).max(100).default(25),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ skip, take }) => jsonResult((await gql.request(LIST_PROJECTS, { skip, take })).projects),
-  );
-
-  server.registerTool(
-    'get_project',
-    {
-      title: 'Get project',
-      description:
-        'Project settings plus analytics, including per-locale progress with the `untranslated` ' +
-        'count used to decide the batch threshold (see get_config).',
-      inputSchema: { projectId: z.string() },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ projectId }) => jsonResult(await gql.request(GET_PROJECT, { id: projectId })),
-  );
-
-  server.registerTool(
-    'create_project',
-    {
-      title: 'Create project',
-      description: 'Creates a localization project. `sourceLocale` defaults to "en".',
-      inputSchema: {
-        name: z.string(),
-        sourceLocale: z.string().default('en'),
-        description: z.string().optional(),
-        context: z.string().optional(),
-        requireReview: z.boolean().optional(),
-        qaCriticEnabled: z.boolean().optional(),
-      },
-      annotations: { openWorldHint: true },
-    },
-    async (input) => jsonResult((await gql.request(CREATE_PROJECT, { input })).createProject),
-  );
-
-  server.registerTool(
-    'update_project',
-    {
-      title: 'Update project',
-      description: 'Updates project settings (name, source locale, review/QA flags, context).',
-      inputSchema: {
-        projectId: z.string(),
-        name: z.string().optional(),
-        sourceLocale: z.string().optional(),
-        description: z.string().optional(),
-        context: z.string().optional(),
-        requireReview: z.boolean().optional(),
-        qaCriticEnabled: z.boolean().optional(),
-        exportApprovedOnly: z.boolean().optional(),
-        sortKeysAlphabetically: z.boolean().optional(),
-        status: z.string().optional(),
-      },
-      annotations: { idempotentHint: true, openWorldHint: true },
-    },
-    async ({ projectId, ...input }) =>
-      jsonResult((await gql.request(UPDATE_PROJECT, { id: projectId, input })).updateProject),
-  );
-}

package/src/tools/providers.ts

@@ -1,35 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { CONFIGURE_LLM_PROVIDER, LIST_LLM_PROVIDERS, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerProviderTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_llm_providers',
-    {
-      title: 'List LLM providers',
-      description: 'Configured LLM providers for the org (never exposes the API key).',
-      inputSchema: {},
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async () => jsonResult((await gql.request(LIST_LLM_PROVIDERS)).llmProviders),
-  );
-
-  server.registerTool(
-    'configure_llm_provider',
-    {
-      title: 'Configure LLM provider',
-      description:
-        'Adds a BYOK LLM provider (OPENROUTER | OPENAI | ANTHROPIC). The key is stored encrypted at rest.',
-      inputSchema: {
-        type: z.enum(['OPENROUTER', 'OPENAI', 'ANTHROPIC']),
-        label: z.string(),
-        apiKey: z.string(),
-        baseUrl: z.string().optional(),
-        defaultModel: z.string().optional(),
-      },
-      annotations: { openWorldHint: true },
-    },
-    async (input) => jsonResult((await gql.request(CONFIGURE_LLM_PROVIDER, { input })).configureLlmProvider),
-  );
-}

package/src/tools/qa.ts

@@ -1,46 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { LIST_QA_ISSUES, RUN_LOCALE_QA, RUN_QA, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerQaTools(server: McpServer, gql: GraphQLClient): void {
-  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: z.string(), localeId: z.string() },
-      annotations: { openWorldHint: true },
-    },
-    async (vars) => jsonResult((await gql.request(RUN_LOCALE_QA, vars)).runLocaleQa),
-  );
-
-  server.registerTool(
-    'run_qa',
-    {
-      title: 'Run QA on a translation',
-      description: 'Runs QA on one translation and returns its score and issues (synchronous).',
-      inputSchema: { projectId: z.string(), translationId: z.string() },
-      annotations: { openWorldHint: true },
-    },
-    async (vars) => jsonResult((await gql.request(RUN_QA, vars)).runQa),
-  );
-
-  server.registerTool(
-    'list_qa_issues',
-    {
-      title: 'List QA issues',
-      description: 'Open QA issues for a locale, plus the issue-type facets (filter tabs).',
-      inputSchema: {
-        projectId: z.string(),
-        localeId: z.string(),
-        type: z.string().optional(),
-        skip: z.number().int().min(0).default(0),
-        take: z.number().int().min(1).max(100).default(25),
-      },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async (vars) => jsonResult(await gql.request(LIST_QA_ISSUES, vars)),
-  );
-}

package/src/tools/styleguides.ts

@@ -1,49 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { CREATE_STYLE_GUIDE, GENERATE_STYLE_GUIDE, LIST_STYLE_GUIDES, type GraphQLClient } from '@syntholoc/sdk';
-import { jsonResult } from '../util';
-
-export function registerStyleGuideTools(server: McpServer, gql: GraphQLClient): void {
-  server.registerTool(
-    'list_style_guides',
-    {
-      title: 'List style guides',
-      description: 'Lists style guides (project-scoped if projectId given, else org-wide).',
-      inputSchema: { projectId: z.string().optional() },
-      annotations: { readOnlyHint: true, openWorldHint: true },
-    },
-    async ({ projectId }) => jsonResult((await gql.request(LIST_STYLE_GUIDES, { projectId })).styleGuides),
-  );
-
-  server.registerTool(
-    'generate_style_guide',
-    {
-      title: 'Generate style guide (draft)',
-      description:
-        'Drafts a tone/rules/prompt-fragment style guide from the project (optionally per locale). ' +
-        'Returns a draft — persist it with create_style_guide.',
-      inputSchema: { projectId: z.string(), localeCode: z.string().optional() },
-      annotations: { openWorldHint: true },
-    },
-    async ({ projectId, localeCode }) =>
-      jsonResult((await gql.request(GENERATE_STYLE_GUIDE, { input: { projectId, localeCode } })).generateStyleGuide),
-  );
-
-  server.registerTool(
-    'create_style_guide',
-    {
-      title: 'Create style guide',
-      description: 'Persists a style guide (tone, rules JSON, prompt fragment), project- or locale-scoped.',
-      inputSchema: {
-        name: z.string(),
-        projectId: z.string().optional(),
-        localeCode: z.string().optional(),
-        tone: z.string().optional(),
-        promptFragment: z.string().optional(),
-        rules: z.array(z.string()).optional(),
-      },
-      annotations: { openWorldHint: true },
-    },
-    async (input) => jsonResult((await gql.request(CREATE_STYLE_GUIDE, { input })).createStyleGuide),
-  );
-}