@l10nmonster/mcp 3.0.0-alpha.16

package/README.md

@@ -0,0 +1,261 @@
+# L10n Monster MCP Server
+
+Model Context Protocol (MCP) server for L10n Monster, exposing translation management functionality to Claude Code and other MCP clients.
+The server exposed an standards-compliant Streamable HTTP transport with per-request isolation.
+
+## Usage
+
+Register MCP as an extension to be served and then start an l10n monster server as usual.
+
+
+### Example
+
+`l10nmonster.config.mjs`:
+```javascript
+import config from '@l10nmonster/core';
+import serve from '@l10nmonster/server';
+import { createMcpRoutes } from '@l10nmonster/mcp';
+serve.registerExtension('mcp', createMcpRoutes);
+
+export default config.l10nMonster(import.meta.dirname).action(serve)
+```
+
+With above config, you can start the l10n server via:
+```shell
+$ npx l10n serve
+```
+
+The server then exposes an mcp at `http://localhost:9000/api/ext/mcp` which can be leveraged by any LLM agent.
+
+
+## Available Tools
+
+- `status` - Get status of various l10nmonster subsystems including channels, projects, providers, language pairs, jobs, translation memory etc. The caller agent controls which sub-systems to include and the level of details to allow for more efficient use of the context.
+- `source_query` - Query source content and translation memory.
+- `translate` - Translate segments using configured providers.
+
+## Extending MCP with Custom Tools
+
+The MCP server supports a registration-based extensibility pattern, allowing external packages to add custom tools without modifying the core MCP package. This mirrors the `ServeAction.registerExtension` pattern used by the L10n Monster server.
+
+### Creating a Custom Tool
+
+Custom tools extend the `McpTool` base class and follow the same conventions as built-in tools:
+
+```javascript
+import { McpTool, McpInputError } from '@l10nmonster/mcp';
+import { z } from 'zod';
+
+export class MyCustomTool extends McpTool {
+    static metadata = {
+        name: 'my_custom_tool',
+        description: 'Does something custom with translation data',
+        inputSchema: z.object({
+            channelId: z.string().describe('Channel ID to process'),
+            option: z.string().optional().default('default').describe('Optional processing option')
+        })
+    };
+
+    static async execute(mm, args) {
+        // Access MonsterManager methods directly
+        const channel = mm.rm.getChannel(args.channelId);
+        
+        if (!channel) {
+            throw new McpInputError(`Channel "${args.channelId}" not found`, {
+                hints: [`Available channels: ${mm.rm.channelIds.join(', ')}`]
+            });
+        }
+
+        // Return structured data
+        return {
+            channelId: args.channelId,
+            result: 'processed',
+            option: args.option
+        };
+    }
+}
+```
+
+### Registering Custom Tools
+
+Register your custom tools in your `l10nmonster.config.mjs` before calling `serve.registerExtension`:
+
+```javascript
+import config from '@l10nmonster/core';
+import serve from '@l10nmonster/server';
+import { createMcpRoutes, registerTool } from '@l10nmonster/mcp';
+import { MyCustomTool } from './my-custom-tool.js';
+
+// Register custom MCP tools
+registerTool(MyCustomTool);
+
+// Register MCP routes with the server
+serve.registerExtension('mcp', createMcpRoutes);
+
+export default config.l10nMonster(import.meta.dirname)
+    .action(serve);
+```
+
+### Tool Registration in Helper Packages
+
+Helper packages can export their MCP tools for registration by consumers:
+
+```javascript
+// In @l10nmonster/helpers-custom/index.js
+export { MyCustomTool } from './mcpTools/MyCustomTool.js';
+
+// In l10nmonster.config.mjs
+import { registerTool } from '@l10nmonster/mcp';
+import { MyCustomTool } from '@l10nmonster/helpers-custom';
+
+registerTool(MyCustomTool);
+```
+
+### Tool Override
+
+Registered tools can override built-in tools by using the same tool name. This allows customization of default behavior:
+
+```javascript
+import { McpTool } from '@l10nmonster/mcp';
+import { z } from 'zod';
+
+// Override the built-in 'status' tool with custom implementation
+export class CustomStatusTool extends McpTool {
+    static metadata = {
+        name: 'status', // Same name as built-in tool
+        description: 'Custom status implementation',
+        inputSchema: z.object({
+            // Custom schema
+        })
+    };
+
+    static async execute(mm, args) {
+        // Custom implementation
+        return { custom: true };
+    }
+}
+
+registerTool(CustomStatusTool);
+```
+
+### Exported API
+
+The MCP package exports the following for extensibility:
+
+- **`registerTool(ToolClass)`** - Register a custom MCP tool
+- **`McpTool`** - Base class for creating tools
+- **Error types** for structured error handling:
+  - `McpToolError` - Base error with structured metadata
+  - `McpInputError` - Invalid input errors
+  - `McpNotFoundError` - Resource not found errors
+  - `McpProviderError` - Translation provider errors
+
+
+## Examples
+
+The `examples/` directory contains complete examples of custom MCP tools:
+
+- **`custom-tool-example.js`** - Demonstrates creating custom tools including:
+  - `ProjectStatsTool` - Get detailed statistics for a specific project
+  - `QualityInsightsTool` - Analyze translation quality distribution
+
+These examples show best practices for:
+- Extending the `McpTool` base class
+- Defining input schemas with Zod
+- Accessing MonsterManager APIs
+- Handling errors with structured error types
+- Returning well-formatted results
+
+## Development
+
+When developing, the best way to test the MCP server is by running it and using the inspector.
+
+```
+npx @modelcontextprotocol/inspector
+```
+
+
+## Creating New Tools
+
+All tools live under `/tools` directory. Each tool interface directly with MonsterManager, providing structured access to L10n Monster functionality through the Model Context Protocol. Unlike CLI actions, these tools return structured data optimized for programmatic consumption rather than console output.
+
+
+All MCP tools inherit from the `McpTool` base class, which handles schema validation with Zod, automatic error formatting, and MCP response serialization. Tools are automatically discovered and registered at server startup by scanning exports from `tools/index.js`.
+
+New tools should focus on a single responsibility while remaining composable with existing tools. Design them to be idempotent where possible, especially for query operations that shouldn't modify state.
+
+Use consistent naming conventions: prefer verb-noun patterns like `source_query` or `translate_segments`, and standardize parameter names such as `channelId`, `sourceLang`, and `targetLang`. Write clear descriptions for both the tool and its parameters, as these directly influence how AI agents discover and use your tools. Include example values in parameter descriptions when they help clarify expected formats.
+
+Remember that tool description and schema descriptions serve different purposes and audiences. Descriptions help with tool selection and understanding, while schema descriptions guide proper usage. So
+   - Aim to have good sensible default for variables to make it easy out-of-the-box usage. Users should be able to get started without extensive configuration.
+   - In case of error emit  a helpful message to the caller with information to potentially recover. For example if a provided parameter is not valid in the error return a list of valid values so LLM can recover.
+   - Optional paramter should have their default explained.
+
+
+
+Additional reading:
+ - https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1382
+ - https://steipete.me/posts/2025/mcp-best-practices#tool--parameter-descriptions 
+
+
+
+### Schema Design
+
+Define input schemas using Zod with descriptive field documentation. Use `.describe()` to explain each parameter's purpose and format, and leverage Zod's validation features like `.min()`, `.max()`, and `.optional()` to enforce constraints and provide sensible defaults.
+
+```javascript
+inputSchema: z.object({
+    channelId: z.string().describe('Channel ID to fetch source TUs from'),
+    guids: z.array(z.string()).min(1).describe('Array of TU GUIDs to translate'),
+    whereCondition: z.string().optional().default('true').describe('SQL WHERE condition against sources')
+})
+```
+
+### Implementation
+
+Create a tool class that extends `McpTool` with static `metadata` and `execute` method:
+
+```javascript
+export class MyNewTool extends McpTool {
+    static metadata = {
+        name: 'my_new_tool',
+        description: 'Tool description for MCP discovery',
+        inputSchema: z.object({...})
+    };
+
+    static async execute(mm, args) {
+        // Call MonsterManager methods directly
+        // Return structured data - the base class handles MCP formatting
+        return { ... };
+    }
+}
+```
+
+Export the tool from `tools/index.js` to make it available for automatic registration:
+
+```javascript
+export { MyNewTool } from './MyNewTool.js';
+```
+
+### Output Guidelines
+
+Return structured objects rather than formatted strings, letting MCP clients handle presentation. Use arrays of objects for lists instead of concatenated strings, and include contextual metadata with results to help consumers understand what they're receiving.
+
+The base class automatically formats results for MCP compatibility, so focus on returning clean, structured data that represents your tool's output naturally.
+
+### Error Handling
+
+The base class provides structured error handling with specific error types (`McpInputError`, `McpNotFoundError`, `McpProviderError`) that include machine-readable codes, retry hints, and detailed context. Let errors bubble up naturally unless you need to add domain-specific context.
+
+When catching errors, use the structured error types to provide actionable information:
+
+```javascript
+try {
+    return await someOperation();
+} catch (error) {
+    throw new McpInputError(`Invalid channel: ${channelId}`, {
+        hints: ['Call translation_status to see available channels'],
+        cause: error
+    });
+}
+```

package/index.js

@@ -0,0 +1,15 @@
+// Main MCP server integration
+export { createMcpRoutes } from './server.js';
+
+// Tool registration for extensibility
+import { registry } from './tools/registry.js';
+export const registerTool = registry.registerTool.bind(registry);
+
+// Base classes and utilities for creating custom tools
+export { 
+    McpTool,
+    McpToolError,
+    McpInputError,
+    McpNotFoundError,
+    McpProviderError
+} from './tools/mcpTool.js';

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@l10nmonster/mcp",
+  "version": "3.0.0-alpha.16",
+  "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"
+}

package/server.js

@@ -0,0 +1,235 @@
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+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';
+
+// Session management for HTTP transport
+const sessions = new Map(); // sessionId -> { transport, lastActivity }
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+// Shared MCP server instance per MonsterManager
+// 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();
+
+/**
+ * Setup tools on an MCP server instance
+ * 
+ * Registers all MCP tools from the registry, including:
+ * 1. Built-in tools (auto-registered from ./tools/index.js)
+ * 2. External tools registered via registerTool()
+ */
+async function setupToolsOnServer(server, monsterManager) {
+    // Register built-in tools if not already registered
+    const builtInTools = Object.values(mcpTools).filter(ToolClass => (
+        ToolClass && 
+        typeof ToolClass === 'function' && 
+        typeof ToolClass.handler === 'function' && 
+        ToolClass.metadata));
+
+    for (const ToolClass of builtInTools) {
+        const toolName = ToolClass.metadata.name;
+        if (!registry.hasTool(toolName)) {
+            registry.registerTool(ToolClass);
+        }
+    }
+
+    // Register all tools from the registry with the MCP server
+    for (const ToolClass of registry.getAllTools()) {
+        const { name, description, inputSchema } = ToolClass.metadata;
+        const handler = ToolClass.handler(monsterManager);
+        
+        console.info(`Registering MCP tool: ${name}`);
+        await server.registerTool(
+            name,
+            {
+                title: name,
+                description,
+                inputSchema: inputSchema.shape,
+            },
+            handler,
+        );
+    }
+}
+
+/**
+ * Get or create a shared MCP server instance for a MonsterManager
+ */
+async function getOrCreateSharedServer(monsterManager) {
+    let server = serverInstances.get(monsterManager);
+    
+    if (!server) {
+        server = new McpServer({
+            name: 'l10nmonster-mcp',
+            version: serverVersion,
+        });
+        
+        await setupToolsOnServer(server, monsterManager);
+        serverInstances.set(monsterManager, server);
+        console.info('Created shared MCP server instance');
+    }
+    
+    return server;
+}
+
+/**
+ * Clean up expired sessions on-demand
+ */
+async function cleanupExpiredSessions() {
+    let cleaned = 0;
+    const now = Date.now();
+    for (const [sessionId, session] of sessions.entries()) {
+        if (now - session.lastActivity > SESSION_TIMEOUT_MS) {
+            try {
+                console.info(`Cleaning up expired session: ${sessionId}`);
+                await session.transport.close();
+            } catch (error) {
+                // Log error per session but continue cleaning other expired sessions
+                console.error(`Error cleaning up expired session ${sessionId}:`, error);
+            } finally {
+                sessions.delete(sessionId);
+                cleaned++;
+            }
+        }
+    }
+    return cleaned;
+}
+
+/**
+ * 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
+ */
+export function createMcpRoutes(mm) {
+    // Handle POST requests for client-to-server communication
+    const handlePost = async (req, res) => {
+        // Clean up expired sessions on each request
+        await cleanupExpiredSessions();
+        
+        try {
+            const sessionId = req.headers['mcp-session-id'];
+            let session;
+
+            if (sessionId && sessions.has(sessionId)) {
+                // Existing session - update activity timestamp
+                session = sessions.get(sessionId);
+                session.lastActivity = Date.now();
+            } else if (!sessionId && isInitializeRequest(req.body)) {
+                // New initialization request - create transport and connect shared server
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (newSessionId) => {
+                        sessions.set(newSessionId, {
+                            transport,
+                            lastActivity: Date.now(),
+                        });
+                    },
+                    // DNS rebinding protection is disabled by default for backwards compatibility.
+                    // For production use, consider enabling:
+                    // enableDnsRebindingProtection: true,
+                    // allowedHosts: ['127.0.0.1'],
+                });
+
+                transport.onclose = () => {
+                    if (transport.sessionId) {
+                        console.info(`Session closed: ${transport.sessionId}`);
+                        sessions.delete(transport.sessionId);
+                    }
+                };
+                
+                // Get or create shared MCP server and connect to new transport
+                const server = await getOrCreateSharedServer(mm);
+                await server.connect(transport);
+                console.info(`New MCP session initialized: ${transport.sessionId}`);
+                
+                session = { transport, lastActivity: Date.now() };
+            } else {
+                // Invalid request - no session ID and not an initialize request
+                return res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Bad Request: No valid session ID provided and not an initialize request',
+                    },
+                    id: null,
+                });
+            }
+
+            // Handle the request through the transport
+            await session.transport.handleRequest(req, res, req.body);
+        } catch (error) {
+            console.error('Error handling MCP POST request:', error);
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                    data: { detail: error.message },
+                },
+                id: null,
+            });
+        }
+    };
+
+    // Handle GET and DELETE requests for existing sessions
+    const handleSessionRequest = async (req, res) => {
+        // Clean up expired sessions on each request
+        await cleanupExpiredSessions();
+        
+        try {
+            const sessionId = req.headers['mcp-session-id'];
+            
+            if (!sessionId || !sessions.has(sessionId)) {
+                return res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Invalid or missing session ID',
+                    },
+                    id: null,
+                });
+            }
+
+            const session = sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            await session.transport.handleRequest(req, res);
+        } catch (error) {
+            console.error('Error handling MCP session request:', error);
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                    data: { detail: error.message },
+                },
+                id: null,
+            });
+        }
+    };
+
+    return [
+        ['post', '/', handlePost],
+        ['get', '/', handleSessionRequest],
+        ['delete', '/', handleSessionRequest],
+    ];
+}