@l10nmonster/mcp 3.0.0-alpha.16

package/tools/status.js

@@ -0,0 +1,665 @@
+import { z } from 'zod';
+import { McpTool, McpNotFoundError } from './mcpTool.js';
+
+/**
+ * Create a language pair key in the format "sourceLang→targetLang"
+ * @param {string} sourceLang Source language code
+ * @param {string} targetLang Target language code
+ * @returns {string} Formatted language pair key
+ */
+function makeLangPairKey(sourceLang, targetLang) {
+    return `${sourceLang}→${targetLang}`;
+}
+
+/**
+ * Get channel statistics and warm caches.
+ * @param {*} mm MonsterManager instance
+ * @param {Object} filters Filter object with optional channel property
+ * @returns {Promise<{channelStats: Object, channelIds: string[]}>}
+ */
+async function getChannelStats(mm, filters) {
+    const channelIds = filters.channel ?
+        mm.rm.channelIds.filter(id => id === filters.channel) :
+        mm.rm.channelIds;
+    
+    if (filters.channel && channelIds.length === 0) {
+        throw new McpNotFoundError(`Channel "${filters.channel}" not found`, {
+            hints: [`Available channels: ${mm.rm.channelIds.join(', ')}`]
+        });
+    }
+    
+    // Warm caches by calling methods that trigger initialization
+    const channelStats = {};
+    for (const channelId of channelIds) {
+        // This call warms the cache
+        channelStats[channelId] = await mm.rm.getActiveContentStats(channelId);
+    }
+    
+    return { channelStats, channelIds };
+}
+
+/**
+ * Get desired language pairs from channels.
+ * @param {*} mm MonsterManager instance
+ * @param {string[]} channelIds List of channel IDs to process
+ * @param {Object} filters Filter object with optional sourceLang and targetLang properties
+ * @returns {Promise<{desiredPairs: Object}>}
+ */
+async function getDesiredLangPairs(mm, channelIds, filters) {
+    const desiredPairs = {};
+    const allLangPairs = new Set();
+    
+    for (const channelId of channelIds) {
+        const channelLangPairs = await mm.rm.getDesiredLangPairs(channelId);
+        for (const [sourceLang, targetLang] of channelLangPairs) {
+            // Apply language filters
+            if (filters.sourceLang && sourceLang !== filters.sourceLang) continue;
+            if (filters.targetLang && targetLang !== filters.targetLang) continue;
+            
+            const pairKey = makeLangPairKey(sourceLang, targetLang);
+            if (!allLangPairs.has(pairKey)) {
+                allLangPairs.add(pairKey);
+                desiredPairs[sourceLang] ??= [];
+                desiredPairs[sourceLang].push(targetLang);
+            }
+        }
+    }
+    
+    return { desiredPairs };
+}
+
+/**
+ * Get available translation providers with their status.
+ * @param {*} mm MonsterManager instance
+ * @param {Object} filters Filter object with optional provider property
+ * @returns {Promise<Array>} List of provider objects
+ */
+async function getAvailableProviders(mm, filters) {
+    const providers = [];
+    for (const provider of mm.dispatcher.providers) {
+        // Apply provider filter
+        if (filters.provider && provider.id !== filters.provider) continue;
+        
+        try {
+            const info = await provider.info();
+            providers.push({
+                id: info.id,
+                type: info.type,
+                quality: info.quality ?? 'dynamic',
+                costPerWord: info.costPerWord ?? 0,
+                costPerMChar: info.costPerMChar ?? 0,
+                supportedPairs: info.supportedPairs ?? 'any',
+                available: true
+            });
+        } catch (error) {
+            providers.push({
+                id: provider.id,
+                available: false,
+                error: error.message
+            });
+        }
+    }
+    
+    if (filters.provider && providers.length === 0) {
+        throw new McpNotFoundError(`Provider "${filters.provider}" not found`, {
+            hints: [`Available providers: ${mm.dispatcher.providers.map(p => p.id).join(', ')}`]
+        });
+    }
+    
+    return providers;
+}
+
+/**
+ * Get supported language pairs from providers.
+ * @param {Array} providers List of provider objects
+ * @param {Object} filters Filter object with optional sourceLang and targetLang properties
+ * @returns {Object} Supported language pairs by source language
+ */
+function getSupportedLangPairs(providers, filters) {
+    const supportedPairs = {};
+    const allSupportedPairs = new Set();
+    
+    if (!Array.isArray(providers)) {
+        return supportedPairs;
+    }
+    
+    for (const provider of providers) {
+        if (!provider.available || !provider.supportedPairs) continue;
+        
+        // Handle different formats of supportedPairs
+        if (provider.supportedPairs === 'any') {
+            // Provider supports any language pair, we can't enumerate them
+            continue;
+        }
+        
+        if (Array.isArray(provider.supportedPairs)) {
+            // Format: [["en", "es"], ["en", "fr"], ...]
+            for (const [sourceLang, targetLang] of provider.supportedPairs) {
+                // Apply language filters
+                if (filters.sourceLang && sourceLang !== filters.sourceLang) continue;
+                if (filters.targetLang && targetLang !== filters.targetLang) continue;
+                
+                const pairKey = makeLangPairKey(sourceLang, targetLang);
+                if (!allSupportedPairs.has(pairKey)) {
+                    allSupportedPairs.add(pairKey);
+                    supportedPairs[sourceLang] ??= [];
+                    if (!supportedPairs[sourceLang].includes(targetLang)) {
+                        supportedPairs[sourceLang].push(targetLang);
+                    }
+                }
+            }
+        }
+    }
+    
+    return supportedPairs;
+}
+
+/**
+ * Get translation memory statistics for available language pairs.
+ * @param {*} mm MonsterManager instance
+ * @param {Object} filters Filter object with optional provider, sourceLang, and targetLang properties
+ * @returns {Promise<{tmStats: Object, availableLangPairs: Array}>}
+ */
+async function getTranslationMemoryStats(mm, filters) {
+    const tmStats = {};
+    const allAvailableLangPairs = await mm.tmm.getAvailableLangPairs();
+    
+    // Filter language pairs
+    const availableLangPairs = allAvailableLangPairs.filter(([sourceLang, targetLang]) => {
+        if (filters.sourceLang && sourceLang !== filters.sourceLang) return false;
+        if (filters.targetLang && targetLang !== filters.targetLang) return false;
+        return true;
+    }).sort();
+    
+    for (const [sourceLang, targetLang] of availableLangPairs) {
+        const tm = mm.tmm.getTM(sourceLang, targetLang);
+        const stats = await tm.getStats();
+        const pairKey = makeLangPairKey(sourceLang, targetLang);
+        
+        // Apply provider filter to TM stats
+        const filteredStats = filters.provider ?
+            stats.filter(s => s.translationProvider === filters.provider) :
+            stats;
+        
+        tmStats[pairKey] = filteredStats.map(s => ({
+            translationProvider: s.translationProvider,
+            status: s.status,
+            jobCount: s.jobCount,
+            tuCount: s.tuCount,
+            redundancy: s.distinctGuids > 0 ? (s.tuCount / s.distinctGuids - 1) : 0
+        }));
+    }
+    
+    return { tmStats, availableLangPairs };
+}
+
+/**
+ * Get translation status filtered by channel and language.
+ * @param {*} mm MonsterManager instance
+ * @param {Object} filters Filter object with optional channel, sourceLang, and targetLang properties
+ * @returns {Promise<{translationStatus: Object}>}
+ */
+async function getTranslationStatus(mm, filters) {
+    // Structure: channelId -> sourceLang -> targetLang -> prj -> { details, pairSummary, pairSummaryByStatus }
+    const translationStatusRaw = await mm.getTranslationStatus();
+    
+    // Transform to sourceLang -> targetLang -> channelId -> prj structure for easier processing
+    // Apply filters during transformation
+    const translationStatus = {};
+    for (const [channelId, channelData] of Object.entries(translationStatusRaw)) {
+        // Apply channel filter
+        if (filters.channel && channelId !== filters.channel) continue;
+        
+        for (const [sourceLang, sourceData] of Object.entries(channelData)) {
+            // Apply source language filter
+            if (filters.sourceLang && sourceLang !== filters.sourceLang) continue;
+            
+            translationStatus[sourceLang] ??= {};
+            for (const [targetLang, targetData] of Object.entries(sourceData)) {
+                // Apply target language filter
+                if (filters.targetLang && targetLang !== filters.targetLang) continue;
+                
+                translationStatus[sourceLang][targetLang] ??= {};
+                translationStatus[sourceLang][targetLang][channelId] = targetData;
+            }
+        }
+    }
+    
+    return { translationStatus };
+}
+
+/**
+ * Compute coverage metrics from translation status.
+ * @param {Object} translationStatus Filtered translation status structure
+ * @returns {Object} Coverage metrics including overall and by-pair breakdowns
+ */
+function computeCoverage(translationStatus) {
+    let totalSegments = 0;
+    let translatedSegments = 0;
+    let untranslatedSegments = 0;
+    let inFlightSegments = 0;
+    let lowQualitySegments = 0;
+    
+    const coverageByPair = {};
+    
+    for (const [sourceLang, sourceStatus] of Object.entries(translationStatus)) {
+        for (const [targetLang, channelStatus] of Object.entries(sourceStatus)) {
+            let pairSegments = 0;
+            let pairTranslated = 0;
+            let pairUntranslated = 0;
+            let pairInFlight = 0;
+            let pairLowQuality = 0;
+            
+            for (const projectStatus of Object.values(channelStatus)) {
+                for (const { pairSummary, pairSummaryByStatus } of Object.values(projectStatus)) {
+                    pairSegments += pairSummary.segs;
+                    pairTranslated += pairSummaryByStatus.translated || 0;
+                    pairUntranslated += pairSummaryByStatus.untranslated || 0;
+                    pairInFlight += pairSummaryByStatus['in flight'] || 0;
+                    pairLowQuality += pairSummaryByStatus['low quality'] || 0;
+                }
+            }
+            
+            totalSegments += pairSegments;
+            translatedSegments += pairTranslated;
+            untranslatedSegments += pairUntranslated;
+            inFlightSegments += pairInFlight;
+            lowQualitySegments += pairLowQuality;
+            
+            const coverage = pairSegments > 0 ? pairTranslated / pairSegments : 0;
+            const pairKey = makeLangPairKey(sourceLang, targetLang);
+            coverageByPair[pairKey] = {
+                total: pairSegments,
+                translated: pairTranslated,
+                untranslated: pairUntranslated,
+                inFlight: pairInFlight,
+                lowQuality: pairLowQuality,
+                coverage
+            };
+        }
+    }
+    
+    const overallCoverage = totalSegments > 0 ? translatedSegments / totalSegments : 0;
+    
+    return {
+        overall: {
+            total: totalSegments,
+            translated: translatedSegments,
+            untranslated: untranslatedSegments,
+            inFlight: inFlightSegments,
+            lowQuality: lowQualitySegments,
+            coverage: overallCoverage
+        },
+        byPair: coverageByPair,
+    };
+}
+
+/**
+ * Get job summaries including pending and recent jobs.
+ * @param {*} mm MonsterManager instance
+ * @param {Object} filters Filter object with optional provider property
+ * @param {Array} availableLangPairs List of [sourceLang, targetLang] pairs
+ * @returns {Promise<{pendingJobs: Array, recentJobs: Array, jobCountsByPair: Object}>}
+ */
+async function getJobSummaries(mm, filters, availableLangPairs) {
+    const pendingJobs = [];
+    const recentJobs = [];
+    const jobCountsByPair = {};
+    
+    for (const [sourceLang, targetLang] of availableLangPairs) {
+        const allJobs = await mm.tmm.getJobTOCByLangPair(sourceLang, targetLang);
+        
+        // Apply provider filter to jobs
+        const filteredJobs = filters.provider ?
+            allJobs.filter(job => job.translationProvider === filters.provider) :
+            allJobs;
+        
+        const unfinished = filteredJobs.filter(job => job.status !== 'done');
+        const recent = filteredJobs
+            .filter(job => {
+                const updatedAt = new Date(job.updatedAt);
+                const weekAgo = new Date();
+                weekAgo.setDate(weekAgo.getDate() - 7);
+                return updatedAt >= weekAgo;
+            })
+            .slice(0, 10);
+        
+        const pairKey = makeLangPairKey(sourceLang, targetLang);
+        jobCountsByPair[pairKey] = {
+            total: filteredJobs.length,
+            unfinished: unfinished.length,
+            recent: recent.length
+        };
+        
+        if (unfinished.length > 0) {
+            pendingJobs.push(...unfinished.map(job => ({
+                pair: pairKey,
+                jobGuid: job.jobGuid,
+                status: job.status,
+                translationProvider: job.translationProvider,
+                updatedAt: job.updatedAt
+            })));
+        }
+        
+        if (recent.length > 0) {
+            recentJobs.push(...recent.map(job => ({
+                pair: pairKey,
+                jobGuid: job.jobGuid,
+                status: job.status,
+                translationProvider: job.translationProvider,
+                updatedAt: job.updatedAt
+            })));
+        }
+    }
+    
+    return { pendingJobs, recentJobs, jobCountsByPair };
+}
+
+function createChannelsMap(channelStats, withDetails) {
+    const channelsMap = {};
+    for (const [channelId, stats] of Object.entries(channelStats)) {
+        channelsMap[channelId] = stats.map(s => ({
+            project: s.prj ?? 'default',
+            sourceLang: s.sourceLang,
+            targetLangs: s.targetLangs || [],
+            segmentCount: s.segmentCount,
+            lastModified: s.lastModified,
+            ...(withDetails && { resourceCount: s.resCount })
+        }));
+    }
+    return channelsMap;
+}
+
+function createLanguagePairsMap(desiredPairs, supportedPairs) {
+    const result = {};
+    
+    if (Object.keys(desiredPairs).length > 0) {
+        const desiredMap = {};
+        for (const [sourceLang, targetLangs] of Object.entries(desiredPairs)) {
+            desiredMap[sourceLang] = targetLangs;
+        }
+        result.desired = desiredMap;
+    }
+    
+    if (Object.keys(supportedPairs).length > 0) {
+        const supportedMap = {};
+        for (const [sourceLang, targetLangs] of Object.entries(supportedPairs)) {
+            supportedMap[sourceLang] = targetLangs;
+        }
+        result.supported = supportedMap;
+    }
+    
+    return result;
+}
+
+function createProvidersMap(providers, withDetails) {
+    const providersMap = {};
+    for (const p of providers) {
+        providersMap[p.id] = {
+            type: p.type,
+            available: p.available,
+            supportedPairs: p.supportedPairs,
+            ...(withDetails && {
+                quality: p.quality,
+                costPerWord: p.costPerWord,
+                costPerMChar: p.costPerMChar
+            }),
+            ...(p.error && { error: p.error })
+        };
+    }
+    return providersMap;
+}
+
+function createTranslationMemoryMap(tmStats, withDetails) {
+    const translationMemoryMap = {};
+    for (const [pairKey, stats] of Object.entries(tmStats)) {
+        const [sourceLang, targetLang] = pairKey.split('→');
+        const langPairKey = makeLangPairKey(sourceLang, targetLang);
+        
+        if (withDetails) {
+            const providerMap = {};
+            for (const s of stats) {
+                providerMap[s.translationProvider] = {
+                    translationUnitCount: s.tuCount,
+                    status: s.status,
+                    jobCount: s.jobCount,
+                    redundancy: s.redundancy
+                };
+            }
+            translationMemoryMap[langPairKey] = providerMap;
+        } else {
+            const totalUnits = stats.reduce((sum, s) => sum + s.tuCount, 0);
+            translationMemoryMap[langPairKey] = totalUnits;
+        }
+    }
+    return translationMemoryMap;
+}
+
+function createCoverageData(coverage, withDetails) {
+    const coverageMap = {};
+    for (const [pairKey, pairCoverage] of Object.entries(coverage.byPair)) {
+        const [sourceLang, targetLang] = pairKey.split('→');
+        const langPairKey = makeLangPairKey(sourceLang, targetLang);
+        coverageMap[langPairKey] = {
+            totalSegments: pairCoverage.total,
+            translated: pairCoverage.translated,
+            untranslated: pairCoverage.untranslated,
+            coveragePercentage: (pairCoverage.coverage * 100).toFixed(2),
+            ...(withDetails && {
+                inFlight: pairCoverage.inFlight,
+                lowQuality: pairCoverage.lowQuality
+            })
+        };
+    }
+    
+    return {
+        map: coverageMap,
+        summary: withDetails ? coverage.overall : undefined
+    };
+}
+
+function createJobsData(jobSummaries) {
+    const jobsMap = {};
+    const allJobs = jobSummaries.pendingJobs.concat(jobSummaries.recentJobs);
+    for (const job of allJobs) {
+        const [sourceLang, targetLang] = job.pair.split('→');
+        const langPairKey = makeLangPairKey(sourceLang, targetLang);
+        if (!jobsMap[langPairKey]) {
+            jobsMap[langPairKey] = [];
+        }
+        jobsMap[langPairKey].push({
+            jobGuid: job.jobGuid,
+            status: job.status,
+            translationProvider: job.translationProvider,
+            updatedAt: job.updatedAt
+        });
+    }
+    
+    return {
+        jobsMap,
+        counts: jobSummaries.jobCountsByPair
+    };
+}
+
+function applyOptionalSections(result, { requestedSections, providers, coverage, jobSummaries, withDetails, channelStats, mm }) {
+    if (requestedSections.has('providers') && Array.isArray(providers)) {
+        result.providers = createProvidersMap(providers, withDetails);
+    }
+    
+    if (requestedSections.has('coverage') && coverage) {
+        const coverageData = createCoverageData(coverage, withDetails);
+        result.coverage = coverageData.map;
+        if (coverageData.summary) {
+            result.coverageSummary = coverageData.summary;
+        }
+    }
+    
+    if (requestedSections.has('jobs') && jobSummaries) {
+        const jobsData = createJobsData(jobSummaries);
+        result.jobs = jobsData.jobsMap;
+        if (jobsData.counts) {
+            result.jobCounts = jobsData.counts;
+        }
+    }
+    
+    if (withDetails) {
+        result.details = {
+            channelCount: Object.keys(channelStats).length,
+            autoSnap: mm.rm.autoSnap
+        };
+    }
+}
+
+/**
+ * Build the final response object.
+ * @param {Object} params Parameters object
+ * @param {Object} params.channelStats Channel statistics
+ * @param {Object} params.desiredPairs Desired language pairs by source language
+ * @param {Object} params.supportedPairs Supported language pairs by source language from providers
+ * @param {Array} params.providers List of providers
+ * @param {Object} params.tmStats Translation memory statistics
+ * @param {Object} params.coverage Coverage metrics
+ * @param {Object} params.jobSummaries Job summaries
+ * @param {boolean} params.withDetails Whether to include detailed information
+ * @param {Set<string>} params.includeSet Requested optional sections
+ * @param {*} params.mm MonsterManager instance
+ * @returns {Object} Complete response object
+ */
+function buildResponse({ channelStats, desiredPairs, supportedPairs, providers, tmStats, coverage, jobSummaries, withDetails, includeSet, mm }) {
+    const requestedSections = includeSet instanceof Set ? includeSet : new Set(includeSet ?? []);
+    
+    const result = {
+        timestamp: new Date().toISOString()
+    };
+    
+    // Add base sections if requested
+    if (requestedSections.has('channels')) {
+        result.channels = createChannelsMap(channelStats, withDetails);
+    }
+    
+    if (requestedSections.has('languagePairs')) {
+        result.languagePairs = createLanguagePairsMap(desiredPairs, supportedPairs);
+    }
+    
+    if (requestedSections.has('translationMemory')) {
+        result.translationMemory = createTranslationMemoryMap(tmStats, withDetails);
+    }
+    
+    // Add optional sections
+    applyOptionalSections(result, {
+        requestedSections,
+        providers,
+        coverage,
+        jobSummaries,
+        withDetails,
+        channelStats,
+        mm
+    });
+    
+    return result;
+}
+
+
+/**
+ * MCP tool for assembling the status of the localization system.
+ * 
+ * This tool chains together functionality from monster, source_list (status mode),
+ * and ops_jobs to provide a comprehensive overview including:
+ * - Channel statistics
+ * - Language pairs
+ * - Translation memory and coverage
+ *   - Provider availability
+ * - Job summaries
+ * 
+ * Supports optional filtering by:
+ * - channel: Filter to specific channel ID (default: all channels)
+ * - provider: Filter to specific translation provider (default: all providers)
+ * - sourceLang: Filter to specific source language (default: all languages)
+ * - targetLang: Filter to specific target language (default: all languages)
+ */
+export class StatusTool extends McpTool {
+    static metadata = {
+        name: 'status',
+        description: `Assemble the status of the l10nmonster translation system as a whole or specific parts of it.
+The result may include any of these sections: translation channels, projects, jobs, memory, coverage, providers and supported language pairs. 
+The result can be further refined by filtering by channel, provider, source language, and target language.
+`,
+        inputSchema: z.object({
+            detailLevel: z.enum(['summary', 'detailed'])
+                .default('summary')
+                .describe('Controls response verbosity: "summary" omits secondary fields, "detailed" includes them'),
+            include: z.array(z.enum(['channels', 'providers', 'languagePairs', 'translationMemory', 'coverage', 'jobs']))
+                .default(['channels', 'providers', 'languagePairs'])
+                .describe('Optional sections to include in the response. Defaults to ["channels", "providers", "languagePairs"]'),
+            channel: z.string()
+                .optional()
+                .describe('Optional channel ID to filter results. Defaults to all channels.'),
+            provider: z.string()
+                .optional()
+                .describe('Optional provider ID to filter results. Defaults to all providers.'),
+            sourceLang: z.string()
+                .optional()
+                .describe('Optional source language to filter results. Defaults to all source languages.'),
+            targetLang: z.string()
+                .optional()
+                .describe('Optional target language to filter results. Defaults to all target languages.'),
+        })
+    };
+
+    static async execute(mm, args) {
+        const filters = {
+            channel: args.channel,
+            provider: args.provider,
+            sourceLang: args.sourceLang,
+            targetLang: args.targetLang
+        };
+        const withDetails = args.detailLevel === 'detailed';
+        const includeSet = new Set(args.include);
+        
+        // Gather all data using helper functions
+        const { channelStats, channelIds } = await getChannelStats(mm, filters);
+        
+        // Get providers if needed for languagePairs:supported or providers section
+        const needsProviders = includeSet.has('providers') || includeSet.has('languagePairs');
+        const providers = needsProviders ?
+            await getAvailableProviders(mm, filters) :
+            null;
+        
+        const desiredPairs = includeSet.has('languagePairs') ?
+            (await getDesiredLangPairs(mm, channelIds, filters)).desiredPairs :
+            {};
+        
+        const supportedPairs = includeSet.has('languagePairs') ?
+            getSupportedLangPairs(providers, filters) :
+            {};
+        
+        // Get TM stats if translationMemory, coverage, or jobs is requested
+        const needsTmStats = includeSet.has('translationMemory') || includeSet.has('coverage') || includeSet.has('jobs');
+        const { tmStats, availableLangPairs } = needsTmStats ?
+            await getTranslationMemoryStats(mm, filters) :
+            { tmStats: {}, availableLangPairs: [] };
+        
+        const coverage = includeSet.has('coverage') ?
+            computeCoverage((await getTranslationStatus(mm, filters)).translationStatus) :
+            null;
+        
+        const jobSummaries = includeSet.has('jobs') ?
+            await getJobSummaries(mm, filters, availableLangPairs) :
+            null;
+        
+        // Build and return response
+        return buildResponse({
+            channelStats,
+            desiredPairs,
+            supportedPairs,
+            providers,
+            tmStats,
+            coverage,
+            jobSummaries,
+            withDetails,
+            includeSet,
+            mm
+        });
+    }
+}
+