Rebase from SecKatie/FalkorDB-MCPServer

.env.example

@@ -6,6 +6,8 @@ FALKORDB_HOST=localhost
 FALKORDB_PORT=6379
 FALKORDB_USERNAME=
 FALKORDB_PASSWORD=
+# Set to 'true' to use read-only queries by default (useful for replica instances)
+FALKORDB_DEFAULT_READONLY=false
 
 # Redis Configuration (for key-value operations)
 REDIS_URL=redis://localhost:6379

README.md

@@ -10,11 +10,12 @@ FalkorDB MCP Server enables AI assistants like Claude to interact with FalkorDB
 ## 🎯 What is this?
 
 This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing AI models to:
-- **Query graph databases** using OpenCypher
+- **Query graph databases** using OpenCypher (with read-only mode support)
 - **Create and manage** nodes and relationships
 - **Store and retrieve** key-value data
 - **List and explore** multiple graphs
 - **Delete graphs** when needed
+- **Read-only queries** for replica instances or to prevent accidental writes
 
 ## 🚀 Quick Start
 
@@ -72,6 +73,7 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
    FALKORDB_PORT=6379
    FALKORDB_USERNAME=    # Optional
    FALKORDB_PASSWORD=    # Optional
+   FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode (useful for replicas)
 
    # Redis Configuration (for key-value operations)
    REDIS_URL=redis://localhost:6379
@@ -115,8 +117,16 @@ Once connected, you can ask Claude to:
 "Show me all people who know each other"
 "Find the shortest path between two nodes"
 "What relationships does John have?"
+"Run a read-only query on the replica instance"
 ```
 
+**Note:** The `query_graph` tool now supports a `readOnly` parameter to execute queries in read-only mode using `GRAPH.RO_QUERY`. This is ideal for:
+- Running queries on replica instances
+- Preventing accidental write operations
+- Ensuring data integrity in production environments
+
+There's also a dedicated `query_graph_readonly` tool that always executes queries in read-only mode.
+
 ### 📝 Manage Data
 ```
 "Create a new person named Alice who knows Bob"
@@ -211,6 +221,22 @@ FALKORDB_USERNAME=your-username
 FALKORDB_PASSWORD=your-secure-password
 ```
 
+### Read-Only Mode for Replica Instances
+
+If you're connecting to a FalkorDB replica instance or want to ensure no write operations are performed, you can enable read-only mode by default:
+
+```env
+FALKORDB_DEFAULT_READONLY=true
+```
+
+This will make all queries execute using `GRAPH.RO_QUERY` by default. You can still override this per-query by setting the `readOnly` parameter in the `query_graph` tool.
+
+**Use cases:**
+- **Replica instances**: Prevent writes to read replicas in replication setups
+- **Production safety**: Ensure critical data isn't accidentally modified
+- **Reporting/analytics**: Run queries for dashboards without risk of data changes
+- **Multi-tenant environments**: Provide read-only access to certain users
+
 ### Running Multiple Instances
 
 You can run multiple MCP servers for different FalkorDB instances:
@@ -222,14 +248,16 @@ You can run multiple MCP servers for different FalkorDB instances:
       "command": "node",
       "args": ["path/to/server/dist/index.js"],
       "env": {
-        "FALKORDB_HOST": "dev.falkordb.local"
+        "FALKORDB_HOST": "dev.falkordb.local",
+        "FALKORDB_DEFAULT_READONLY": "false"
       }
     },
-    "falkordb-prod": {
+    "falkordb-prod-replica": {
       "command": "node", 
       "args": ["path/to/server/dist/index.js"],
       "env": {
-        "FALKORDB_HOST": "prod.falkordb.com"
+        "FALKORDB_HOST": "replica.falkordb.com",
+        "FALKORDB_DEFAULT_READONLY": "true"
       }
     }
   }

src/config/index.test.ts

@@ -13,6 +13,8 @@ describe('Config', () => {
     expect(config.falkorDB).toHaveProperty('port');
     expect(config.falkorDB).toHaveProperty('username');
     expect(config.falkorDB).toHaveProperty('password');
+    expect(config.falkorDB).toHaveProperty('defaultReadOnly');
+    expect(typeof config.falkorDB.defaultReadOnly).toBe('boolean');
   });
 
   test('should have MCP configuration', () => {

src/config/index.ts

@@ -15,6 +15,7 @@ export const config = {
     port: parseInt(process.env.FALKORDB_PORT || '6379'),
     username: process.env.FALKORDB_USERNAME || '',
     password: process.env.FALKORDB_PASSWORD || '',
+    defaultReadOnly: process.env.FALKORDB_DEFAULT_READONLY === 'true',
   },
   redis: {
     url: process.env.REDIS_URL || 'redis://localhost:6379',

src/mcp/tools.ts

@@ -4,19 +4,21 @@ 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';
 
 function registerQueryGraphTool(server: McpServer): void {
   server.registerTool(
     "query_graph",
     {
       title: "Query Graph",
-      description: "Run a OpenCypher query on a graph",
+      description: "Run a OpenCypher query on a graph. Supports both read-write and read-only queries.",
       inputSchema: {
         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."),
       },
     },
-    async ({graphName, query}) => {
+    async ({graphName, query, readOnly}) => {
       try {
         if (!graphName?.trim()) {
           throw new AppError(
@@ -34,8 +36,11 @@ function registerQueryGraphTool(server: McpServer): void {
           );
         }
 
-        const result = await falkorDBService.executeQuery(graphName, query);
-        await logger.debug('Query tool executed successfully', { graphName });
+        // 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: [{
@@ -51,6 +56,52 @@ function registerQueryGraphTool(server: McpServer): void {
   )
 }
 
+function registerQueryGraphReadOnlyTool(server: McpServer): void {
+  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: {
+        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)"),
+      },
+    },
+    async ({graphName, query}) => {
+      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 });
+        throw error;
+      }
+    }
+  )
+}
+
 function registerListGraphsTool(server: McpServer): void {
   // Register list_graphs tool
   server.registerTool(
@@ -267,8 +318,9 @@ function registerDeleteKeyTool(server: McpServer): void {
 }
 
 export default function registerAllTools(server: McpServer): void {
-  // Register query_graph tool
+  // Register query_graph tools
   registerQueryGraphTool(server);
+  registerQueryGraphReadOnlyTool(server);
   registerListGraphsTool(server);
   registerDeleteGraphTool(server);
   registerSetKeyTool(server);

src/services/falkordb.service.test.ts

@@ -18,7 +18,8 @@ jest.mock('../config/index.js', () => ({
       host: 'localhost',
       port: 6379,
       username: 'testuser',
-      password: 'testpass'
+      password: 'testpass',
+      defaultReadOnly: false
     }
   }
 }));
@@ -27,6 +28,7 @@ jest.mock('../config/index.js', () => ({
 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();
@@ -40,6 +42,7 @@ jest.mock('falkordb', () => {
         }),
         selectGraph: mockSelectGraph.mockReturnValue({
           query: mockQuery,
+          roQuery: mockRoQuery,
           delete: mockDelete
         }),
         list: mockList,
@@ -48,6 +51,7 @@ jest.mock('falkordb', () => {
     },
     mockSelectGraph,
     mockQuery,
+    mockRoQuery,
     mockList,
     mockClose,
     mockPing,
@@ -218,6 +222,7 @@ describe('FalkorDB Service', () => {
       // Assert
       expect(mockFalkorDB.mockSelectGraph).toHaveBeenCalledWith(graphName);
       expect(mockFalkorDB.mockQuery).toHaveBeenCalledWith(query, params);
+      expect(mockFalkorDB.mockRoQuery).not.toHaveBeenCalled();
       expect(result).toEqual(expectedResult);
     });
 
@@ -242,6 +247,53 @@ describe('FalkorDB Service', () => {
       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 as any).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 as any).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
@@ -278,6 +330,69 @@ describe('FalkorDB Service', () => {
         expect((error as AppError).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 as any).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 as AppError).name).toBe(CommonErrors.OPERATION_FAILED);
+        expect((error as AppError).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 as any).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 as any).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', () => {