@better-i18n/mcp-types 0.2.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@better-i18n/mcp-types",
+  "version": "0.2.0",
+  "description": "Type definitions and schemas for Better i18n MCP API",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schemas": "./src/schemas.ts",
+    "./types": "./src/types.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/better-i18n/better-i18n.git",
+    "directory": "packages/mcp-types"
+  },
+  "license": "MIT"
+}

package/src/client-types.ts

@@ -0,0 +1,93 @@
+/**
+ * MCP Client Types
+ *
+ * Type definitions for the Better i18n MCP API client.
+ * These types provide type safety for API calls without requiring
+ * the actual tRPC router implementation.
+ */
+
+import type {
+  GetProjectInput,
+  GetAllTranslationsInput,
+  ListKeysInput,
+  CreateKeysInput,
+  UpdateKeysInput,
+  DeleteKeysInput,
+  AddLanguageInput,
+  GetSyncsInput,
+  GetSyncInput,
+} from "./schemas";
+
+import type {
+  ListProjectsResponse,
+  GetProjectResponse,
+  GetAllTranslationsResponse,
+  ListKeysResponse,
+  CreateKeysResponse,
+  UpdateKeysResponse,
+  DeleteKeysResponse,
+  AddLanguageResponse,
+  GetSyncsResponse,
+  GetSyncResponse,
+} from "./types";
+
+/**
+ * MCP API client interface.
+ *
+ * This interface defines the shape of the MCP API for type-safe client usage.
+ * Use this to wrap an untyped tRPC client for full type safety.
+ *
+ * @example
+ * ```typescript
+ * import { createTRPCClient } from "@trpc/client";
+ * import type { MCPClient } from "@better-i18n/mcp-types";
+ *
+ * // Create untyped client
+ * const rawClient = createTRPCClient<any>({ ... });
+ *
+ * // Use as typed client
+ * const client = rawClient as unknown as { mcp: MCPClient };
+ * const projects = await client.mcp.listProjects.query();
+ * ```
+ */
+export interface MCPClient {
+  listProjects: {
+    query: () => Promise<ListProjectsResponse>;
+  };
+  getProject: {
+    query: (input: GetProjectInput) => Promise<GetProjectResponse>;
+  };
+  getAllTranslations: {
+    query: (
+      input: GetAllTranslationsInput
+    ) => Promise<GetAllTranslationsResponse>;
+  };
+  listKeys: {
+    query: (input: ListKeysInput) => Promise<ListKeysResponse>;
+  };
+  createKeys: {
+    mutate: (input: CreateKeysInput) => Promise<CreateKeysResponse>;
+  };
+  updateKeys: {
+    mutate: (input: UpdateKeysInput) => Promise<UpdateKeysResponse>;
+  };
+  deleteKeys: {
+    mutate: (input: DeleteKeysInput) => Promise<DeleteKeysResponse>;
+  };
+  addLanguage: {
+    mutate: (input: AddLanguageInput) => Promise<AddLanguageResponse>;
+  };
+  getSyncs: {
+    query: (input: GetSyncsInput) => Promise<GetSyncsResponse>;
+  };
+  getSync: {
+    query: (input: GetSyncInput) => Promise<GetSyncResponse>;
+  };
+}
+
+/**
+ * Full API client interface with mcp namespace.
+ */
+export interface APIClient {
+  mcp: MCPClient;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @better-i18n/mcp-types
+ *
+ * Type definitions and Zod schemas for the Better i18n MCP API.
+ *
+ * This package defines the contract between:
+ * - The Better i18n API (platform)
+ * - The MCP server package (@better-i18n/mcp)
+ * - Any other clients that want type-safe API access
+ *
+ * @example
+ * ```typescript
+ * import { createTRPCClient } from "@trpc/client";
+ * import type { AppRouter } from "@better-i18n/mcp-types";
+ *
+ * const client = createTRPCClient<AppRouter>({
+ *   links: [httpBatchLink({ url: "https://api.better-i18n.com/api/trpc" })],
+ * });
+ *
+ * // Type-safe API calls
+ * const projects = await client.mcp.listProjects.query();
+ * ```
+ */
+
+// Re-export all schemas
+export * from "./schemas";
+
+// Re-export all types
+export * from "./types";
+
+// Re-export client types
+export * from "./client-types";

package/src/schemas.ts

@@ -0,0 +1,257 @@
+/**
+ * MCP API Schemas
+ *
+ * Zod validation schemas for MCP router endpoints.
+ * These schemas define the contract between the API and MCP clients.
+ *
+ * Uses COMPACT format (k, n, ns, t, v) for efficient AI communication.
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// Base Schemas
+// ============================================================================
+
+/**
+ * Base schema for identifying a project.
+ * All MCP operations require org and project slugs from i18n.config.ts.
+ */
+export const projectIdentifierSchema = z.object({
+  /** Organization slug (e.g., "my-company") - from i18n.config.ts */
+  orgSlug: z.string().describe("Organization slug from i18n.config.ts"),
+  /** Project slug (e.g., "my-app") - from i18n.config.ts */
+  projectSlug: z.string().describe("Project slug from i18n.config.ts"),
+});
+
+export type ProjectIdentifier = z.infer<typeof projectIdentifierSchema>;
+
+// ============================================================================
+// Read Endpoint Schemas
+// ============================================================================
+
+/**
+ * Input schema for getProject endpoint.
+ */
+export const getProjectInput = projectIdentifierSchema;
+export type GetProjectInput = z.infer<typeof getProjectInput>;
+
+/**
+ * Input schema for listKeys endpoint.
+ */
+export const listKeysInput = projectIdentifierSchema.extend({
+  /** Search by key name (partial match) — string or array for multi-term search */
+  search: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe(
+      "Search keys by name (partial match). Single string or array for multi-term search."
+    ),
+  /** Filter by namespaces */
+  namespaces: z
+    .array(z.string())
+    .optional()
+    .describe("Only return keys from these namespaces"),
+  /** Find keys missing translation for this language code (e.g., 'tr', 'de') */
+  missingLanguage: z
+    .string()
+    .optional()
+    .describe("Filter to keys MISSING translation for this language"),
+  /** Page number (1-indexed, default: 1) */
+  page: z.number().min(1).optional(),
+  /** Number of results per page (max 100, default: 50) */
+  limit: z.number().min(1).max(100).optional(),
+});
+export type ListKeysInput = z.infer<typeof listKeysInput>;
+
+/**
+ * Input schema for getAllTranslations endpoint.
+ * Returns ALL keys without pagination - designed for AI/MCP usage.
+ *
+ * SEARCH + FILTER:
+ * - search: Text to search for (in source text or specified languages)
+ * - languages: Which languages to search in AND return translations for
+ *
+ * EXAMPLES:
+ * - Find "login" in source: { search: "login" }
+ * - Find "Giriş" in Turkish: { search: "Giriş", languages: ["tr"] }
+ * - Get all Turkish translations: { languages: ["tr"] }
+ * - Get specific keys: { keys: ["auth.login.title", "auth.login.button"] }
+ */
+export const getAllTranslationsInput = projectIdentifierSchema.extend({
+  /** Optional: filter by namespaces */
+  namespaces: z
+    .array(z.string())
+    .optional()
+    .describe("Only return keys from these namespaces"),
+  /** Optional: specific key names to fetch */
+  keys: z
+    .array(z.string())
+    .optional()
+    .describe("Fetch specific keys by name (exact match)"),
+  /** Optional: search text in source or translations (string or array) */
+  search: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe(
+      "Text to search for in source text or translations (case-insensitive). Single string or array for multi-term search."
+    ),
+  /** Optional: languages to search in AND return translations for */
+  languages: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Language codes to search in and return (e.g., ['tr', 'de']). If omitted with search, searches source text. If omitted without search, returns all languages."
+    ),
+  /** Optional: filter by translation status (default: all) */
+  status: z
+    .enum(["missing", "draft", "approved", "all"])
+    .optional()
+    .describe(
+      "Filter by status: 'missing' (no translation), 'draft', 'approved', 'all' (default: 'all')"
+    ),
+});
+export type GetAllTranslationsInput = z.infer<typeof getAllTranslationsInput>;
+
+// ============================================================================
+// Write Endpoint Schemas - COMPACT FORMAT
+// ============================================================================
+
+/**
+ * Compact key item for createKeys endpoint.
+ *
+ * COMPACT FORMAT:
+ * - n: key name (e.g., "submit_button", "nav.home")
+ * - ns: namespace (default: "default")
+ * - v: source value (source language text)
+ * - t: translations object { langCode: text }
+ */
+export const compactCreateKeyItem = z.object({
+  /** Key name (e.g., "submit_button", "nav.home") */
+  n: z.string().describe("Key name identifier"),
+  /** Namespace (default: "default" = root level) */
+  ns: z.string().default("default").describe("Namespace for grouping"),
+  /** Source value (source language text) */
+  v: z.string().optional().describe("Source language text"),
+  /** Target translations: { 'tr': 'Turkish text', 'de': 'German text' } */
+  t: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Target translations object"),
+});
+export type CompactCreateKeyItem = z.infer<typeof compactCreateKeyItem>;
+
+/**
+ * Input schema for createKeys endpoint.
+ * Creates one or more translation keys with optional translations.
+ *
+ * COMPACT FORMAT - uses k array with { n, ns, v, t }
+ */
+export const createKeysInput = projectIdentifierSchema.extend({
+  /** Array of keys to create */
+  k: z.array(compactCreateKeyItem).min(1).describe("Array of keys to create"),
+});
+export type CreateKeysInput = z.infer<typeof createKeysInput>;
+
+/**
+ * Compact translation update item for updateKeys endpoint.
+ *
+ * COMPACT FORMAT:
+ * - k: key identifier (keyId or key name)
+ * - n: key name (optional, for lookup)
+ * - ns: namespace
+ * - l: language code
+ * - t: translation text
+ * - s: is source language (boolean)
+ * - st: status (optional)
+ */
+export const compactUpdateItem = z.object({
+  /** Key identifier (keyId or key name) */
+  k: z.string().describe("Key identifier"),
+  /** Key name (optional) */
+  n: z.string().optional().describe("Key name"),
+  /** Namespace */
+  ns: z.string().optional().describe("Namespace"),
+  /** Language code */
+  l: z.string().describe("Language code"),
+  /** Translation text */
+  t: z.string().describe("Translation text"),
+  /** Is source language */
+  s: z.boolean().optional().describe("Is source language"),
+  /** Status */
+  st: z.string().optional().describe("Translation status"),
+});
+export type CompactUpdateItem = z.infer<typeof compactUpdateItem>;
+
+/**
+ * Input schema for updateKeys endpoint.
+ * Updates translations for one or more keys.
+ *
+ * COMPACT FORMAT - uses t array with { k, n, ns, l, t, s, st }
+ */
+export const updateKeysInput = projectIdentifierSchema.extend({
+  /** Array of translation updates */
+  t: z
+    .array(compactUpdateItem)
+    .min(1)
+    .describe("Array of translation updates"),
+});
+export type UpdateKeysInput = z.infer<typeof updateKeysInput>;
+
+/**
+ * Input schema for deleteKeys endpoint.
+ * Soft-deletes translation keys by UUID.
+ */
+export const deleteKeysInput = projectIdentifierSchema.extend({
+  /** Array of key IDs (UUIDs) to delete */
+  keyIds: z.array(z.string().uuid()).min(1).max(100),
+});
+export type DeleteKeysInput = z.infer<typeof deleteKeysInput>;
+
+/**
+ * Input schema for addLanguage endpoint.
+ */
+export const addLanguageInput = projectIdentifierSchema.extend({
+  /** ISO 639-1 language code (e.g., "fr", "ja", "de") */
+  languageCode: z.string().min(2).max(5),
+});
+export type AddLanguageInput = z.infer<typeof addLanguageInput>;
+
+// ============================================================================
+// Sync Endpoint Schemas
+// ============================================================================
+
+/**
+ * Input schema for getSyncs endpoint.
+ * Lists recent sync operations for a project.
+ */
+export const getSyncsInput = projectIdentifierSchema.extend({
+  /** Maximum number of sync jobs to return (default: 10, max: 50) */
+  limit: z
+    .number()
+    .min(1)
+    .max(50)
+    .optional()
+    .describe("Number of sync jobs to return (default: 10)"),
+  /** Filter by sync status */
+  status: z
+    .enum(["pending", "in_progress", "completed", "failed"])
+    .optional()
+    .describe("Filter syncs by status"),
+  /** Filter by job type */
+  type: z
+    .enum(["initial_import", "source_sync", "cdn_upload", "publish_batch"])
+    .optional()
+    .describe("Filter syncs by job type"),
+});
+export type GetSyncsInput = z.infer<typeof getSyncsInput>;
+
+/**
+ * Input schema for getSync endpoint.
+ * Get detailed information about a specific sync operation.
+ */
+export const getSyncInput = z.object({
+  /** Sync job ID */
+  syncId: z.string().describe("The sync job ID to retrieve details for"),
+});
+export type GetSyncInput = z.infer<typeof getSyncInput>;

package/src/types.ts

@@ -0,0 +1,328 @@
+/**
+ * MCP API Types
+ *
+ * TypeScript interfaces for MCP router responses.
+ * These types define the contract between the API and MCP clients.
+ */
+
+// ============================================================================
+// Project Types
+// ============================================================================
+
+/**
+ * Project info from listProjects endpoint.
+ */
+export interface ProjectInfo {
+  /** Project identifier in 'org/project' format */
+  slug: string;
+  /** Project display name */
+  name: string;
+  /** Organization display name */
+  organizationName: string;
+  /** Source language code (e.g., "en") */
+  sourceLanguage: string;
+  /** Target language codes */
+  targetLanguages: string[];
+}
+
+/**
+ * Response from listProjects endpoint.
+ */
+export interface ListProjectsResponse {
+  projects: ProjectInfo[];
+}
+
+/**
+ * Coverage info per language.
+ */
+export interface LanguageCoverage {
+  /** Number of translated keys */
+  translated: number;
+  /** Percentage of keys translated (0-100) */
+  percentage: number;
+}
+
+/**
+ * Response from getProject endpoint.
+ */
+export interface GetProjectResponse {
+  /** Project identifier in 'org/project' format */
+  project: string;
+  /** Source language code */
+  sourceLanguage: string;
+  /** Available namespaces */
+  namespaces: string[];
+  /** Available target languages */
+  languages: string[];
+  /** Total number of translation keys */
+  totalKeys: number;
+  /** Coverage per language */
+  coverage: Record<string, LanguageCoverage>;
+  /** Optional message (e.g., when no repository linked) */
+  message?: string;
+}
+
+// ============================================================================
+// Translation Key Types
+// ============================================================================
+
+/**
+ * Translation info within a key.
+ */
+export interface TranslationInfo {
+  /** Translation record ID */
+  id: string;
+  /** Translated text */
+  text: string;
+  /** Translation status */
+  status: string;
+}
+
+/**
+ * Key with full translations from getAllTranslations endpoint.
+ */
+export interface KeyWithFullTranslations {
+  /** Key UUID */
+  id: string;
+  /** Key name */
+  key: string;
+  /** Namespace */
+  namespace: string;
+  /** Source text (source language) */
+  sourceText: string | null;
+  /** Translations by language code */
+  translations: Record<string, TranslationInfo>;
+}
+
+/**
+ * Response from getAllTranslations endpoint.
+ */
+export interface GetAllTranslationsResponse {
+  /** Project identifier */
+  project: string;
+  /** Source language code */
+  sourceLanguage: string;
+  /** Total number of keys returned */
+  total: number;
+  /** Search term if provided */
+  search: string | string[] | null;
+  /** Languages filter if provided */
+  languages: string[] | null;
+  /** Status filter */
+  status?: string;
+  /** Translation keys with their translations */
+  keys: KeyWithFullTranslations[];
+}
+
+/**
+ * Key with translations from listKeys endpoint.
+ */
+export interface KeyWithTranslations {
+  /** Key UUID */
+  id: string;
+  /** Key name */
+  key: string;
+  /** Namespace */
+  namespace: string;
+  /** Source text (source language) */
+  sourceText: string | null;
+  /** Translations by language code (text only) */
+  translations: Record<string, string>;
+  /** List of languages with translations */
+  translatedLanguages: string[];
+}
+
+/**
+ * Response from listKeys endpoint.
+ */
+export interface ListKeysResponse {
+  /** Total number of matching keys */
+  total: number;
+  /** Current page number */
+  page: number;
+  /** Results per page */
+  limit: number;
+  /** Translation keys */
+  keys: KeyWithTranslations[];
+}
+
+// ============================================================================
+// Create/Update/Delete Types
+// ============================================================================
+
+/**
+ * Result for a single created key.
+ */
+export interface CreateKeyResultItem {
+  /** Key name */
+  key: string;
+  /** Created key UUID */
+  keyId: string;
+  /** Number of translations added */
+  translationsAdded: number;
+}
+
+/**
+ * Response from createKeys endpoint.
+ */
+export interface CreateKeysResponse {
+  /** Operation success */
+  success: boolean;
+  /** Number of keys created */
+  keysCreated: number;
+  /** Created key details */
+  keys: CreateKeyResultItem[];
+  /** Skipped keys (duplicates) */
+  skipped?: Array<{ key: string; reason: string }>;
+}
+
+/**
+ * Result for a single updated key.
+ */
+export interface UpdateKeyResultItem {
+  /** Key name */
+  key: string;
+  /** Languages that were updated */
+  updatedLanguages: string[];
+  /** Whether source text was updated */
+  sourceUpdated: boolean;
+}
+
+/**
+ * Response from updateKeys endpoint.
+ */
+export interface UpdateKeysResponse {
+  /** Operation success */
+  success: boolean;
+  /** Number of keys updated */
+  keysUpdated: number;
+  /** Updated key details */
+  updates: UpdateKeyResultItem[];
+}
+
+/**
+ * Marked key info from deleteKeys endpoint.
+ */
+export interface MarkedKeyInfo {
+  /** Key UUID */
+  keyId: string;
+  /** Key name */
+  key: string;
+  /** Namespace */
+  namespace: string | null;
+}
+
+/**
+ * Response from deleteKeys endpoint.
+ */
+export interface DeleteKeysResponse {
+  /** Operation success */
+  success: boolean;
+  /** Number of keys marked for deletion */
+  markedCount: number;
+  /** Marked key details */
+  marked: MarkedKeyInfo[];
+  /** Key IDs that were not found */
+  skipped?: string[];
+}
+
+/**
+ * Response from addLanguage endpoint.
+ */
+export interface AddLanguageResponse {
+  /** Operation success */
+  success: boolean;
+  /** Result message */
+  message: string;
+  /** Whether language already existed */
+  alreadyExists: boolean;
+}
+
+// ============================================================================
+// Sync Types
+// ============================================================================
+
+/**
+ * Sync job type.
+ */
+export type SyncJobType =
+  | "initial_import"
+  | "source_sync"
+  | "cdn_upload"
+  | "publish_batch";
+
+/**
+ * Sync job status.
+ */
+export type SyncJobStatus = "pending" | "in_progress" | "completed" | "failed";
+
+/**
+ * Sync job summary from getSyncs endpoint.
+ */
+export interface SyncJobSummary {
+  /** Sync job ID */
+  id: string;
+  /** Job type */
+  type: SyncJobType;
+  /** Job status */
+  status: SyncJobStatus;
+  /** Start time (ISO string) */
+  startedAt: string;
+  /** Completion time (ISO string) */
+  completedAt?: string;
+  /** Error message if failed */
+  errorMessage?: string | null;
+  /** Job metadata */
+  metadata: {
+    keysProcessed: number;
+    totalFiles?: number | null;
+    processedFiles?: number | null;
+  };
+}
+
+/**
+ * Response from getSyncs endpoint.
+ */
+export interface GetSyncsResponse {
+  /** Project identifier */
+  project: string;
+  /** Total syncs returned */
+  total: number;
+  /** Sync job summaries */
+  syncs: SyncJobSummary[];
+  /** Optional message */
+  message?: string;
+}
+
+/**
+ * Affected key from sync operation.
+ */
+export interface AffectedKey {
+  /** Key name */
+  key: string;
+  /** Action performed */
+  action: string;
+}
+
+/**
+ * Response from getSync endpoint.
+ */
+export interface GetSyncResponse {
+  /** Sync job ID */
+  id: string;
+  /** Job type */
+  type: SyncJobType;
+  /** Job status */
+  status: SyncJobStatus;
+  /** Start time (ISO string) */
+  startedAt: string;
+  /** Completion time (ISO string) */
+  completedAt?: string;
+  /** Error message if failed */
+  errorMessage?: string | null;
+  /** Activity logs */
+  logs: string[];
+  /** Affected keys */
+  affectedKeys: AffectedKey[];
+}
+