@falkordb/mcpserver 1.0.1

package/dist/services/falkordb.service.test.js

@@ -0,0 +1,489 @@
+import { falkorDBService } from './falkordb.service';
+import { AppError, CommonErrors } from '../errors/AppError.js';
+// Mock the logger service
+jest.mock('./logger.service.js', () => ({
+    logger: {
+        info: jest.fn().mockResolvedValue(undefined),
+        warn: jest.fn().mockResolvedValue(undefined),
+        error: jest.fn().mockResolvedValue(undefined),
+        debug: jest.fn().mockResolvedValue(undefined),
+    }
+}));
+// Mock the config
+jest.mock('../config/index.js', () => ({
+    config: {
+        falkorDB: {
+            host: 'localhost',
+            port: 6379,
+            username: 'testuser',
+            password: 'testpass',
+            defaultReadOnly: false
+        }
+    }
+}));
+// Mock the FalkorDB library
+jest.mock('falkordb', () => {
+    const mockSelectGraph = jest.fn();
+    const mockQuery = jest.fn();
+    const mockRoQuery = jest.fn();
+    const mockList = jest.fn();
+    const mockClose = jest.fn();
+    const mockPing = jest.fn();
+    const mockDelete = jest.fn();
+    return {
+        FalkorDB: {
+            connect: jest.fn().mockResolvedValue({
+                connection: Promise.resolve({
+                    ping: mockPing
+                }),
+                selectGraph: mockSelectGraph.mockReturnValue({
+                    query: mockQuery,
+                    roQuery: mockRoQuery,
+                    delete: mockDelete
+                }),
+                list: mockList,
+                close: mockClose
+            })
+        },
+        mockSelectGraph,
+        mockQuery,
+        mockRoQuery,
+        mockList,
+        mockClose,
+        mockPing,
+        mockDelete
+    };
+});
+describe('FalkorDB Service', () => {
+    let mockFalkorDB;
+    beforeAll(async () => {
+        // Access the mocks
+        mockFalkorDB = await import('falkordb');
+    });
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Reset service state
+        falkorDBService.client = null;
+        falkorDBService.retryCount = 0;
+        falkorDBService.initializingPromise = null;
+    });
+    describe('initialize', () => {
+        it('should successfully initialize and connect to FalkorDB', async () => {
+            // Arrange
+            mockFalkorDB.FalkorDB.connect.mockResolvedValue({
+                connection: Promise.resolve({
+                    ping: mockFalkorDB.mockPing.mockResolvedValue('PONG')
+                }),
+                selectGraph: mockFalkorDB.mockSelectGraph,
+                list: mockFalkorDB.mockList,
+                close: mockFalkorDB.mockClose
+            });
+            // Act
+            await falkorDBService.initialize();
+            // Assert
+            expect(mockFalkorDB.FalkorDB.connect).toHaveBeenCalledWith({
+                socket: {
+                    host: 'localhost',
+                    port: 6379,
+                },
+                password: 'testpass',
+                username: 'testuser',
+            });
+            expect(mockFalkorDB.mockPing).toHaveBeenCalled();
+            expect(falkorDBService.client).not.toBeNull();
+            expect(falkorDBService.retryCount).toBe(0);
+            expect(falkorDBService.initializingPromise).toBeNull();
+        });
+        it('should await ongoing initialization if already initializing', async () => {
+            // Arrange
+            mockFalkorDB.FalkorDB.connect.mockResolvedValue({
+                connection: Promise.resolve({
+                    ping: mockFalkorDB.mockPing.mockResolvedValue('PONG')
+                }),
+                selectGraph: mockFalkorDB.mockSelectGraph,
+                list: mockFalkorDB.mockList,
+                close: mockFalkorDB.mockClose
+            });
+            // Act - start two initializations concurrently
+            const init1 = falkorDBService.initialize();
+            const init2 = falkorDBService.initialize();
+            await Promise.all([init1, init2]);
+            // Assert - connect should only be called once
+            expect(mockFalkorDB.FalkorDB.connect).toHaveBeenCalledTimes(1);
+            expect(falkorDBService.client).not.toBeNull();
+        });
+        it('should retry connection on failure and eventually succeed', async () => {
+            // Arrange
+            const connectError = new Error('Connection failed');
+            mockFalkorDB.FalkorDB.connect
+                .mockRejectedValueOnce(connectError)
+                .mockRejectedValueOnce(connectError)
+                .mockResolvedValueOnce({
+                connection: Promise.resolve({
+                    ping: mockFalkorDB.mockPing.mockResolvedValue('PONG')
+                }),
+                selectGraph: mockFalkorDB.mockSelectGraph,
+                list: mockFalkorDB.mockList,
+                close: mockFalkorDB.mockClose
+            });
+            // Mock setTimeout to avoid actual delays
+            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
+                setImmediate(callback);
+                return {};
+            });
+            // Act
+            await falkorDBService.initialize();
+            // Assert
+            expect(mockFalkorDB.FalkorDB.connect).toHaveBeenCalledTimes(3);
+            expect(falkorDBService.client).not.toBeNull();
+            expect(falkorDBService.retryCount).toBe(0);
+            // Cleanup
+            setTimeoutSpy.mockRestore();
+        });
+        it('should throw AppError after max retries exceeded', async () => {
+            // Arrange
+            const connectError = new Error('Connection failed');
+            mockFalkorDB.FalkorDB.connect.mockRejectedValue(connectError);
+            // Mock setTimeout to avoid actual delays
+            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
+                setImmediate(callback);
+                return {};
+            });
+            // Act & Assert
+            try {
+                await falkorDBService.initialize();
+                fail('Expected initialize to throw AppError');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.CONNECTION_FAILED);
+            }
+            expect(mockFalkorDB.FalkorDB.connect).toHaveBeenCalledTimes(6); // 1 initial + 5 retries
+            // Cleanup
+            setTimeoutSpy.mockRestore();
+        });
+        it('should handle ping failure during connection test', async () => {
+            // Arrange
+            const pingError = new Error('Ping failed');
+            mockFalkorDB.FalkorDB.connect.mockResolvedValue({
+                connection: Promise.resolve({
+                    ping: mockFalkorDB.mockPing.mockRejectedValue(pingError)
+                }),
+                selectGraph: mockFalkorDB.mockSelectGraph,
+                list: mockFalkorDB.mockList,
+                close: mockFalkorDB.mockClose
+            });
+            // Mock setTimeout to avoid actual delays
+            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
+                setImmediate(callback);
+                return {};
+            });
+            // Act & Assert
+            await expect(falkorDBService.initialize()).rejects.toThrow(AppError);
+            // Cleanup
+            setTimeoutSpy.mockRestore();
+        });
+    });
+    describe('executeQuery', () => {
+        it('should execute a query on the specified graph', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'MATCH (n) RETURN n';
+            const params = { param1: 'value1' };
+            const expectedResult = { records: [{ id: 1 }] };
+            mockFalkorDB.mockQuery.mockResolvedValue(expectedResult);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            const result = await falkorDBService.executeQuery(graphName, query, params);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockQuery).toHaveBeenCalledWith(query, params);
+            expect(mockFalkorDB.mockRoQuery).not.toHaveBeenCalled();
+            expect(result).toEqual(expectedResult);
+        });
+        it('should execute a query without params', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'MATCH (n) RETURN n';
+            const expectedResult = { records: [{ id: 1 }] };
+            mockFalkorDB.mockQuery.mockResolvedValue(expectedResult);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            const result = await falkorDBService.executeQuery(graphName, query);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockQuery).toHaveBeenCalledWith(query, undefined);
+            expect(result).toEqual(expectedResult);
+        });
+        it('should execute a read-only query when readOnly flag is true', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'MATCH (n) RETURN n';
+            const params = { param1: 'value1' };
+            const expectedResult = { records: [{ id: 1 }] };
+            mockFalkorDB.mockRoQuery.mockResolvedValue(expectedResult);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            const result = await falkorDBService.executeQuery(graphName, query, params, true);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockRoQuery).toHaveBeenCalledWith(query, params);
+            expect(mockFalkorDB.mockQuery).not.toHaveBeenCalled();
+            expect(result).toEqual(expectedResult);
+        });
+        it('should execute a read-only query without params', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'MATCH (n) RETURN n';
+            const expectedResult = { records: [{ id: 1 }] };
+            mockFalkorDB.mockRoQuery.mockResolvedValue(expectedResult);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            const result = await falkorDBService.executeQuery(graphName, query, undefined, true);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockRoQuery).toHaveBeenCalledWith(query, undefined);
+            expect(mockFalkorDB.mockQuery).not.toHaveBeenCalled();
+            expect(result).toEqual(expectedResult);
+        });
+        it('should throw AppError if client is not initialized', async () => {
+            // Arrange
+            falkorDBService.client = null;
+            // Act & Assert
+            await expect(falkorDBService.executeQuery('graph', 'query'))
+                .rejects
+                .toThrow(AppError);
+            await expect(falkorDBService.executeQuery('graph', 'query'))
+                .rejects
+                .toThrow('FalkorDB client not initialized');
+        });
+        it('should throw AppError when query execution fails', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'INVALID QUERY';
+            const queryError = new Error('Query syntax error');
+            mockFalkorDB.mockQuery.mockRejectedValue(queryError);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act & Assert
+            try {
+                await falkorDBService.executeQuery(graphName, query);
+                fail('Expected executeQuery to throw AppError');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
+            }
+        });
+        it('should throw AppError when read-only query execution fails', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'CREATE (n) RETURN n';
+            const queryError = new Error('Write operations not allowed in read-only mode');
+            mockFalkorDB.mockRoQuery.mockRejectedValue(queryError);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act & Assert
+            try {
+                await falkorDBService.executeQuery(graphName, query, undefined, true);
+                fail('Expected executeQuery to throw AppError');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
+                expect(error.message).toContain('read-only');
+            }
+        });
+    });
+    describe('executeReadOnlyQuery', () => {
+        it('should execute a read-only query using ro_query', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const query = 'MATCH (n) RETURN n';
+            const params = { param1: 'value1' };
+            const expectedResult = { records: [{ id: 1 }] };
+            mockFalkorDB.mockRoQuery.mockResolvedValue(expectedResult);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            const result = await falkorDBService.executeReadOnlyQuery(graphName, query, params);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockRoQuery).toHaveBeenCalledWith(query, params);
+            expect(mockFalkorDB.mockQuery).not.toHaveBeenCalled();
+            expect(result).toEqual(expectedResult);
+        });
+        it('should throw AppError if client is not initialized', async () => {
+            // Arrange
+            falkorDBService.client = null;
+            // Act & Assert
+            await expect(falkorDBService.executeReadOnlyQuery('graph', 'query'))
+                .rejects
+                .toThrow(AppError);
+            await expect(falkorDBService.executeReadOnlyQuery('graph', 'query'))
+                .rejects
+                .toThrow('FalkorDB client not initialized');
+        });
+    });
+    describe('listGraphs', () => {
+        it('should return a list of graphs', async () => {
+            // Arrange
+            const expectedGraphs = ['graph1', 'graph2'];
+            mockFalkorDB.mockList.mockResolvedValue(expectedGraphs);
+            // Force client to be available
+            falkorDBService.client = {
+                list: mockFalkorDB.mockList
+            };
+            // Act
+            const result = await falkorDBService.listGraphs();
+            // Assert
+            expect(mockFalkorDB.mockList).toHaveBeenCalled();
+            expect(result).toEqual(expectedGraphs);
+        });
+        it('should return empty array when no graphs exist', async () => {
+            // Arrange
+            const expectedGraphs = [];
+            mockFalkorDB.mockList.mockResolvedValue(expectedGraphs);
+            // Force client to be available
+            falkorDBService.client = {
+                list: mockFalkorDB.mockList
+            };
+            // Act
+            const result = await falkorDBService.listGraphs();
+            // Assert
+            expect(mockFalkorDB.mockList).toHaveBeenCalled();
+            expect(result).toEqual(expectedGraphs);
+        });
+        it('should throw AppError if client is not initialized', async () => {
+            // Arrange
+            falkorDBService.client = null;
+            // Act & Assert
+            await expect(falkorDBService.listGraphs())
+                .rejects
+                .toThrow(AppError);
+            await expect(falkorDBService.listGraphs())
+                .rejects
+                .toThrow('FalkorDB client not initialized');
+        });
+        it('should throw AppError when listing graphs fails', async () => {
+            // Arrange
+            const listError = new Error('Database connection lost');
+            mockFalkorDB.mockList.mockRejectedValue(listError);
+            // Force client to be available
+            falkorDBService.client = {
+                list: mockFalkorDB.mockList
+            };
+            // Act & Assert
+            try {
+                await falkorDBService.listGraphs();
+                fail('Expected listGraphs to throw AppError');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
+            }
+        });
+    });
+    describe('deleteGraph', () => {
+        it('should delete a graph successfully', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            mockFalkorDB.mockDelete.mockResolvedValue(undefined);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act
+            await falkorDBService.deleteGraph(graphName);
+            // Assert
+            expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
+            expect(mockFalkorDB.mockDelete).toHaveBeenCalled();
+        });
+        it('should throw AppError if client is not initialized', async () => {
+            // Arrange
+            falkorDBService.client = null;
+            // Act & Assert
+            await expect(falkorDBService.deleteGraph('testGraph'))
+                .rejects
+                .toThrow(AppError);
+            await expect(falkorDBService.deleteGraph('testGraph'))
+                .rejects
+                .toThrow('FalkorDB client not initialized');
+        });
+        it('should throw AppError when delete operation fails', async () => {
+            // Arrange
+            const graphName = 'testGraph';
+            const deleteError = new Error('Graph not found');
+            mockFalkorDB.mockDelete.mockRejectedValue(deleteError);
+            // Force client to be available
+            falkorDBService.client = {
+                selectGraph: mockFalkorDB.mockSelectGraph
+            };
+            // Act & Assert
+            try {
+                await falkorDBService.deleteGraph(graphName);
+                fail('Expected deleteGraph to throw AppError');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
+            }
+        });
+    });
+    describe('close', () => {
+        it('should close the client connection successfully', async () => {
+            // Arrange
+            mockFalkorDB.mockClose.mockResolvedValue(undefined);
+            falkorDBService.client = {
+                close: mockFalkorDB.mockClose
+            };
+            falkorDBService.retryCount = 3;
+            // Act
+            await falkorDBService.close();
+            // Assert
+            expect(mockFalkorDB.mockClose).toHaveBeenCalled();
+            expect(falkorDBService.client).toBeNull();
+            expect(falkorDBService.retryCount).toBe(0);
+        });
+        it('should handle close error gracefully', async () => {
+            // Arrange
+            const closeError = new Error('Close failed');
+            mockFalkorDB.mockClose.mockRejectedValue(closeError);
+            falkorDBService.client = {
+                close: mockFalkorDB.mockClose
+            };
+            falkorDBService.retryCount = 2;
+            // Act
+            await falkorDBService.close();
+            // Assert
+            expect(mockFalkorDB.mockClose).toHaveBeenCalled();
+            expect(falkorDBService.client).toBeNull();
+            expect(falkorDBService.retryCount).toBe(0);
+        });
+        it('should not throw if client is already null', async () => {
+            // Arrange
+            falkorDBService.client = null;
+            // Act & Assert
+            await expect(falkorDBService.close()).resolves.not.toThrow();
+            expect(mockFalkorDB.mockClose).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/services/logger.service.js

@@ -0,0 +1,151 @@
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { userLogDir } from 'platformdirs';
+/**
+ * Enhanced logging service for MCP servers with both MCP client notifications and file fallback
+ * Logs are sent to MCP clients when connected, and always written to files for persistence
+ */
+export class Logger {
+    logDir;
+    logFile;
+    mcpServer;
+    constructor() {
+        // For MCP servers, we primarily use MCP notifications for logging
+        // File logging is optional and only enabled if environment allows it
+        this.logDir = userLogDir('falkordb-mcp', 'mulliken-llc', '0.1.0', false, true);
+        this.logFile = join(this.logDir, 'falkordb-mcp.log');
+        // Only create log directory if we're in development or explicitly enabled
+        if (process.env.ENABLE_FILE_LOGGING === 'true' || process.env.NODE_ENV === 'development') {
+            try {
+                if (!existsSync(this.logDir)) {
+                    mkdirSync(this.logDir, { recursive: true });
+                }
+            }
+            catch (error) {
+                // If we can't create logs directory, disable file logging
+                console.warn('Failed to create log directory:', error instanceof Error ? error.message : String(error));
+                this.logFile = '';
+            }
+        }
+        else {
+            // Disable file logging by default for MCP servers
+            this.logFile = '';
+        }
+    }
+    /**
+     * Set the MCP server instance to enable client notifications
+     * This should be called after the server is created but before starting
+     */
+    setMcpServer(server) {
+        this.mcpServer = server;
+    }
+    formatLog(level, message, context) {
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            ...(context && { context }),
+            pid: process.pid
+        };
+        return JSON.stringify(logEntry) + '\n';
+    }
+    writeLog(level, message, context) {
+        // Guard against file logging when disabled
+        if (!this.logFile) {
+            return;
+        }
+        try {
+            // Always write to file for persistence
+            const logLine = this.formatLog(level, message, context);
+            appendFileSync(this.logFile, logLine);
+        }
+        catch {
+            // If we can't log to file, we can't do much about it without breaking MCP
+            // In production, consider using a more robust logging solution
+        }
+    }
+    async sendMcpLog(level, message, context) {
+        if (!this.mcpServer) {
+            return;
+        }
+        try {
+            // Format log data for MCP client
+            const logData = context ? `${message} | ${JSON.stringify(context)}` : message;
+            // Map WARN to warning for MCP spec compliance
+            const mcpLevel = level === 'WARN' ? 'warning' : level.toLowerCase();
+            // Send notification to MCP client
+            await this.mcpServer.server.notification({
+                method: 'notifications/message',
+                params: {
+                    level: mcpLevel,
+                    data: logData,
+                    logger: 'falkordb-mcp'
+                }
+            });
+        }
+        catch {
+            // If MCP notification fails, just continue - file logging is our fallback
+            // Don't log this error to avoid infinite loops
+        }
+    }
+    async log(level, message, context) {
+        // Always write to file
+        this.writeLog(level, message, context);
+        // Try to send to MCP client if server is available
+        await this.sendMcpLog(level, message, context);
+    }
+    async info(message, context) {
+        await this.log('INFO', message, context);
+    }
+    async warn(message, context) {
+        await this.log('WARN', message, context);
+    }
+    async error(message, error, context) {
+        const errorContext = error ? {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+            ...error.isOperational !== undefined && {
+                isOperational: error.isOperational
+            },
+            ...context
+        } : context;
+        await this.log('ERROR', message, errorContext);
+    }
+    async debug(message, context) {
+        if (process.env.NODE_ENV === 'development') {
+            await this.log('DEBUG', message, context);
+        }
+    }
+    // Synchronous versions for backward compatibility in cases where async isn't possible
+    infoSync(message, context) {
+        this.writeLog('INFO', message, context);
+        // Fire and forget for MCP notification
+        this.sendMcpLog('INFO', message, context).catch(() => { });
+    }
+    warnSync(message, context) {
+        this.writeLog('WARN', message, context);
+        this.sendMcpLog('WARN', message, context).catch(() => { });
+    }
+    errorSync(message, error, context) {
+        const errorContext = error ? {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+            ...error.isOperational !== undefined && {
+                isOperational: error.isOperational
+            },
+            ...context
+        } : context;
+        this.writeLog('ERROR', message, errorContext);
+        this.sendMcpLog('ERROR', message, errorContext).catch(() => { });
+    }
+    debugSync(message, context) {
+        if (process.env.NODE_ENV === 'development') {
+            this.writeLog('DEBUG', message, context);
+            this.sendMcpLog('DEBUG', message, context).catch(() => { });
+        }
+    }
+}
+// Export singleton instance
+export const logger = new Logger();