@cleocode/mcp-server 0.86.0

package/dist/index.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * CLEO MCP Server Entry Point
+ *
+ * Exposes CLEO's 65 CLI commands and 280+ library functions through
+ * two gateway tools using CQRS pattern:
+ * - cleo_query: 45 read operations (never modifies state)
+ * - cleo_mutate: 53 write operations (validated, logged, atomic)
+ *
+ * Wires together:
+ * 1. Configuration loader
+ * 2. CLI executor wrapper
+ * 3. Domain router
+ * 4. Gateway tools (query + mutate)
+ * 5. MCP SDK server with stdio transport
+ *
+ * @task T2926
+ * @see MCP-SERVER-SPECIFICATION.md for complete API documentation
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './lib/config.js';
+import { DomainRouter } from './lib/router.js';
+import { createExecutor } from './lib/executor.js';
+import { registerQueryTool } from './gateways/query.js';
+import { registerMutateTool } from './gateways/mutate.js';
+import { QueryCache } from './lib/cache.js';
+import { BackgroundJobManager } from './lib/background-jobs.js';
+let serverState = null;
+/**
+ * Initialize and start MCP server
+ */
+async function main() {
+    try {
+        // Load configuration
+        console.error('[CLEO MCP] Loading configuration...');
+        const config = loadConfig();
+        // Log startup info (to stderr, not stdout which is used by MCP)
+        console.error('[CLEO MCP] Starting server...');
+        console.error(`[CLEO MCP] CLI path: ${config.cliPath}`);
+        console.error(`[CLEO MCP] Timeout: ${config.timeout}ms`);
+        console.error(`[CLEO MCP] Log level: ${config.logLevel}`);
+        console.error(`[CLEO MCP] Metrics: ${config.enableMetrics ? 'enabled' : 'disabled'}`);
+        console.error(`[CLEO MCP] Max retries: ${config.maxRetries}`);
+        // Create CLI executor
+        console.error('[CLEO MCP] Creating CLI executor...');
+        const executor = createExecutor(config.cliPath, config.timeout, config.maxRetries);
+        // Test CLI connection
+        console.error('[CLEO MCP] Testing CLI connection...');
+        const connected = await executor.testConnection();
+        if (!connected) {
+            throw new Error(`Failed to connect to CLEO CLI at ${config.cliPath}`);
+        }
+        console.error('[CLEO MCP] CLI connection successful');
+        // Get CLI version
+        const cliVersion = await executor.getVersion();
+        console.error(`[CLEO MCP] CLI version: ${cliVersion}`);
+        // Initialize domain router with executor and rate limiting config
+        console.error('[CLEO MCP] Initializing domain router...');
+        const router = new DomainRouter(executor, true, config.rateLimiting);
+        console.error('[CLEO MCP] Domain router initialized');
+        console.error(`[CLEO MCP] Rate limiting: ${config.rateLimiting.enabled ? 'enabled' : 'disabled'} (query: ${config.rateLimiting.query.maxRequests}/min, mutate: ${config.rateLimiting.mutate.maxRequests}/min, spawn: ${config.rateLimiting.spawn.maxRequests}/min)`);
+        console.error(`[CLEO MCP] Registered domains: ${router.getDomains().join(', ')}`);
+        // Initialize background job manager
+        const jobManager = new BackgroundJobManager({ maxJobs: 10, retentionMs: 3600000 });
+        console.error('[CLEO MCP] Background job manager initialized (max: 10, retention: 1h)');
+        // Wire job manager into system handler via router
+        const systemOps = router.getDomainOperations('system');
+        if (systemOps) {
+            // Access the system handler through the router to inject job manager
+            // The SystemHandler.setJobManager method allows post-construction injection
+            const systemHandler = router.handlers.get('system');
+            if (systemHandler && typeof systemHandler.setJobManager === 'function') {
+                systemHandler.setJobManager(jobManager);
+                console.error('[CLEO MCP] Background job manager wired to system handler');
+            }
+        }
+        // Initialize query cache
+        const cache = new QueryCache(config.queryCacheTtl, config.queryCache);
+        console.error(`[CLEO MCP] Query cache: ${config.queryCache ? 'enabled' : 'disabled'} (TTL: ${config.queryCacheTtl}ms)`);
+        // Create MCP server
+        const server = new Server({
+            name: 'cleo-server',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        // Register tools (ListTools handler)
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    registerQueryTool(),
+                    registerMutateTool(),
+                ],
+            };
+        });
+        // Handle tool calls (CallTool handler)
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            console.error(`[CLEO MCP] Tool call: ${name}`);
+            if (config.logLevel === 'debug') {
+                console.error(`[CLEO MCP] Arguments:`, JSON.stringify(args, null, 2));
+            }
+            try {
+                // Validate gateway name
+                if (name !== 'cleo_query' && name !== 'cleo_mutate') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    _meta: {
+                                        gateway: name,
+                                        version: '1.0.0',
+                                        timestamp: new Date().toISOString(),
+                                    },
+                                    success: false,
+                                    error: {
+                                        code: 'E_INVALID_GATEWAY',
+                                        exitCode: 2,
+                                        message: `Unknown gateway: ${name}. Use 'cleo_query' or 'cleo_mutate'.`,
+                                    },
+                                }),
+                            },
+                        ],
+                    };
+                }
+                // Validate required parameters
+                if (!args?.domain || !args?.operation) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    _meta: {
+                                        gateway: name,
+                                        version: '1.0.0',
+                                        timestamp: new Date().toISOString(),
+                                    },
+                                    success: false,
+                                    error: {
+                                        code: 'E_INVALID_INPUT',
+                                        exitCode: 2,
+                                        message: 'Missing required parameters: domain and operation',
+                                    },
+                                }),
+                            },
+                        ],
+                    };
+                }
+                // Build domain request
+                const domainRequest = {
+                    gateway: name,
+                    domain: args.domain,
+                    operation: args.operation,
+                    params: args.params,
+                };
+                // Check cache bypass flag
+                const bypassCache = !!args.params?.bypassCache;
+                // For query operations, check cache first
+                if (name === 'cleo_query' && !bypassCache) {
+                    const domain = args.domain;
+                    const operation = args.operation;
+                    const params = args.params;
+                    const cached = cache.get(domain, operation, params);
+                    if (cached !== undefined) {
+                        if (config.logLevel === 'debug') {
+                            console.error(`[CLEO MCP] Cache hit: ${domain}.${operation}`);
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify(cached, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                }
+                // Route to domain handler
+                const result = await router.routeOperation(domainRequest);
+                if (config.logLevel === 'debug') {
+                    console.error(`[CLEO MCP] Result:`, JSON.stringify(result, null, 2));
+                }
+                // Cache successful query results
+                if (name === 'cleo_query' && result.success && !bypassCache) {
+                    cache.set(args.domain, args.operation, args.params, result);
+                }
+                // Invalidate domain cache on mutate operations
+                if (name === 'cleo_mutate') {
+                    const invalidated = cache.invalidateDomain(args.domain);
+                    if (invalidated > 0 && config.logLevel === 'debug') {
+                        console.error(`[CLEO MCP] Cache invalidated ${invalidated} entries for domain: ${args.domain}`);
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                console.error(`[CLEO MCP] Error:`, error);
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                _meta: {
+                                    gateway: name,
+                                    version: '1.0.0',
+                                    timestamp: new Date().toISOString(),
+                                },
+                                success: false,
+                                error: {
+                                    code: 'E_INTERNAL_ERROR',
+                                    message: errorMessage,
+                                },
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        // Store server state for cleanup
+        serverState = {
+            router,
+            server,
+            cache,
+            jobManager,
+        };
+        // Create transport and connect
+        console.error('[CLEO MCP] Connecting to stdio transport...');
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('[CLEO MCP] Server started successfully');
+        console.error('[CLEO MCP] Ready for requests');
+    }
+    catch (error) {
+        console.error('[CLEO MCP] Failed to start server:', error);
+        process.exit(1);
+    }
+}
+/**
+ * Graceful shutdown handler
+ */
+async function shutdown(signal) {
+    console.error(`[CLEO MCP] Received ${signal}, shutting down...`);
+    if (serverState) {
+        try {
+            // Destroy background job manager
+            serverState.jobManager.destroy();
+            // Destroy cache
+            serverState.cache.destroy();
+            // Close server
+            await serverState.server.close();
+            console.error('[CLEO MCP] Server closed');
+        }
+        catch (error) {
+            console.error('[CLEO MCP] Error during shutdown:', error);
+        }
+    }
+    process.exit(0);
+}
+/**
+ * Error handler for uncaught exceptions
+ */
+function handleUncaughtError(error, type) {
+    console.error(`[CLEO MCP] ${type}:`, error);
+    // Attempt graceful shutdown
+    if (serverState) {
+        shutdown('ERROR').catch(() => {
+            process.exit(1);
+        });
+    }
+    else {
+        process.exit(1);
+    }
+}
+// Register signal handlers for graceful shutdown
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+// Register error handlers
+process.on('uncaughtException', (error) => handleUncaughtError(error, 'Uncaught Exception'));
+process.on('unhandledRejection', (reason) => handleUncaughtError(reason instanceof Error ? reason : new Error(String(reason)), 'Unhandled Rejection'));
+// Start server
+main().catch((error) => {
+    console.error('[CLEO MCP] Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/audit.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Audit Trail for MCP Server Mutations
+ *
+ * Logs all write operations to .cleo/audit-log.json for compliance
+ * and debugging purposes.
+ *
+ * @task T2920
+ * @task T2929
+ */
+/**
+ * Audit entry interface
+ */
+export interface AuditEntry {
+    timestamp: string;
+    sessionId: string | null;
+    domain: string;
+    operation: string;
+    params: Record<string, unknown>;
+    result: {
+        success: boolean;
+        exitCode: number;
+        duration: number;
+    };
+    metadata: {
+        taskId?: string;
+        userId?: string;
+        source: "mcp";
+        gateway?: 'cleo_mutate' | 'cleo_query';
+    };
+    error?: string;
+}
+/**
+ * Log mutation to audit trail
+ *
+ * Appends a single-line JSON entry to .cleo/audit-log.json
+ * Non-blocking - errors are logged but not thrown
+ * Automatically rotates log if size exceeds limit
+ *
+ * @param entry Audit entry to log
+ */
+export declare function logMutation(entry: AuditEntry): Promise<void>;
+/**
+ * Log error to audit trail
+ *
+ * Convenience function for logging errors with full context
+ *
+ * @param domain Domain where error occurred
+ * @param operation Operation that failed
+ * @param error Error object or message
+ * @param params Operation parameters
+ * @param exitCode Exit code (default: 1)
+ */
+export declare function logError(domain: string, operation: string, error: Error | string, params?: Record<string, unknown>, exitCode?: number): Promise<void>;
+/**
+ * Read audit log entries
+ *
+ * @param options Filter options
+ * @returns Array of audit entries
+ */
+export declare function readAuditLog(options?: {
+    since?: string;
+    domain?: string;
+    operation?: string;
+    success?: boolean;
+    limit?: number;
+}): Promise<AuditEntry[]>;
+/**
+ * Get audit statistics
+ *
+ * @returns Audit statistics
+ */
+export declare function getAuditStats(): Promise<{
+    totalEntries: number;
+    successCount: number;
+    failureCount: number;
+    byDomain: Record<string, number>;
+    byOperation: Record<string, number>;
+    avgDuration: number;
+}>;
+/**
+ * Clear audit log (use with caution)
+ *
+ * @returns Number of entries cleared
+ */
+export declare function clearAuditLog(): Promise<number>;
+/**
+ * Manually rotate audit log
+ *
+ * Forces rotation regardless of size
+ *
+ * @returns Path to rotated log file
+ */
+export declare function rotateLog(): Promise<string | null>;
+/**
+ * Archive old audit entries
+ *
+ * Moves entries older than specified date to archive file
+ *
+ * @param beforeDate ISO date string
+ * @returns Number of entries archived
+ */
+export declare function archiveAuditLog(beforeDate: string): Promise<number>;
+/**
+ * Query audit log entries with filters
+ *
+ * @param options Query options
+ * @returns Filtered audit entries
+ */
+export declare function queryAudit(options?: {
+    since?: string;
+    domain?: string;
+    operation?: string;
+    success?: boolean;
+    taskId?: string;
+    sessionId?: string;
+    limit?: number;
+}): Promise<AuditEntry[]>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/lib/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/lib/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC;KACxC,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuCD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BlE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,GAAG,MAAM,EACrB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA6CxB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CA0BD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAerD;AAkCD;;;;;;GAMG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxD;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BzE;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAexB"}