@l10nmonster/mcp 3.0.0-alpha.17 → 3.1.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+## @l10nmonster/mcp [3.1.1](https://public-github/l10nmonster/l10nmonster/compare/@l10nmonster/mcp@3.1.0...@l10nmonster/mcp@3.1.1) (2025-12-23)
+
+
+### Bug Fixes
+
+* Improve type definitions and checks ([826b412](https://public-github/l10nmonster/l10nmonster/commit/826b412f0f7e761d404165a243b0c2b26c416ac1))
+
+
+
+
+
+### Dependencies
+
+* **@l10nmonster/core:** upgraded to 3.1.1
+
+# @l10nmonster/mcp [3.1.0](https://public-github/l10nmonster/l10nmonster/compare/@l10nmonster/mcp@3.0.0...@l10nmonster/mcp@3.1.0) (2025-12-20)
+
+
+### Bug Fixes
+
+* Make source query channel optional ([1addc68](https://public-github/l10nmonster/l10nmonster/commit/1addc68d009794a92588a28b816d7e9edbab6b47))
+* Pluralization improvements ([5964250](https://public-github/l10nmonster/l10nmonster/commit/596425092c425cc8d6c312ef58509c4c3c537431))
+* Version bumps ([d3030bd](https://public-github/l10nmonster/l10nmonster/commit/d3030bdd0af6ddbc79b3076af7427111ca9b04d0))
+
+
+### Features
+
+* implement an approach for mcp extensibility ([#50](https://public-github/l10nmonster/l10nmonster/issues/50)) ([5fcc89b](https://public-github/l10nmonster/l10nmonster/commit/5fcc89bef8c8af01d88f35dece8290989d04e4d5))

package/interfaces.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Central type definitions for @l10nmonster/mcp
+ * This is the single source of truth for MCP tool interfaces.
+ */
+
+/**
+ * MCP tool metadata definition.
+ */
+export interface McpToolMetadata {
+    /** Tool name identifier. */
+    name: string;
+    /** Tool description for discovery. */
+    description: string;
+    /** Zod input schema for validation. */
+    inputSchema: unknown;
+}
+
+/**
+ * MCP content item in a response.
+ */
+export interface McpContentItem {
+    /** Content type (text, image, resource). */
+    type: 'text' | 'image' | 'resource';
+    /** Text content (for type='text'). */
+    text?: string;
+    /** Base64 data (for type='image'). */
+    data?: string;
+    /** MIME type (for type='image' or 'resource'). */
+    mimeType?: string;
+}
+
+/**
+ * MCP tool response format.
+ */
+export interface McpToolResponse {
+    /** Array of content items. */
+    content: McpContentItem[];
+    /** True if this response represents an error. */
+    isError?: boolean;
+}
+
+/**
+ * MCP tool interface - defines contract for MCP tools.
+ */
+export interface McpToolInterface {
+    /** Static metadata for the tool. */
+    metadata: McpToolMetadata;
+
+    /**
+     * Execute the tool with given arguments.
+     * @param mm - MonsterManager instance.
+     * @param args - Tool arguments.
+     * @returns Tool result.
+     */
+    execute(mm: unknown, args: Record<string, unknown>): Promise<unknown>;
+
+    /**
+     * Get handler function for MCP registration.
+     * @param mm - MonsterManager instance.
+     * @returns Handler function.
+     */
+    handler(mm: unknown): (args: Record<string, unknown>) => Promise<McpToolResponse>;
+
+    /**
+     * Format a result for MCP response.
+     * @param result - Tool execution result.
+     * @returns Formatted MCP response.
+     */
+    formatResult(result: unknown): McpToolResponse;
+
+    /**
+     * Format an error for MCP response.
+     * @param error - Error to format.
+     * @returns Formatted error response.
+     */
+    formatError(error: Error): McpToolResponse;
+}

package/package.json

@@ -1,31 +1,32 @@
 {
-  "name": "@l10nmonster/mcp",
-  "version": "3.0.0-alpha.17",
-  "description": "L10n Monster Model Context Protocol (MCP) Server",
-  "type": "module",
-  "main": "index.js",
-  "scripts": {
-    "test": "node --test tests/*.test.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.18.1",
-    "zod": "^3"
-  },
-  "peerDependencies": {
-    "@l10nmonster/core": "^3.0.0-alpha.0"
-  },
-  "engines": {
-    "node": ">=22.11.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0"
-  },
-  "keywords": [
-    "mcp",
-    "localization",
-    "translation",
-    "l10n"
-  ],
-  "author": "L10n Monster",
-  "license": "MIT"
+    "name": "@l10nmonster/mcp",
+    "version": "3.1.1",
+    "description": "L10n Monster Model Context Protocol (MCP) Server",
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "test": "node --test tests/*.test.js",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.18.1",
+        "zod": "^3"
+    },
+    "peerDependencies": {
+        "@l10nmonster/core": "3.1.1"
+    },
+    "engines": {
+        "node": ">=22.11.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0"
+    },
+    "keywords": [
+        "mcp",
+        "localization",
+        "translation",
+        "l10n"
+    ],
+    "author": "L10n Monster",
+    "license": "MIT"
 }

package/server.js

@@ -4,8 +4,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import * as mcpTools from './tools/index.js';
 import { registry } from './tools/registry.js';
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
+import { l10nMonsterVersion } from '@l10nmonster/core';
 
 // Session management for HTTP transport
 const sessions = new Map(); // sessionId -> { transport, lastActivity }
@@ -15,20 +14,8 @@ const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 // Use a WeakMap to avoid memory leaks. Once all sessions to a server are closed the server will be garbage collected.
 const serverInstances = new WeakMap(); // monsterManager -> McpServer
 
-
-async function getMcpPackageVersion() {
-    try {
-        const packageJsonContent = await readFile(path.join(import.meta.dirname, 'package.json'), 'utf-8');
-        const packageJson = JSON.parse(packageJsonContent.toString());
-        return packageJson.version;
-    } catch (error) {
-        console.error('Error parsing MCP package version:', error);
-        return '0.0.1-unknown';
-    }
-}
-
-// Set server version to be the package version
-const serverVersion = await getMcpPackageVersion();
+// Server version from core package
+const serverVersion = l10nMonsterVersion;
 
 /**
  * Setup tools on an MCP server instance
@@ -116,9 +103,9 @@ async function cleanupExpiredSessions() {
 /**
  * Creates MCP route handlers for use with the serve action extension mechanism.
  * Returns route definitions that can be registered via ServeAction.registerExtension.
- * 
- * @param {import('@l10nmonster/core').MonsterManager} mm - MonsterManager instance
- * @returns {Array<[string, string, Function]>} Array of [method, path, handler] route definitions
+ *
+ * @param {unknown} mm - MonsterManager instance.
+ * @returns {Array<[string, string, Function]>} Route definitions.
  */
 export function createMcpRoutes(mm) {
     // Handle POST requests for client-to-server communication

package/tools/mcpTool.js

@@ -57,14 +57,12 @@ export class McpProviderError extends McpToolError {
 
 /**
  * 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 {
 
     /**

package/tools/sourceQuery.js

@@ -32,7 +32,8 @@ You can write your own where conditions using SQL syntaxt against the following
             targetLang: z.string()
                 .describe('Target language code (e.g., "es-419")'),
             channel: z.string()
-                .describe('Channel ID to query sources from'),
+                .optional()
+                .describe('Channel ID to query sources from. If omitted, queries all channels.'),
             whereCondition: z.string()
                 .optional()
                 .describe('SQL WHERE condition against sources (default: "true" to match all)'),
@@ -40,12 +41,14 @@ You can write your own where conditions using SQL syntaxt against the following
     };
 
     static async execute(mm, args) {
-        const { sourceLang, targetLang, channel: channelId } = args;
+        const { sourceLang, targetLang, channel } = 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`, {
+        const channels = channel ? [channel] : availableChannels;
+
+        if (channel && availableChannels.length > 0 && !availableChannels.includes(channel)) {
+            throw new McpNotFoundError(`Channel "${channel}" not found`, {
                 hints: [`Available channels: ${availableChannels.join(', ')}`]
             });
         }
@@ -61,19 +64,22 @@ You can write your own where conditions using SQL syntaxt against the following
             });
         }
 
-        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
-            });
+        const tus = [];
+        for (const channelId of channels) {
+            try {
+                const channelTus = await tm.querySource(channelId, whereCondition);
+                tus.push(...channelTus);
+            } 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 {

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": [
+    "*.js",
+    "**/*.js"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/node_modules",
+    "test/**",
+    "tests/**",
+    "**/*.test.js",
+    "**/*.spec.js",
+    "dist/**",
+    "ui/**",
+    "types/**"
+  ]
+}

package/tests/integration.test.js

@@ -1,215 +0,0 @@
-import { describe, it, beforeEach } from 'node:test';
-import assert from 'node:assert';
-import { registerTool, McpTool, McpInputError } from '../index.js';
-import { registry } from '../tools/registry.js';
-import { z } from 'zod';
-
-// Create a custom tool for testing
-class CustomTestTool extends McpTool {
-    static metadata = {
-        name: 'custom_test_tool',
-        description: 'A custom tool for integration testing',
-        inputSchema: z.object({
-            message: z.string().describe('A test message')
-        })
-    };
-
-    static async execute(mm, args) {
-        return {
-            tool: 'custom_test_tool',
-            message: args.message,
-            timestamp: new Date().toISOString()
-        };
-    }
-}
-
-// Create a tool that overrides a built-in tool name
-class OverrideStatusTool extends McpTool {
-    static metadata = {
-        name: 'status',
-        description: 'Custom status tool override',
-        inputSchema: z.object({})
-    };
-
-    static async execute() {
-        return { custom: true, overridden: true };
-    }
-}
-
-describe('MCP Integration Tests', () => {
-    beforeEach(() => {
-        registry.clear();
-    });
-
-    it('should allow registering and using custom tools', async () => {
-        // Register the custom tool
-        registerTool(CustomTestTool);
-        
-        // Verify it's registered
-        assert.strictEqual(registry.hasTool('custom_test_tool'), true);
-        
-        // Get the tool and create a handler
-        const ToolClass = registry.getTool('custom_test_tool');
-        const handler = ToolClass.handler({});
-        
-        // Execute the handler
-        const result = await handler({ message: 'Hello from custom tool' });
-        
-        // Verify the result
-        assert.ok(result.content);
-        assert.strictEqual(result.content[0].type, 'text');
-        const data = JSON.parse(result.content[0].text);
-        assert.strictEqual(data.tool, 'custom_test_tool');
-        assert.strictEqual(data.message, 'Hello from custom tool');
-    });
-
-    it('should allow overriding built-in tools', () => {
-        // Register an override tool
-        registerTool(OverrideStatusTool);
-        
-        // Verify it's registered with the same name
-        assert.strictEqual(registry.hasTool('status'), true);
-        
-        // Get the tool and verify it's the override
-        const ToolClass = registry.getTool('status');
-        assert.strictEqual(ToolClass.metadata.description, 'Custom status tool override');
-    });
-
-    it('should handle tool execution errors gracefully', async () => {
-        class ErrorTool extends McpTool {
-            static metadata = {
-                name: 'error_tool',
-                description: 'Tool that throws errors',
-                inputSchema: z.object({
-                    shouldError: z.boolean()
-                })
-            };
-
-            static async execute(mm, args) {
-                if (args.shouldError) {
-                    throw new McpInputError('Test error', {
-                        hints: ['Try setting shouldError to false']
-                    });
-                }
-                return { success: true };
-            }
-        }
-
-        registerTool(ErrorTool);
-        
-        const ToolClass = registry.getTool('error_tool');
-        const handler = ToolClass.handler({});
-        
-        // Execute with error
-        const errorResult = await handler({ shouldError: true });
-        
-        // Verify error response
-        assert.strictEqual(errorResult.isError, true);
-        assert.ok(errorResult.content);
-        assert.ok(errorResult.content[0].text.includes('Test error'));
-        
-        // Execute without error
-        const successResult = await handler({ shouldError: false });
-        
-        // Verify success response
-        assert.strictEqual(successResult.isError, undefined);
-        const data = JSON.parse(successResult.content[0].text);
-        assert.strictEqual(data.success, true);
-    });
-
-    it('should validate input schemas', async () => {
-        class StrictTool extends McpTool {
-            static metadata = {
-                name: 'strict_tool',
-                description: 'Tool with strict validation',
-                inputSchema: z.object({
-                    required: z.string().min(1),
-                    optional: z.number().optional()
-                })
-            };
-
-            static async execute(mm, args) {
-                return args;
-            }
-        }
-
-        registerTool(StrictTool);
-        
-        const ToolClass = registry.getTool('strict_tool');
-        const handler = ToolClass.handler({});
-        
-        // Test with missing required field
-        const invalidResult = await handler({});
-        assert.strictEqual(invalidResult.isError, true);
-        
-        // Test with valid input
-        const validResult = await handler({ required: 'test' });
-        assert.strictEqual(validResult.isError, undefined);
-        const data = JSON.parse(validResult.content[0].text);
-        assert.strictEqual(data.required, 'test');
-    });
-
-    it('should support multiple tool registrations via function', () => {
-        class Tool1 extends McpTool {
-            static metadata = {
-                name: 'tool_1',
-                description: 'First tool',
-                inputSchema: z.object({})
-            };
-            static async execute() { return { id: 1 }; }
-        }
-
-        class Tool2 extends McpTool {
-            static metadata = {
-                name: 'tool_2',
-                description: 'Second tool',
-                inputSchema: z.object({})
-            };
-            static async execute() { return { id: 2 }; }
-        }
-
-        class Tool3 extends McpTool {
-            static metadata = {
-                name: 'tool_3',
-                description: 'Third tool',
-                inputSchema: z.object({})
-            };
-            static async execute() { return { id: 3 }; }
-        }
-
-        // Register tools individually
-        registerTool(Tool1);
-        registerTool(Tool2);
-        registerTool(Tool3);
-        
-        // Verify all are registered
-        assert.strictEqual(registry.getAllTools().length, 3);
-        assert.strictEqual(registry.hasTool('tool_1'), true);
-        assert.strictEqual(registry.hasTool('tool_2'), true);
-        assert.strictEqual(registry.hasTool('tool_3'), true);
-    });
-
-    it('should maintain tool isolation between registrations', () => {
-        class IsolatedTool extends McpTool {
-            static metadata = {
-                name: 'isolated',
-                description: 'Isolated tool',
-                inputSchema: z.object({})
-            };
-            static async execute() { return { isolated: true }; }
-        }
-
-        // Register tool
-        registerTool(IsolatedTool);
-        assert.strictEqual(registry.getAllTools().length, 1);
-        
-        // Clear registry
-        registry.clear();
-        assert.strictEqual(registry.getAllTools().length, 0);
-        
-        // Register again
-        registerTool(IsolatedTool);
-        assert.strictEqual(registry.getAllTools().length, 1);
-    });
-});
-