@better-i18n/mcp-types 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/mcp-types",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Type definitions and schemas for Better i18n MCP API",
   "type": "module",
   "main": "./src/index.ts",

package/src/schemas.ts

@@ -63,7 +63,10 @@ export const listKeysInput = projectIdentifierSchema.extend({
   /** Number of results per page (max 100) */
   limit: z.number().min(1).max(100).default(50),
 });
-export type ListKeysInput = z.infer<typeof listKeysInput>;
+/** Output type (after defaults applied - server side) */
+export type ListKeysOutput = z.infer<typeof listKeysInput>;
+/** Input type (before defaults - client side) */
+export type ListKeysInput = z.input<typeof listKeysInput>;
 
 /**
  * Input schema for getAllTranslations endpoint.
@@ -112,12 +115,48 @@ export const getAllTranslationsInput = projectIdentifierSchema.extend({
       "Filter by status: 'missing' (no translation), 'draft', 'approved', 'all'",
     ),
 });
-export type GetAllTranslationsInput = z.infer<typeof getAllTranslationsInput>;
+/** Output type (after defaults applied - server side) */
+export type GetAllTranslationsOutput = z.infer<typeof getAllTranslationsInput>;
+/** Input type (before defaults - client side) */
+export type GetAllTranslationsInput = z.input<typeof getAllTranslationsInput>;
 
 // ============================================================================
 // Write Endpoint Schemas - COMPACT FORMAT
 // ============================================================================
 
+/**
+ * Namespace context object for enriching namespace metadata.
+ * Provide this on any key to set context on its namespace.
+ * If multiple keys share a namespace, the last context wins.
+ */
+const namespaceContextSchema = z.object({
+  /** Human-readable description of the namespace */
+  description: z
+    .string()
+    .optional()
+    .describe("What this namespace contains (e.g., 'Authentication flow strings')"),
+  /** Owning team */
+  team: z
+    .string()
+    .optional()
+    .describe("Team responsible (e.g., 'auth-team')"),
+  /** Business domain */
+  domain: z
+    .string()
+    .optional()
+    .describe("Business domain (e.g., 'authentication', 'payments')"),
+  /** AI translation guidance specific to this namespace */
+  aiPrompt: z
+    .string()
+    .optional()
+    .describe("Extra AI translation instructions for this namespace"),
+  /** Organizational tags */
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Tags for categorization (e.g., ['critical', 'user-facing'])"),
+});
+
 /**
  * Compact key item for createKeys endpoint.
  *
@@ -126,6 +165,7 @@ export type GetAllTranslationsInput = z.infer<typeof getAllTranslationsInput>;
  * - ns: namespace (default: "default")
  * - v: source value (source language text)
  * - t: translations object { langCode: text }
+ * - nc: namespace context (optional, enriches the namespace)
  */
 const compactCreateKeyItem = z.object({
   /** Key name (e.g., "submit_button", "nav.home") */
@@ -139,6 +179,12 @@ const compactCreateKeyItem = z.object({
     .record(z.string(), z.string())
     .optional()
     .describe("Target translations object"),
+  /** Namespace context - enriches the namespace with metadata */
+  nc: namespaceContextSchema
+    .optional()
+    .describe(
+      "Namespace context: description, team, domain, aiPrompt, tags. Sets metadata on the namespace.",
+    ),
 });
 
 /**
@@ -151,7 +197,8 @@ 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>;
+export type CreateKeysOutput = z.infer<typeof createKeysInput>;
+export type CreateKeysInput = z.input<typeof createKeysInput>;
 
 /**
  * Compact translation update item for updateKeys endpoint.
@@ -180,6 +227,12 @@ const compactUpdateItem = z.object({
   s: z.boolean().optional().describe("Is source language"),
   /** Status */
   st: z.string().optional().describe("Translation status"),
+  /** Namespace context - enriches the namespace with metadata */
+  nc: namespaceContextSchema
+    .optional()
+    .describe(
+      "Namespace context: description, team, domain, aiPrompt, tags. Sets metadata on the namespace.",
+    ),
 });
 
 /**
@@ -192,7 +245,8 @@ 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>;
+export type UpdateKeysOutput = z.infer<typeof updateKeysInput>;
+export type UpdateKeysInput = z.input<typeof updateKeysInput>;
 
 /**
  * Input schema for deleteKeys endpoint.
@@ -202,7 +256,7 @@ 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>;
+export type DeleteKeysInput = z.input<typeof deleteKeysInput>;
 
 /**
  * Input schema for addLanguage endpoint.
@@ -211,7 +265,7 @@ 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>;
+export type AddLanguageInput = z.input<typeof addLanguageInput>;
 
 // ============================================================================
 // Sync Endpoint Schemas
@@ -240,7 +294,8 @@ export const getSyncsInput = projectIdentifierSchema.extend({
     .optional()
     .describe("Filter syncs by job type"),
 });
-export type GetSyncsInput = z.infer<typeof getSyncsInput>;
+export type GetSyncsOutput = z.infer<typeof getSyncsInput>;
+export type GetSyncsInput = z.input<typeof getSyncsInput>;
 
 /**
  * Input schema for getSync endpoint.
@@ -250,4 +305,4 @@ 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>;
+export type GetSyncInput = z.input<typeof getSyncInput>;

package/src/types.ts

@@ -42,6 +42,25 @@ export interface LanguageCoverage {
   percentage: number;
 }
 
+/**
+ * Namespace metadata returned from read endpoints.
+ */
+export interface NamespaceInfo {
+  /** Namespace name ("default" for root keys) */
+  name: string;
+  /** Number of keys in this namespace */
+  keyCount: number;
+  /** Human-readable description */
+  description: string | null;
+  /** Structured context (team, domain, aiPrompt, tags) */
+  context: {
+    team?: string;
+    domain?: string;
+    aiPrompt?: string;
+    tags?: string[];
+  } | null;
+}
+
 /**
  * Response from getProject endpoint.
  */
@@ -50,8 +69,8 @@ export interface GetProjectResponse {
   project: string;
   /** Source language code */
   sourceLanguage: string;
-  /** Available namespaces */
-  namespaces: string[];
+  /** Available namespaces with metadata */
+  namespaces: NamespaceInfo[];
   /** Available target languages */
   languages: string[];
   /** Total number of translation keys */
@@ -112,6 +131,8 @@ export interface GetAllTranslationsResponse {
   status?: string;
   /** Translation keys with their translations */
   keys: KeyWithFullTranslations[];
+  /** Namespace metadata for namespaces present in results */
+  namespaceDetails?: Record<string, NamespaceInfo>;
 }
 
 /**
@@ -140,6 +161,8 @@ export interface ListKeysResponse {
   page: number;
   limit: number;
   keys: KeyWithTranslations[];
+  /** Namespace metadata for namespaces present in results */
+  namespaceDetails?: Record<string, NamespaceInfo>;
 }
 
 // ============================================================================