@falkordb/mcpserver 1.0.1

package/dist/mcp/tools.js

@@ -0,0 +1,258 @@
+import { z } from 'zod';
+import { falkorDBService } from '../services/falkordb.service.js';
+import { redisService } from '../services/redis.service.js';
+import { logger } from '../services/logger.service.js';
+import { AppError, CommonErrors } from '../errors/AppError.js';
+import { config } from '../config/index.js';
+// Define schemas as simple objects first to avoid TS2589 deep recursion
+const queryGraphSchema = {
+    graphName: z.string().describe("The name of the graph to query"),
+    query: z.string().describe("The OpenCypher query to run"),
+    readOnly: z.boolean().optional().describe("If true, executes as a read-only query (GRAPH.RO_QUERY). Useful for replica instances or to prevent accidental writes. Defaults to FALKORDB_DEFAULT_READONLY environment variable."),
+};
+const queryGraphReadOnlySchema = {
+    graphName: z.string().describe("The name of the graph to query"),
+    query: z.string().describe("The read-only OpenCypher query to run (write operations will fail)"),
+};
+const deleteGraphSchema = {
+    graphName: z.string().describe("The name of the graph to delete"),
+    confirmDelete: z.literal(true).describe("Must be set to true to confirm deletion. This is a safety measure to prevent accidental data loss."),
+};
+const setKeySchema = {
+    key: z.string().describe("The key to set"),
+    value: z.string().describe("The value to set"),
+};
+const getKeySchema = {
+    key: z.string().describe("The key to get."),
+};
+const deleteKeySchema = {
+    key: z.string().describe("The key to delete"),
+    confirmDelete: z.literal(true).describe("Must be set to true to confirm deletion. This is a safety measure to prevent accidental data loss."),
+};
+function registerQueryGraphTool(server) {
+    server.registerTool("query_graph", {
+        title: "Query Graph",
+        description: "Run an OpenCypher query on a graph. Supports both read-write and read-only queries.",
+        inputSchema: queryGraphSchema, // Cast to any to prevent TS2589 (deep recursion) during type inference
+    }, async (args) => {
+        // Manual validation since we're using raw shape for registration
+        const { graphName, query, readOnly } = z.object(queryGraphSchema).parse(args);
+        try {
+            if (!graphName?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Graph name is required and cannot be empty', true);
+            }
+            if (!query?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Query is required and cannot be empty', true);
+            }
+            // Use the provided readOnly flag, or fall back to the default from config
+            const isReadOnly = readOnly !== undefined ? readOnly : config.falkorDB.defaultReadOnly;
+            const result = await falkorDBService.executeQuery(graphName, query, undefined, isReadOnly);
+            await logger.debug('Query tool executed successfully', { graphName, readOnly: isReadOnly });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Query tool execution failed', error instanceof Error ? error : new Error(String(error)), { graphName, query: query.substring(0, 100) + (query.length > 100 ? '...' : '') });
+            throw error;
+        }
+    });
+}
+function registerQueryGraphReadOnlyTool(server) {
+    server.registerTool("query_graph_readonly", {
+        title: "Query Graph (Read-Only)",
+        description: "Run a read-only OpenCypher query on a graph using GRAPH.RO_QUERY. This ensures no write operations are performed and is ideal for replica instances.",
+        inputSchema: queryGraphReadOnlySchema,
+    }, async (args) => {
+        const { graphName, query } = z.object(queryGraphReadOnlySchema).parse(args);
+        try {
+            if (!graphName?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Graph name is required and cannot be empty', true);
+            }
+            if (!query?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Query is required and cannot be empty', true);
+            }
+            const result = await falkorDBService.executeReadOnlyQuery(graphName, query);
+            await logger.debug('Read-only query tool executed successfully', { graphName });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Read-only query tool execution failed', error instanceof Error ? error : new Error(String(error)), { graphName, query: query.substring(0, 100) + (query.length > 100 ? '...' : '') });
+            throw error;
+        }
+    });
+}
+function registerListGraphsTool(server) {
+    // Register list_graphs tool
+    server.registerTool("list_graphs", {
+        title: "List Graphs",
+        description: "List all graphs available to query",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await falkorDBService.listGraphs();
+            await logger.debug('List graphs tool executed', { count: result.length });
+            return {
+                content: [{
+                        type: "text",
+                        text: result.join("\n"),
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('List graphs tool execution failed', error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    });
+}
+function registerDeleteGraphTool(server) {
+    // Register delete_graph tool
+    server.registerTool("delete_graph", {
+        title: "Delete Graph",
+        description: "Permanently delete a graph from the database. WARNING: This action is irreversible. You must set confirmDelete to true to proceed.",
+        inputSchema: deleteGraphSchema,
+    }, async (args) => {
+        const { graphName } = z.object(deleteGraphSchema).parse(args);
+        try {
+            if (!graphName?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Graph name is required and cannot be empty', true);
+            }
+            await falkorDBService.deleteGraph(graphName);
+            await logger.info('Delete graph tool executed successfully', { graphName });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Graph ${graphName} deleted`
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Delete graph tool execution failed', error instanceof Error ? error : new Error(String(error)), { graphName });
+            throw error;
+        }
+    });
+}
+function registerListKeysTool(server) {
+    server.registerTool("list_keys", {
+        title: "List Keys",
+        description: "List all keys in Redis",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const keys = await redisService.listKeys();
+            await logger.debug('List keys tool executed', { count: keys.length });
+            return {
+                content: [{
+                        type: "text",
+                        text: keys.join("\n"),
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('List keys tool execution failed', error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    });
+}
+function registerSetKeyTool(server) {
+    // Register set_key tool
+    server.registerTool("set_key", {
+        title: "Set Key",
+        description: "Set a key in Redis",
+        inputSchema: setKeySchema,
+    }, async (args) => {
+        const { key, value } = z.object(setKeySchema).parse(args);
+        try {
+            if (!key?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
+            }
+            if (value === undefined || value === null) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Value is required', true);
+            }
+            await redisService.set(key, value);
+            await logger.debug('Set key tool executed successfully', { key });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Key ${key} set successfully`
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Set key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
+            throw error;
+        }
+    });
+}
+function registerGetKeyTool(server) {
+    // Register get_key tool
+    server.registerTool("get_key", {
+        title: "Get Key",
+        description: "Get a key from Redis",
+        inputSchema: getKeySchema,
+    }, async (args) => {
+        const { key } = z.object(getKeySchema).parse(args);
+        try {
+            if (!key?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
+            }
+            const value = await redisService.get(key);
+            await logger.debug('Get key tool executed successfully', { key, hasValue: value !== null });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Key ${key} is ${value ?? 'null (not found)'}`
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Get key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
+            throw error;
+        }
+    });
+}
+function registerDeleteKeyTool(server) {
+    server.registerTool("delete_key", {
+        title: "Delete Key",
+        description: "Permanently delete a key from Redis. WARNING: This action is irreversible. You must set confirmDelete to true to proceed.",
+        inputSchema: deleteKeySchema,
+    }, async (args) => {
+        const { key } = z.object(deleteKeySchema).parse(args);
+        try {
+            if (!key?.trim()) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
+            }
+            await redisService.delete(key);
+            await logger.debug('Delete key tool executed successfully', { key });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Key ${key} deleted`
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Delete key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
+            throw error;
+        }
+    });
+}
+export default function registerAllTools(server) {
+    // Register query_graph tools
+    registerQueryGraphTool(server);
+    registerQueryGraphReadOnlyTool(server);
+    registerListGraphsTool(server);
+    registerDeleteGraphTool(server);
+    registerSetKeyTool(server);
+    registerGetKeyTool(server);
+    registerDeleteKeyTool(server);
+    registerListKeysTool(server);
+}

package/dist/models/mcp-client-config.js

@@ -0,0 +1,34 @@
+/**
+ * MCP Client Configuration Types
+ */
+/**
+ * Sample MCP Client Configuration
+ */
+export const sampleMCPClientConfig = {
+    defaultServer: "falkordb",
+    servers: {
+        "falkordb": {
+            url: "http://localhost:3000/api/mcp",
+            apiKey: "your_api_key_here"
+        }
+    }
+};
+/**
+ * Sample MCP Server Configuration
+ */
+export const sampleMCPServerConfig = {
+    mcpServers: {
+        "falkordb": {
+            command: "docker",
+            args: [
+                "run",
+                "-i",
+                "--rm",
+                "-p", "3000:3000",
+                "--env-file", ".env",
+                "falkordb-mcpserver",
+                "falkordb://host.docker.internal:6379"
+            ]
+        }
+    }
+};

package/dist/models/mcp-client-config.test.js

@@ -0,0 +1,173 @@
+import { sampleMCPClientConfig, sampleMCPServerConfig } from './mcp-client-config';
+describe('MCP Client Configuration Models', () => {
+    describe('Type Definitions', () => {
+        it('should define MCPServerConfig interface correctly', () => {
+            // Arrange
+            const config = {
+                mcpServers: {
+                    'test-server': {
+                        command: 'node',
+                        args: ['server.js']
+                    }
+                }
+            };
+            // Assert - TypeScript compilation validates the interface
+            expect(config.mcpServers).toBeDefined();
+            expect(config.mcpServers['test-server'].command).toBe('node');
+            expect(config.mcpServers['test-server'].args).toEqual(['server.js']);
+        });
+        it('should define MCPClientConfig interface correctly', () => {
+            // Arrange
+            const config = {
+                defaultServer: 'test',
+                servers: {
+                    'test': {
+                        url: 'http://localhost:3000',
+                        apiKey: 'secret'
+                    }
+                }
+            };
+            // Assert - TypeScript compilation validates the interface
+            expect(config.defaultServer).toBe('test');
+            expect(config.servers).toBeDefined();
+            expect(config.servers['test'].url).toBe('http://localhost:3000');
+            expect(config.servers['test'].apiKey).toBe('secret');
+        });
+        it('should allow optional properties in MCPClientConfig', () => {
+            // Arrange
+            const configWithoutDefaults = {
+                servers: {
+                    'test': {
+                        url: 'http://localhost:3000'
+                        // apiKey is optional
+                    }
+                }
+                // defaultServer is optional
+            };
+            // Assert
+            expect(configWithoutDefaults.defaultServer).toBeUndefined();
+            expect(configWithoutDefaults.servers['test'].apiKey).toBeUndefined();
+            expect(configWithoutDefaults.servers['test'].url).toBe('http://localhost:3000');
+        });
+    });
+    describe('Sample Configurations', () => {
+        describe('sampleMCPClientConfig', () => {
+            it('should have correct structure and values', () => {
+                // Assert
+                expect(sampleMCPClientConfig).toBeDefined();
+                expect(sampleMCPClientConfig.defaultServer).toBe('falkordb');
+                expect(sampleMCPClientConfig.servers).toBeDefined();
+                expect(sampleMCPClientConfig.servers.falkordb).toBeDefined();
+                expect(sampleMCPClientConfig.servers.falkordb.url).toBe('http://localhost:3000/api/mcp');
+                expect(sampleMCPClientConfig.servers.falkordb.apiKey).toBe('your_api_key_here');
+            });
+            it('should be a valid MCPClientConfig', () => {
+                // Act - assign to typed variable to ensure type compliance
+                const config = sampleMCPClientConfig;
+                // Assert
+                expect(config).toBe(sampleMCPClientConfig);
+            });
+            it('should be immutable reference', () => {
+                // Act - get multiple references
+                const ref1 = sampleMCPClientConfig;
+                const ref2 = sampleMCPClientConfig;
+                // Assert
+                expect(ref1).toBe(ref2);
+            });
+        });
+        describe('sampleMCPServerConfig', () => {
+            it('should have correct structure and values', () => {
+                // Assert
+                expect(sampleMCPServerConfig).toBeDefined();
+                expect(sampleMCPServerConfig.mcpServers).toBeDefined();
+                expect(sampleMCPServerConfig.mcpServers.falkordb).toBeDefined();
+                expect(sampleMCPServerConfig.mcpServers.falkordb.command).toBe('docker');
+                expect(sampleMCPServerConfig.mcpServers.falkordb.args).toBeInstanceOf(Array);
+            });
+            it('should have correct docker arguments', () => {
+                // Arrange
+                const expectedArgs = [
+                    'run',
+                    '-i',
+                    '--rm',
+                    '-p', '3000:3000',
+                    '--env-file', '.env',
+                    'falkordb-mcpserver',
+                    'falkordb://host.docker.internal:6379'
+                ];
+                // Assert
+                expect(sampleMCPServerConfig.mcpServers.falkordb.args).toEqual(expectedArgs);
+            });
+            it('should be a valid MCPServerConfig', () => {
+                // Act - assign to typed variable to ensure type compliance
+                const config = sampleMCPServerConfig;
+                // Assert
+                expect(config).toBe(sampleMCPServerConfig);
+            });
+            it('should include Docker container configuration', () => {
+                // Arrange
+                const falkordbConfig = sampleMCPServerConfig.mcpServers.falkordb;
+                // Assert
+                expect(falkordbConfig.command).toBe('docker');
+                expect(falkordbConfig.args).toContain('run');
+                expect(falkordbConfig.args).toContain('falkordb-mcpserver');
+                expect(falkordbConfig.args).toContain('falkordb://host.docker.internal:6379');
+                expect(falkordbConfig.args).toContain('-p');
+                expect(falkordbConfig.args).toContain('3000:3000');
+                expect(falkordbConfig.args).toContain('--env-file');
+                expect(falkordbConfig.args).toContain('.env');
+            });
+        });
+    });
+    describe('Configuration Usage Examples', () => {
+        it('should support multiple servers in client config', () => {
+            // Arrange
+            const multiServerConfig = {
+                defaultServer: 'primary',
+                servers: {
+                    'primary': {
+                        url: 'http://localhost:3000/api/mcp',
+                        apiKey: 'primary-key'
+                    },
+                    'backup': {
+                        url: 'http://backup.example.com/api/mcp',
+                        apiKey: 'backup-key'
+                    },
+                    'dev': {
+                        url: 'http://dev.localhost:3001/api/mcp'
+                        // No API key for dev
+                    }
+                }
+            };
+            // Assert
+            expect(Object.keys(multiServerConfig.servers)).toHaveLength(3);
+            expect(multiServerConfig.servers.primary.apiKey).toBeDefined();
+            expect(multiServerConfig.servers.backup.apiKey).toBeDefined();
+            expect(multiServerConfig.servers.dev.apiKey).toBeUndefined();
+        });
+        it('should support multiple server processes in server config', () => {
+            // Arrange
+            const multiProcessConfig = {
+                mcpServers: {
+                    'falkordb-main': {
+                        command: 'node',
+                        args: ['dist/index.js']
+                    },
+                    'falkordb-worker': {
+                        command: 'node',
+                        args: ['dist/worker.js', '--port', '3001']
+                    },
+                    'falkordb-docker': {
+                        command: 'docker',
+                        args: ['run', '-p', '3002:3000', 'falkordb-mcpserver']
+                    }
+                }
+            };
+            // Assert
+            expect(Object.keys(multiProcessConfig.mcpServers)).toHaveLength(3);
+            expect(multiProcessConfig.mcpServers['falkordb-main'].command).toBe('node');
+            expect(multiProcessConfig.mcpServers['falkordb-worker'].args).toContain('--port');
+            expect(multiProcessConfig.mcpServers['falkordb-docker'].command).toBe('docker');
+        });
+    });
+});

package/dist/models/mcp.types.js

@@ -0,0 +1,4 @@
+/**
+ * MCP Types - based on Model Context Protocol specification
+ */
+export {};

package/dist/services/falkordb.service.js

@@ -0,0 +1,175 @@
+import { FalkorDB } from 'falkordb';
+import { config } from '../config/index.js';
+import { AppError, CommonErrors } from '../errors/AppError.js';
+import { logger } from './logger.service.js';
+class FalkorDBService {
+    client = null;
+    maxRetries = 5;
+    retryCount = 0;
+    initializingPromise = null;
+    constructor() {
+        // Don't initialize in constructor - use explicit initialization
+    }
+    async initialize() {
+        // Idempotency guard: skip if already connected
+        if (this.client) {
+            return;
+        }
+        if (this.initializingPromise) {
+            return this.initializingPromise;
+        }
+        this.retryCount = 0;
+        this.initializingPromise = this._initialize();
+        try {
+            await this.initializingPromise;
+        }
+        finally {
+            this.initializingPromise = null;
+        }
+    }
+    async _initialize() {
+        for (;; this.retryCount++) {
+            try {
+                // Fire-and-forget: informational log, not critical
+                logger.info('Attempting to connect to FalkorDB', {
+                    host: config.falkorDB.host,
+                    port: config.falkorDB.port,
+                    attempt: this.retryCount + 1
+                });
+                this.client = await FalkorDB.connect({
+                    socket: {
+                        host: config.falkorDB.host,
+                        port: config.falkorDB.port,
+                    },
+                    password: config.falkorDB.password,
+                    username: config.falkorDB.username,
+                });
+                // Test connection
+                const connection = await this.client.connection;
+                await connection.ping();
+                // Fire-and-forget: informational log, not critical
+                logger.info('Successfully connected to FalkorDB');
+                this.retryCount = 0;
+                return;
+            }
+            catch (error) {
+                // Clean up any partially connected client before retrying or throwing
+                if (this.client) {
+                    try {
+                        await this.client.close();
+                    }
+                    catch {
+                        // Ignore cleanup errors
+                    }
+                    this.client = null;
+                }
+                if (this.retryCount < this.maxRetries) {
+                    // Fire-and-forget: informational log before retry delay
+                    logger.warn('Failed to connect to FalkorDB, retrying...', {
+                        attempt: this.retryCount + 1,
+                        maxRetries: this.maxRetries,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                    const delay = Math.min(5000 * 2 ** this.retryCount, 30000) + Math.random() * 1000;
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+                else {
+                    const appError = new AppError(CommonErrors.CONNECTION_FAILED, `Failed to connect to FalkorDB after ${this.maxRetries} attempts: ${error instanceof Error ? error.message : String(error)}`, true);
+                    await logger.error('FalkorDB connection failed permanently', appError);
+                    throw appError;
+                }
+            }
+        }
+    }
+    async executeQuery(graphName, query, params, readOnly = false) {
+        if (!this.client) {
+            throw new AppError(CommonErrors.CONNECTION_FAILED, 'FalkorDB client not initialized. Call initialize() first.', true);
+        }
+        try {
+            const graph = this.client.selectGraph(graphName);
+            const result = readOnly
+                ? await graph.roQuery(query, params)
+                : await graph.query(query, params);
+            // Fire-and-forget: informational log, not critical
+            logger.debug('Query executed successfully', {
+                graphName,
+                query: query.substring(0, 100) + (query.length > 100 ? '...' : ''),
+                hasParams: !!params,
+                readOnly
+            });
+            return result;
+        }
+        catch (error) {
+            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to execute ${readOnly ? 'read-only ' : ''}query on graph '${graphName}': ${error instanceof Error ? error.message : String(error)}`, true);
+            // Sanitize query for error logging using same truncation as debug logs
+            const safeQuery = query.substring(0, 100) + (query.length > 100 ? '...' : '');
+            await logger.error('Query execution failed', appError, { graphName, query: safeQuery, readOnly });
+            throw appError;
+        }
+    }
+    /**
+     * Execute a read-only query on a specific graph
+     * This is useful for replica instances or when you want to ensure no writes occur
+     * @param graphName - The name of the graph to query
+     * @param query - The OpenCypher query to execute
+     * @param params - Optional query parameters
+     * @returns Query result
+     */
+    async executeReadOnlyQuery(graphName, query, params) {
+        return this.executeQuery(graphName, query, params, true);
+    }
+    /**
+     * Lists all available graphs in FalkorDB
+     * @returns Array of graph names
+     */
+    async listGraphs() {
+        if (!this.client) {
+            throw new AppError(CommonErrors.CONNECTION_FAILED, 'FalkorDB client not initialized. Call initialize() first.', true);
+        }
+        try {
+            const graphs = await this.client.list();
+            // Fire-and-forget: informational log, not critical
+            logger.debug('Listed graphs successfully', { count: graphs.length });
+            return graphs;
+        }
+        catch (error) {
+            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to list graphs: ${error instanceof Error ? error.message : String(error)}`, true);
+            await logger.error('Failed to list graphs', appError);
+            throw appError;
+        }
+    }
+    async deleteGraph(graphName) {
+        if (!this.client) {
+            throw new AppError(CommonErrors.CONNECTION_FAILED, 'FalkorDB client not initialized. Call initialize() first.', true);
+        }
+        try {
+            await this.client.selectGraph(graphName).delete();
+            // Fire-and-forget: informational log, not critical
+            logger.info('Graph deleted successfully', { graphName });
+        }
+        catch (error) {
+            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to delete graph '${graphName}': ${error instanceof Error ? error.message : String(error)}`, true);
+            await logger.error('Failed to delete graph', appError, { graphName });
+            throw appError;
+        }
+    }
+    async close() {
+        if (this.client) {
+            try {
+                await this.client.close();
+                // Fire-and-forget: informational log, not critical
+                logger.info('FalkorDB connection closed successfully');
+            }
+            catch (error) {
+                // Fire-and-forget: best-effort log during shutdown
+                logger.error('Error closing FalkorDB connection', error instanceof Error ? error : new Error(String(error)));
+            }
+            finally {
+                this.client = null;
+                this.retryCount = 0;
+            }
+        }
+    }
+}
+// Export a singleton instance
+export const falkorDBService = new FalkorDBService();