@falkordb/mcpserver 1.0.1

package/dist/errors/ErrorHandler.test.js

@@ -0,0 +1,146 @@
+import { ErrorHandler, errorHandler } from './ErrorHandler';
+import { AppError, CommonErrors } from './AppError';
+// Mock the logger service
+jest.mock('../services/logger.service.js', () => ({
+    logger: {
+        error: jest.fn().mockResolvedValue(undefined),
+        info: jest.fn().mockResolvedValue(undefined),
+        errorSync: jest.fn(),
+    }
+}));
+// Get mock logger from the mocked module
+let mockLogger;
+describe('ErrorHandler', () => {
+    let handler;
+    beforeEach(async () => {
+        handler = new ErrorHandler();
+        jest.clearAllMocks();
+        // Import the mock logger
+        const loggerModule = await import('../services/logger.service.js');
+        mockLogger = loggerModule.logger;
+    });
+    describe('handleError', () => {
+        it('should handle operational errors gracefully', async () => {
+            // Arrange
+            const operationalError = new AppError(CommonErrors.OPERATION_FAILED, 'Test operational error', true);
+            // Act
+            await handler.handleError(operationalError);
+            // Assert
+            expect(mockLogger.error).toHaveBeenCalledWith('Unhandled error occurred', operationalError, expect.objectContaining({
+                timestamp: expect.any(String),
+                errorType: 'AppError'
+            }));
+            expect(mockLogger.info).toHaveBeenCalledWith('Operational error handled gracefully', {
+                errorName: operationalError.name,
+                errorMessage: operationalError.message
+            });
+        });
+        it('should handle programmer errors with critical logging', async () => {
+            // Arrange
+            const programmerError = new AppError(CommonErrors.INVALID_INPUT, 'Test programmer error', false // not operational
+            );
+            // Act
+            await handler.handleError(programmerError);
+            // Assert
+            expect(mockLogger.error).toHaveBeenCalledWith('Unhandled error occurred', programmerError, expect.objectContaining({
+                timestamp: expect.any(String),
+                errorType: 'AppError'
+            }));
+            expect(mockLogger.error).toHaveBeenCalledWith('Programmer error detected - may require process restart', programmerError, {
+                recommendation: 'Review code for bugs',
+                severity: 'critical'
+            });
+        });
+        it('should handle generic errors as programmer errors', async () => {
+            // Arrange
+            const genericError = new Error('Generic error message');
+            // Act
+            await handler.handleError(genericError);
+            // Assert
+            expect(mockLogger.error).toHaveBeenCalledWith('Unhandled error occurred', genericError, expect.objectContaining({
+                timestamp: expect.any(String),
+                errorType: 'Error'
+            }));
+            expect(mockLogger.error).toHaveBeenCalledWith('Programmer error detected - may require process restart', genericError, {
+                recommendation: 'Review code for bugs',
+                severity: 'critical'
+            });
+        });
+    });
+    describe('isTrustedError', () => {
+        it('should return true for operational AppError', () => {
+            // Arrange
+            const operationalError = new AppError(CommonErrors.OPERATION_FAILED, 'Test operational error', true);
+            // Act
+            const result = handler.isTrustedError(operationalError);
+            // Assert
+            expect(result).toBe(true);
+        });
+        it('should return false for non-operational AppError', () => {
+            // Arrange
+            const nonOperationalError = new AppError(CommonErrors.INVALID_INPUT, 'Test programmer error', false);
+            // Act
+            const result = handler.isTrustedError(nonOperationalError);
+            // Assert
+            expect(result).toBe(false);
+        });
+        it('should return false for generic Error', () => {
+            // Arrange
+            const genericError = new Error('Generic error');
+            // Act
+            const result = handler.isTrustedError(genericError);
+            // Assert
+            expect(result).toBe(false);
+        });
+        it('should return false for non-Error objects', () => {
+            // Arrange
+            const nonError = { message: 'Not an error' };
+            // Act
+            const result = handler.isTrustedError(nonError);
+            // Assert
+            expect(result).toBe(false);
+        });
+    });
+    describe('crashIfUntrustedError', () => {
+        let processExitSpy;
+        beforeEach(() => {
+            processExitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+                throw new Error('process.exit called');
+            });
+        });
+        afterEach(() => {
+            processExitSpy.mockRestore();
+        });
+        it('should not crash for trusted operational errors', () => {
+            // Arrange
+            const operationalError = new AppError(CommonErrors.OPERATION_FAILED, 'Test operational error', true);
+            // Act & Assert
+            expect(() => handler.crashIfUntrustedError(operationalError)).not.toThrow();
+            expect(processExitSpy).not.toHaveBeenCalled();
+            expect(mockLogger.errorSync).not.toHaveBeenCalled();
+        });
+        it('should crash for untrusted programmer errors', () => {
+            // Arrange
+            const programmerError = new AppError(CommonErrors.INVALID_INPUT, 'Test programmer error', false);
+            // Act & Assert
+            expect(() => handler.crashIfUntrustedError(programmerError)).toThrow('process.exit called');
+            expect(mockLogger.errorSync).toHaveBeenCalledWith('Crashing process due to untrusted error', programmerError);
+            expect(processExitSpy).toHaveBeenCalledWith(1);
+        });
+        it('should crash for generic errors', () => {
+            // Arrange
+            const genericError = new Error('Generic error');
+            // Act & Assert
+            expect(() => handler.crashIfUntrustedError(genericError)).toThrow('process.exit called');
+            expect(mockLogger.errorSync).toHaveBeenCalledWith('Crashing process due to untrusted error', genericError);
+            expect(processExitSpy).toHaveBeenCalledWith(1);
+        });
+    });
+    describe('singleton instance', () => {
+        it('should export a singleton instance', () => {
+            // Assert
+            expect(errorHandler).toBeInstanceOf(ErrorHandler);
+            expect(errorHandler).toBe(errorHandler); // Same instance
+        });
+    });
+});

package/dist/index.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { createRequire } from 'module';
+import { createServer } from 'http';
+import { randomUUID } from 'crypto';
+import { falkorDBService } from './services/falkordb.service.js';
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { redisService } from './services/redis.service.js';
+import { errorHandler } from './errors/ErrorHandler.js';
+import { logger } from './services/logger.service.js';
+import { config } from './config/index.js';
+import registerAllTools from './mcp/tools.js';
+import registerAllResources from './mcp/resources.js';
+import registerAllPrompts from './mcp/prompts.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+// Setup global error handlers following Node.js best practices
+process.on('uncaughtException', (error) => {
+    logger.errorSync('Uncaught exception occurred', error);
+    void errorHandler.handleError(error).catch((handlerError) => {
+        logger.errorSync('Error while handling uncaught exception', handlerError instanceof Error ? handlerError : new Error(String(handlerError)));
+    });
+    errorHandler.crashIfUntrustedError(error);
+});
+process.on('unhandledRejection', (reason) => {
+    // Re-throw as error to be caught by uncaughtException handler
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    throw error;
+});
+// Graceful shutdown handler
+let httpServer = null;
+const gracefulShutdown = async (signal) => {
+    await logger.info(`Received ${signal}, shutting down gracefully`);
+    try {
+        if (httpServer) {
+            await new Promise((resolve, reject) => {
+                httpServer.close((err) => err ? reject(err) : resolve());
+            });
+        }
+        await falkorDBService.close();
+        await redisService.close();
+        await logger.info('All services closed successfully');
+        process.exit(0);
+    }
+    catch (error) {
+        await logger.error('Error during graceful shutdown', error instanceof Error ? error : new Error(String(error)));
+        process.exit(1);
+    }
+};
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+// Create an MCP server
+const server = new McpServer({
+    name: "falkordb",
+    version: version
+}, {
+    capabilities: {
+        tools: {
+            listChanged: true,
+        },
+        resources: {
+            listChanged: true,
+        },
+        prompts: {
+            listChanged: true,
+        },
+        logging: {},
+    }
+});
+// Note: Current MCP TypeScript SDK doesn't directly support elicitation in tool handlers
+// This is a conceptual implementation - you'd need to implement session access
+// Configure logger to send notifications to MCP clients
+logger.setMcpServer(server);
+// Register all tools and resources
+registerAllTools(server);
+registerAllResources(server);
+registerAllPrompts(server);
+// Initialize services before starting server
+async function initializeServices() {
+    await logger.info('Initializing FalkorDB MCP server...');
+    try {
+        await falkorDBService.initialize();
+        await redisService.initialize();
+        await logger.info('All services initialized successfully');
+    }
+    catch (error) {
+        await logger.error('Failed to initialize services', error instanceof Error ? error : new Error(String(error)));
+        throw error;
+    }
+}
+// Main server startup
+async function startServer() {
+    try {
+        await initializeServices();
+        if (config.mcp.transport === 'http') {
+            await startHTTPServer();
+        }
+        else {
+            await startStdioServer();
+        }
+    }
+    catch (error) {
+        await logger.error('Failed to start MCP server', error instanceof Error ? error : new Error(String(error)));
+        await gracefulShutdown('STARTUP_ERROR');
+    }
+}
+async function startStdioServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await logger.info('MCP server started successfully (stdio transport)');
+}
+async function startHTTPServer() {
+    const port = config.server.port;
+    const apiKey = config.mcp.apiKey;
+    // Map session IDs to their transports for session management
+    const sessions = new Map();
+    httpServer = createServer(async (req, res) => {
+        // API key authentication for HTTP transport
+        if (apiKey) {
+            const authHeader = req.headers['authorization'];
+            if (!authHeader || authHeader !== `Bearer ${apiKey}`) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized' }));
+                return;
+            }
+        }
+        const sessionId = req.headers['mcp-session-id'];
+        if (req.method === 'POST') {
+            // Read the request body
+            const body = await readRequestBody(req);
+            const parsedBody = JSON.parse(body);
+            if (sessionId && sessions.has(sessionId)) {
+                // Existing session — route to its transport
+                const transport = sessions.get(sessionId);
+                await transport.handleRequest(req, res, parsedBody);
+            }
+            else if (!sessionId && isInitializeRequest(parsedBody)) {
+                // New session initialization
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                });
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid)
+                        sessions.delete(sid);
+                };
+                // Connect a fresh McpServer for this session
+                const sessionServer = createSessionServer();
+                await sessionServer.connect(transport);
+                await transport.handleRequest(req, res, parsedBody);
+                // Store session after handling (sessionId is set after init)
+                if (transport.sessionId) {
+                    sessions.set(transport.sessionId, transport);
+                }
+            }
+            else {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Bad Request: No valid session or initialization' }));
+            }
+        }
+        else if (req.method === 'GET') {
+            // SSE stream for server-initiated messages
+            if (sessionId && sessions.has(sessionId)) {
+                const transport = sessions.get(sessionId);
+                await transport.handleRequest(req, res);
+            }
+            else {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Bad Request: Invalid or missing session ID' }));
+            }
+        }
+        else if (req.method === 'DELETE') {
+            // Session termination
+            if (sessionId && sessions.has(sessionId)) {
+                const transport = sessions.get(sessionId);
+                await transport.handleRequest(req, res);
+                sessions.delete(sessionId);
+            }
+            else {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Bad Request: Invalid or missing session ID' }));
+            }
+        }
+        else {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method Not Allowed' }));
+        }
+    });
+    httpServer.listen(port, () => {
+        // Fire-and-forget: non-critical startup log
+        logger.info(`MCP server started successfully (HTTP transport on port ${port})`);
+    });
+}
+function createSessionServer() {
+    const sessionServer = new McpServer({
+        name: "falkordb",
+        version: version,
+    }, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true },
+            prompts: { listChanged: true },
+            logging: {},
+        },
+    });
+    logger.setMcpServer(sessionServer);
+    registerAllTools(sessionServer);
+    registerAllResources(sessionServer);
+    registerAllPrompts(sessionServer);
+    return sessionServer;
+}
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk.toString(); });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+function isInitializeRequest(body) {
+    if (typeof body === 'object' && body !== null && 'method' in body) {
+        return body.method === 'initialize';
+    }
+    if (Array.isArray(body)) {
+        return body.some(msg => typeof msg === 'object' && msg !== null && 'method' in msg && msg.method === 'initialize');
+    }
+    return false;
+}
+// Start the server
+startServer().catch(async (error) => {
+    await logger.error('Fatal startup error', error instanceof Error ? error : new Error(String(error)));
+    process.exit(1);
+});

package/dist/mcp/prompts.js

@@ -0,0 +1,229 @@
+import { z } from "zod";
+// Define schemas as simple objects first to avoid TS2589 deep recursion
+const userSetupArgsSchema = {
+    name: z.string().describe("The name of the user"),
+};
+const memoryQueryArgsSchema = {
+    query: z.string().describe("The query or topic to search for in memory"),
+    context: z.string().optional().describe("Additional context to help scope the search"),
+    relationship_depth: z.coerce.number().min(1).max(3).describe("How many relationship hops to traverse (1-3)")
+};
+function registerUserSetupPrompt(server) {
+    // Register user_setup prompt
+    server.registerPrompt("user_setup", {
+        title: "User Setup",
+        description: "Setup the user graph node and connect it to the rest of the relevant nodes",
+        argsSchema: userSetupArgsSchema, // Cast to any to prevent TS2589 (deep recursion) during type inference
+    }, async (args) => {
+        const { name } = z.object(userSetupArgsSchema).parse(args);
+        const userMessage = `# User Setup Task
+
+You are working with a FalkorDB graph database to manage user information and relationships. 
+
+**User Information:**
+- Name: ${name}
+
+**Your task is to:**
+
+1. **Check if user exists**: Search for a node with the name "${name}" in the memory graph using a parameterized query: \`MATCH (u) WHERE u.name = $name RETURN u\` with params \`{name: "${name}"}\`
+2. **Create user node if needed**: If no node exists with this name, create a new user node using a parameterized query with the following properties:
+   - name: "${name}"
+   - type: "User"
+   - created_at: current timestamp
+3. **Establish relationships**: Ensure the user node is properly connected to relevant nodes in the graph, such as:
+   - Recent conversations or interactions
+   - Associated topics or interests
+   - Related entities or contexts
+
+**Guidelines:**
+- Use appropriate Cypher queries to search, create, and connect nodes
+- Maintain data consistency and avoid duplicate user nodes
+- Consider the existing graph structure when establishing new relationships
+- Log any operations performed for debugging purposes
+
+Please proceed with setting up the user "${name}" in the memory graph.`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: userMessage
+                    }
+                }
+            ]
+        };
+    });
+}
+function registerMemoryQueryPrompt(server) {
+    server.registerPrompt("memory_query", {
+        title: "Memory Query",
+        description: "Query the memory graph to retrieve and analyze stored information",
+        argsSchema: memoryQueryArgsSchema, // Cast to any to prevent TS2589 (deep recursion) during type inference
+    }, async (args) => {
+        const { query, context, relationship_depth } = z.object(memoryQueryArgsSchema).parse(args);
+        const memoryMessage = `# Memory Query Task
+
+You are working with a FalkorDB graph database to retrieve and analyze stored memory information.
+
+**Query Information:**
+- Search Query: ${query}
+${context ? `- Additional Context: ${context}` : ''}
+- Relationship Depth: ${relationship_depth} hops
+
+**Your task is to:**
+
+1. **Search for relevant nodes**: Use parameterized Cypher queries to find nodes that match or relate to the search query
+   - Always use query parameters (e.g., \`$query\`) instead of string interpolation to prevent injection
+   - Look for nodes with matching names, properties, or content
+   - Consider partial matches and semantic relationships
+   
+2. **Traverse relationships**: Explore connected nodes up to ${relationship_depth} relationship hops to gather context:
+   - Follow relationships like RELATES_TO, MENTIONED_IN, CONNECTED_TO
+   - Include timestamps and relationship properties
+   
+3. **Analyze and synthesize**: Process the retrieved information to:
+   - Identify key patterns and connections
+   - Extract relevant facts and relationships
+   - Organize information chronologically or by relevance
+   
+4. **Provide structured results**: Format your findings including:
+   - Direct matches and their properties
+   - Related nodes and connection paths
+   - Temporal patterns if applicable
+   - Confidence levels for relationships
+
+**Query Guidelines:**
+- Use MATCH patterns to find relevant nodes
+- Utilize WHERE clauses for filtering
+- Consider using OPTIONAL MATCH for related information
+- Include LIMIT clauses to manage result size
+- Order results by relevance or timestamp
+
+**Example Cypher patterns (always use parameterized queries):**
+\`\`\`cypher
+// Use $query parameter - never interpolate user input directly
+MATCH (n) WHERE n.name CONTAINS $query OR n.content CONTAINS $query
+MATCH (n)-[r*1..${relationship_depth}]-(related)
+RETURN n, r, related ORDER BY n.timestamp DESC
+// Pass params: {query: "${query}"}
+\`\`\`
+
+Please proceed with querying the memory graph for information about "${query}".`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: memoryMessage
+                    }
+                }
+            ]
+        };
+    });
+}
+function registerGraphReorganizationPrompt(server) {
+    server.registerPrompt("graph_reorganization", {
+        title: "Graph Reorganization",
+        description: "Analyze and reorganize the graph structure for optimal performance and usability"
+    }, async () => {
+        const reorganizationMessage = `# Graph Reorganization Task
+
+You are working with a FalkorDB graph database to optimize its structure for better performance and usability.
+
+**Your task is to:**
+
+1. **Analyze Current Structure**: Examine the graph to identify structural issues:
+   - Find nodes with excessive connections (hubs with >50 relationships)
+   - Identify disconnected components or islands
+   - Locate duplicate or near-duplicate nodes
+   - Find outdated or stale connections
+   - Analyze relationship distribution and patterns
+
+2. **Performance Optimization**: Based on the analysis, implement improvements:
+   - **Merge duplicate nodes**: Combine nodes with similar properties or content
+   - **Create strategic hubs**: Add intermediate nodes to reduce direct connections
+   - **Remove dead connections**: Delete relationships to non-existent or irrelevant nodes
+   - **Add semantic clustering**: Group related nodes under topic or category nodes
+   - **Optimize relationship types**: Ensure relationship labels are descriptive and indexed
+
+3. **Usability Enhancement**: Improve graph navigation and querying:
+   - **Add metadata nodes**: Create nodes that summarize clusters or topics
+   - **Establish clear hierarchies**: Organize nodes in logical parent-child relationships
+   - **Create shortcut relationships**: Add direct paths for frequently accessed connections
+   - **Implement time-based organization**: Group nodes by temporal relevance
+
+4. **Validation and Testing**: After reorganization:
+   - Verify all critical paths remain intact
+   - Test common query patterns for performance
+   - Ensure no data loss occurred during restructuring
+   - Document changes made for future reference
+
+**Optimization Strategies by Goal:**
+
+**Performance Focus:**
+- Minimize query traversal depth
+- Balance node degree distribution
+- Create efficient index structures
+- Reduce redundant relationships
+
+**Usability Focus:**
+- Improve semantic organization
+- Add descriptive metadata
+- Create intuitive navigation paths
+- Enhance discoverability
+
+**Balanced Approach:**
+- Apply moderate optimizations from both areas
+- Prioritize changes with highest impact/effort ratio
+
+**Analysis Queries to Run:**
+\`\`\`cypher
+// Find high-degree nodes
+MATCH (n)
+WITH n, size((n)--()) as degree
+WHERE degree > 20
+RETURN n, degree ORDER BY degree DESC LIMIT 10
+
+// Find disconnected components
+MATCH (n)
+WHERE NOT (n)--()
+RETURN count(n) as isolated_nodes
+
+// Identify potential duplicates
+MATCH (n1), (n2)
+WHERE id(n1) < id(n2) 
+AND n1.name = n2.name 
+AND n1.type = n2.type
+RETURN n1, n2
+
+// Find stale nodes (older than 30 days with no recent connections)
+MATCH (n)
+WHERE n.created_at < datetime() - duration({days: 30})
+AND NOT (n)-[:UPDATED_AT|ACCESSED_AT]-()
+RETURN n LIMIT 20
+\`\`\`
+
+**Reorganization Operations:**
+Implement the most impactful optimizations. Prioritize operations that provide the best balance of performance improvement and structural clarity.
+
+Begin with analyzing the current graph structure and proceed with the reorganization plan.`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: reorganizationMessage
+                    }
+                }
+            ]
+        };
+    });
+}
+export default function registerAllPrompts(server) {
+    registerUserSetupPrompt(server);
+    registerMemoryQueryPrompt(server);
+    registerGraphReorganizationPrompt(server);
+}

package/dist/mcp/resources.js

@@ -0,0 +1,26 @@
+import { falkorDBService } from '../services/falkordb.service.js';
+import { logger } from '../services/logger.service.js';
+export default function registerAllResources(server) {
+    // Register graph_list resource
+    server.registerResource("graph_list", "graph://listing", {
+        title: "List Graphs",
+        description: "List all graphs in the database",
+        mimeType: "text/plain",
+    }, async (uri) => {
+        try {
+            const graphNames = await falkorDBService.listGraphs();
+            const markdownList = graphNames.map(name => `- ${name}`).join('\n');
+            await logger.debug('Graph list resource accessed', { count: graphNames.length });
+            return {
+                contents: [{
+                        uri: uri.href,
+                        text: markdownList,
+                    }]
+            };
+        }
+        catch (error) {
+            await logger.error('Failed to fetch graph list resource', error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    });
+}