@l10nmonster/mcp 3.0.0-alpha.16

package/tests/registry.test.js

@@ -0,0 +1,169 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { registry } from '../tools/registry.js';
+import { McpTool } from '../tools/mcpTool.js';
+import { z } from 'zod';
+
+// Mock tool classes for testing
+class TestTool1 extends McpTool {
+    static metadata = {
+        name: 'test_tool_1',
+        description: 'Test tool 1',
+        inputSchema: z.object({})
+    };
+
+    static async execute() {
+        return { result: 'test1' };
+    }
+
+    static handler() {
+        return async () => this.formatResult({ result: 'test1' });
+    }
+}
+
+class TestTool2 extends McpTool {
+    static metadata = {
+        name: 'test_tool_2',
+        description: 'Test tool 2',
+        inputSchema: z.object({})
+    };
+
+    static async execute() {
+        return { result: 'test2' };
+    }
+
+    static handler() {
+        return async () => this.formatResult({ result: 'test2' });
+    }
+}
+
+class OverrideTool extends McpTool {
+    static metadata = {
+        name: 'test_tool_1', // Same name as TestTool1
+        description: 'Override tool',
+        inputSchema: z.object({})
+    };
+
+    static async execute() {
+        return { result: 'override' };
+    }
+
+    static handler() {
+        return async () => this.formatResult({ result: 'override' });
+    }
+}
+
+describe('MCP Registry', () => {
+    beforeEach(() => {
+        // Clear registry before each test
+        registry.clear();
+    });
+
+    it('should register a single tool', () => {
+        registry.registerTool(TestTool1);
+        
+        assert.strictEqual(registry.hasTool('test_tool_1'), true);
+        assert.strictEqual(registry.getTool('test_tool_1'), TestTool1);
+    });
+
+    it('should register multiple tools', () => {
+        registry.registerTools([TestTool1, TestTool2]);
+        
+        assert.strictEqual(registry.hasTool('test_tool_1'), true);
+        assert.strictEqual(registry.hasTool('test_tool_2'), true);
+        
+        const allTools = registry.getAllTools();
+        assert.strictEqual(allTools.length, 2);
+    });
+
+    it('should override existing tool with same name', () => {
+        registry.registerTool(TestTool1);
+        registry.registerTool(OverrideTool);
+        
+        const tool = registry.getTool('test_tool_1');
+        assert.strictEqual(tool, OverrideTool);
+        assert.notStrictEqual(tool, TestTool1);
+    });
+
+    it('should return all registered tools', () => {
+        registry.registerTools([TestTool1, TestTool2]);
+        
+        const allTools = registry.getAllTools();
+        assert.strictEqual(allTools.length, 2);
+        assert.ok(allTools.includes(TestTool1));
+        assert.ok(allTools.includes(TestTool2));
+    });
+
+    it('should return undefined for non-existent tool', () => {
+        const tool = registry.getTool('non_existent');
+        assert.strictEqual(tool, undefined);
+    });
+
+    it('should return false for non-existent tool check', () => {
+        assert.strictEqual(registry.hasTool('non_existent'), false);
+    });
+
+    it('should clear all registered tools', () => {
+        registry.registerTools([TestTool1, TestTool2]);
+        assert.strictEqual(registry.getAllTools().length, 2);
+        
+        registry.clear();
+        assert.strictEqual(registry.getAllTools().length, 0);
+    });
+
+    it('should throw error for invalid tool class', () => {
+        assert.throws(
+            () => registry.registerTool(null),
+            /ToolClass must be a class\/function/
+        );
+        
+        assert.throws(
+            () => registry.registerTool('not a class'),
+            /ToolClass must be a class\/function/
+        );
+    });
+
+    it('should throw error for tool without metadata', () => {
+        class InvalidTool {}
+        
+        assert.throws(
+            () => registry.registerTool(InvalidTool),
+            /must have static metadata property/
+        );
+    });
+
+    it('should throw error for tool without name in metadata', () => {
+        class InvalidTool {
+            static metadata = {
+                description: 'No name'
+            };
+        }
+        
+        assert.throws(
+            () => registry.registerTool(InvalidTool),
+            /metadata must have a string 'name' property/
+        );
+    });
+
+    it('should throw error for tool without handler method', () => {
+        class InvalidTool {
+            static metadata = {
+                name: 'invalid',
+                description: 'No handler'
+            };
+        }
+        
+        assert.throws(
+            () => registry.registerTool(InvalidTool),
+            /must have static handler method/
+        );
+    });
+
+    it('should throw error when registerTools receives non-array', () => {
+        assert.throws(
+            () => registry.registerTools('not an array'),
+            /toolClasses must be an array/
+        );
+    });
+});
+

package/tools/index.js

@@ -0,0 +1,3 @@
+export { SourceQueryTool } from './sourceQuery.js';
+export { TranslateTool } from './translate.js';
+export { StatusTool as TranslationStatusTool } from './status.js';

package/tools/mcpTool.js

@@ -0,0 +1,214 @@
+import { z } from 'zod';
+
+/**
+ * Base error type for MCP tools with structured metadata.
+ */
+export class McpToolError extends Error {
+
+    /**
+     * @param {string} message Error message
+     * @param {Object} [options]
+     * @param {string} [options.code] Stable machine readable error code
+     * @param {boolean} [options.retryable=false] Whether the caller can retry safely
+     * @param {string[]} [options.hints] Recovery hints for the caller
+     * @param {unknown} [options.details] Arbitrary structured payload with extra context
+     * @param {Error} [options.cause] Underlying error
+     */
+    constructor(message, { code, retryable = false, hints, details, cause } = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.retryable = retryable;
+        this.hints = hints;
+        this.details = details;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+
+    static wrap(error, defaults = {}) {
+        if (error instanceof McpToolError) {
+            return error;
+        }
+        return new McpToolError(error?.message ?? 'Unexpected error', {
+            cause: error,
+            ...defaults
+        });
+    }
+}
+
+export class McpInputError extends McpToolError {
+    constructor(message, options = {}) {
+        super(message, { code: 'INVALID_INPUT', ...options });
+    }
+}
+
+export class McpNotFoundError extends McpToolError {
+    constructor(message, options = {}) {
+        super(message, { code: 'NOT_FOUND', ...options });
+    }
+}
+
+export class McpProviderError extends McpToolError {
+    constructor(message, options = {}) {
+        super(message, { code: 'PROVIDER_ERROR', ...options });
+    }
+}
+
+/**
+ * Base class for MCP tools that call underlying MonsterManager functions directly.
+ * 
+ * MCP tools are separate from CLI actions and:
+ * - Return structured data (not console output)
+ * - Have MCP-optimized schemas (not CLI-optimized)
+ * - Call underlying MonsterManager methods directly
+ * 
+ */
+
+export class McpTool {
+
+    /**
+     * Static metadata object containing:
+     * - name: Tool identifier
+     * - description: Tool description for MCP
+     * - inputSchema: Zod schema for input validation
+     * 
+     * Subclasses must define this static property.
+     */
+    static metadata = {
+        name: '',
+        description: '',
+        inputSchema: z.object({})
+    };
+
+    /**
+     * Execute the tool with validated arguments
+     * @param {Object} mm - MonsterManager instance
+     * @param {Object} args - Validated arguments from Zod schema
+     * @returns {Promise<*>} Result from tool execution (will be formatted by handler)
+     */
+    // eslint-disable-next-line no-unused-vars
+    static async execute(mm, args) {
+        throw new Error('Subclasses must implement execute()');
+    }
+
+    /**
+     * Returns an async handler function for MCP tool registration
+     * @param {Object} mm - MonsterManager instance
+     * @returns {Function} Async handler function
+     */
+    static handler(mm) {
+        const schema = this.metadata.inputSchema;
+        
+        return async (args) => {
+            try {
+                const validatedArgs = schema.parse(args);
+                const result = await this.execute(mm, validatedArgs);
+                return this.formatResult(result);
+            } catch (error) {
+                return this.formatError(error);
+            }
+        };
+    }
+
+    /**
+     * Format a result for MCP response
+     * @param {*} result - Result from execute()
+     * @returns {Object} MCP-formatted response
+     */
+    static formatResult(result) {
+        if (result && typeof result === 'object') {
+            // Pass through responses that already conform to MCP response shape
+            if (Array.isArray(result.content)) {
+                return result;
+            }
+            return {
+                content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2)
+                }]
+            };
+        }
+        
+        const text = typeof result === 'string' ? result : String(result);
+        
+        return {
+            content: [{
+                type: 'text',
+                text
+            }]
+        };
+    }
+
+    /**
+     * Format an error for MCP response
+     * @param {Error} error - Error that occurred
+     * @returns {Object} MCP-formatted error response
+     */
+    static formatError(error) {
+        const normalized = McpToolError.wrap(error, { code: 'UNKNOWN_ERROR' });
+        const summary = `Error executing ${this.metadata.name}: ${normalized.message}`;
+
+        const payload = {
+            name: normalized.name,
+            message: normalized.message,
+            code: normalized.code ?? 'UNKNOWN_ERROR',
+            retryable: Boolean(normalized.retryable),
+            hints: normalized.hints ?? [],
+            details: normalized.details
+        };
+
+        const cause = normalized.cause;
+        if (cause && typeof cause === 'object') {
+            let causeName;
+            if ('name' in cause && typeof cause.name === 'string') {
+                causeName = cause.name;
+            } else if (cause.constructor && typeof cause.constructor.name === 'string') {
+                causeName = cause.constructor.name;
+            }
+
+            let causeMessage;
+            if ('message' in cause && typeof cause.message === 'string') {
+                causeMessage = cause.message;
+            }
+
+            payload.cause = {
+                name: causeName,
+                message: causeMessage
+            };
+        }
+        
+        if (error instanceof z.ZodError) {
+            payload.code = 'INVALID_INPUT';
+            payload.details = {
+                issues: error.issues.map(issue => ({
+                    path: issue.path.join('.') || '(root)',
+                    message: issue.message,
+                    code: issue.code
+                }))
+            };
+            if (!payload.hints || payload.hints.length === 0) {
+                payload.hints = [
+                    'Inspect the schema and ensure all required fields are provided.',
+                    'Check enum values and optional defaults.'
+                ];
+            }
+        }
+        
+        if (typeof normalized.stack === 'string') {
+            payload.stack = normalized.stack;
+        }
+        
+        return {
+            content: [{
+                type: 'text',
+                text: summary
+            }, {
+                type: 'text',
+                text: JSON.stringify(payload, null, 2)
+            }],
+            isError: true
+        };
+    }
+}
+

package/tools/registry.js

@@ -0,0 +1,69 @@
+/**
+ * MCP Tool Registry
+ * 
+ * Provides a registration mechanism for extending MCP with custom tools.
+ * External packages can register their own McpTool subclasses which will be
+ * automatically discovered and registered when the MCP server starts.
+ */
+
+class Registry {
+    constructor() {
+        this.registeredTools = new Map(); // toolName -> ToolClass
+    }
+
+    registerTool(ToolClass) {
+        if (!ToolClass || typeof ToolClass !== 'function') {
+            throw new Error('registerTool: ToolClass must be a class/function');
+        }
+
+        if (!ToolClass.metadata || typeof ToolClass.metadata !== 'object') {
+            throw new Error(`registerTool: ${ToolClass.name} must have static metadata property`);
+        }
+
+        if (!ToolClass.metadata.name || typeof ToolClass.metadata.name !== 'string') {
+            throw new Error(`registerTool: ${ToolClass.name} metadata must have a string 'name' property`);
+        }
+
+        if (typeof ToolClass.handler !== 'function') {
+            throw new Error(`registerTool: ${ToolClass.name} must have static handler method`);
+        }
+
+        const toolName = ToolClass.metadata.name;
+        
+        if (this.registeredTools.has(toolName)) {
+            console.warn(`MCP tool "${toolName}" is already registered. Overwriting with new implementation.`);
+        }
+
+        this.registeredTools.set(toolName, ToolClass);
+        console.info(`Registered MCP tool: ${toolName}`);
+    }
+
+    registerTools(toolClasses) {
+        if (!Array.isArray(toolClasses)) {
+            throw new Error('registerTools: toolClasses must be an array');
+        }
+
+        for (const ToolClass of toolClasses) {
+            this.registerTool(ToolClass);
+        }
+    }
+
+    getAllTools() {
+        return Array.from(this.registeredTools.values());
+    }
+
+    getTool(toolName) {
+        return this.registeredTools.get(toolName);
+    }
+
+    hasTool(toolName) {
+        return this.registeredTools.has(toolName);
+    }
+
+    clear() {
+        this.registeredTools.clear();
+    }
+}
+
+export const registry = new Registry();
+

package/tools/sourceQuery.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { McpTool, McpInputError, McpNotFoundError, McpToolError } from './mcpTool.js';
+
+/**
+ * MCP tool for querying source content and translation memory.
+ * 
+ * This tool calls the underlying MonsterManager methods directly,
+ * avoiding CLI-specific concerns like console logging and file I/O.
+ */
+export class SourceQueryTool extends McpTool {
+    static metadata = {
+        name: 'source_query',
+        description: `Query sources in the source snapshot.
+You can write your own where conditions using SQL syntaxt against the following columns:
+- channel: Channel id
+- prj: Project id
+- rid: Resource id
+- sid: Segment id
+- guid: Segment guid
+- nsrc: Normalized source
+- minQ: Desired minimum quality
+- ntgt: Normalized translation (if available)
+- q: Quality score (if translation is available)
+- notes: Notes object (if any)
+- mf: Message format id
+- segProps: Non-standard segment properties object (if any)
+- words: Word count
+- chars: Character count`,
+        inputSchema: z.object({
+            sourceLang: z.string()
+                .describe('Source language code (e.g., "en-US")'),
+            targetLang: z.string()
+                .describe('Target language code (e.g., "es-419")'),
+            channel: z.string()
+                .describe('Channel ID to query sources from'),
+            whereCondition: z.string()
+                .optional()
+                .describe('SQL WHERE condition against sources (default: "true" to match all)'),
+        })
+    };
+
+    static async execute(mm, args) {
+        const { sourceLang, targetLang, channel: channelId } = args;
+        const whereCondition = args.whereCondition ?? 'true';
+
+        const availableChannels = mm.rm.channelIds ?? [];
+        if (availableChannels.length > 0 && !availableChannels.includes(channelId)) {
+            throw new McpNotFoundError(`Channel "${channelId}" not found`, {
+                hints: [`Available channels: ${availableChannels.join(', ')}`]
+            });
+        }
+
+        // Get translation memory and query sources
+        let tm;
+        try {
+            tm = mm.tmm.getTM(sourceLang, targetLang);
+        } catch (error) {
+            throw new McpInputError(`Language pair ${sourceLang}→${targetLang} is not available`, {
+                hints: ['Call translation_status with include=["coverage"] to inspect available language pairs.'],
+                cause: error
+            });
+        }
+
+        let tus;
+        try {
+            tus = await tm.querySource(channelId, whereCondition);
+        } catch (error) {
+            throw new McpToolError('Failed to execute query against source snapshot', {
+                code: 'QUERY_FAILED',
+                hints: [
+                    'Verify that your SQL WHERE clause only references supported columns.',
+                    'Escaping: wrap string literals in single quotes.'
+                ],
+                details: { channelId, whereCondition },
+                cause: error
+            });
+        }
+
+        return {
+            message: tus.length === 0 ? 'No content returned for the specified query' : `Found ${tus.length} translation units`,
+            sourceLang,
+            targetLang,
+            translationUnits: tus,
+        };
+
+    }
+}
+