@falkordb/mcpserver 1.1.1 → 1.2.1

package/.env.example

@@ -10,12 +10,15 @@ MCP_TRANSPORT=stdio
 # MCP_API_KEY=
 
 # FalkorDB Configuration
+# When using Docker Compose, set FALKORDB_HOST=falkordb (the service name)
 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
+# Set to 'true' to enforce strict read-only mode - blocks all write operations (queries, graph deletions, key modifications)
+FALKORDB_STRICT_READONLY=false
 
 # Logging Configuration (optional)
 ENABLE_FILE_LOGGING=false

package/README.md

@@ -79,6 +79,27 @@ This is useful for:
 - Running the server standalone without Claude Desktop
 - Custom integrations and scripting
 
+### Docker Compose
+
+Run FalkorDB and the MCP server together:
+
+```bash
+cp .env.example .env   # create env file; edit to set MCP_API_KEY, FALKORDB_PASSWORD, etc.
+docker compose up -d
+```
+
+> **Note:** Skipping the `.env` file leaves variables like `MCP_API_KEY` and `FALKORDB_PASSWORD` empty, which disables API key authentication and uses no database password.
+
+This starts FalkorDB with health checks and persistent volumes, plus the MCP server pre-configured to connect to it.
+
+The MCP server runs in **HTTP transport** mode and is exposed on `localhost:3000` by default. To connect a client, configure it to use:
+
+- **Transport:** `http`
+- **URL:** `http://localhost:3000`
+- **API Key:** Set via the `MCP_API_KEY` environment variable (optional)
+
+See `docker-compose.yml` for the exact port and configuration values.
+
 ### Installation
 
 1. **Clone and install:**
@@ -286,7 +307,25 @@ Requests without a valid key receive a `401 Unauthorized` response. Auth is only
 
 ### Using with Docker
 
-Build and run the MCP server in a Docker container (defaults to HTTP transport):
+**Using pre-built images from Docker Hub:**
+
+```bash
+# Use the latest stable release
+docker pull falkordb/mcpserver:latest
+docker run -p 3000:3000 \
+  -e FALKORDB_HOST=host.docker.internal \
+  -e FALKORDB_PORT=6379 \
+  -e MCP_API_KEY=your-secret-key \
+  falkordb/mcpserver:latest
+
+# Or use the edge version (latest main branch)
+docker pull falkordb/mcpserver:edge
+
+# Or pin to a specific version
+docker pull falkordb/mcpserver:1.0.0
+```
+
+**Building locally:**
 
 ```bash
 docker build -t falkordb-mcpserver .
@@ -307,7 +346,7 @@ services:
       - "6379:6379"
 
   mcp-server:
-    build: .
+    image: falkordb/mcpserver:latest  # or use 'build: .' to build locally
     ports:
       - "3000:3000"
     environment:

package/dist/config/index.js

@@ -14,6 +14,7 @@ export const config = {
         username: process.env.FALKORDB_USERNAME || '',
         password: process.env.FALKORDB_PASSWORD || '',
         defaultReadOnly: process.env.FALKORDB_DEFAULT_READONLY === 'true',
+        strictReadOnly: process.env.FALKORDB_STRICT_READONLY === 'true',
     },
     mcp: {
         transport: (process.env.MCP_TRANSPORT || 'stdio'),

package/dist/config/index.test.js

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

package/dist/mcp/tools.js

@@ -34,6 +34,10 @@ function registerQueryGraphTool(server) {
             }
             // Use the provided readOnly flag, or fall back to the default from config
             const isReadOnly = readOnly !== undefined ? readOnly : config.falkorDB.defaultReadOnly;
+            // Enforce strict read-only mode if enabled
+            if (config.falkorDB.strictReadOnly && !isReadOnly) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Cannot execute write queries: server is in strict read-only mode (FALKORDB_STRICT_READONLY=true)', true);
+            }
             const result = await falkorDBService.executeQuery(graphName, query, undefined, isReadOnly);
             await logger.debug('Query tool executed successfully', { graphName, readOnly: isReadOnly });
             return {
@@ -113,6 +117,10 @@ function registerDeleteGraphTool(server) {
             if (!graphName?.trim()) {
                 throw new AppError(CommonErrors.INVALID_INPUT, 'Graph name is required and cannot be empty', true);
             }
+            // Enforce strict read-only mode if enabled
+            if (config.falkorDB.strictReadOnly) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Cannot delete graphs: server is in strict read-only mode (FALKORDB_STRICT_READONLY=true)', true);
+            }
             await falkorDBService.deleteGraph(graphName);
             await logger.info('Delete graph tool executed successfully', { graphName });
             return {

package/dist/mcp/tools.test.js

@@ -0,0 +1,172 @@
+import { AppError, CommonErrors } from '../errors/AppError.js';
+// Mock the logger service
+jest.mock('../services/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 FalkorDB service
+jest.mock('../services/falkordb.service.js', () => ({
+    falkorDBService: {
+        executeQuery: jest.fn(),
+        executeReadOnlyQuery: jest.fn(),
+        listGraphs: jest.fn(),
+        deleteGraph: jest.fn(),
+    }
+}));
+// Mock config with different scenarios
+let mockConfig = {
+    falkorDB: {
+        defaultReadOnly: false,
+        strictReadOnly: false,
+    }
+};
+jest.mock('../config/index.js', () => ({
+    get config() {
+        return mockConfig;
+    }
+}));
+// Import after mocks are set up
+import registerAllTools from './tools.js';
+import { falkorDBService } from '../services/falkordb.service.js';
+describe('MCP Tools - Strict Read-Only Mode', () => {
+    let server;
+    let queryGraphHandler;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Reset mock config
+        mockConfig = {
+            falkorDB: {
+                defaultReadOnly: false,
+                strictReadOnly: false,
+            }
+        };
+        // Create a minimal mock server that captures tool handlers
+        server = {
+            registerTool: jest.fn((name, schema, handler) => {
+                if (name === 'query_graph') {
+                    queryGraphHandler = handler;
+                }
+            }),
+        };
+        registerAllTools(server);
+    });
+    describe('query_graph tool with strictReadOnly=false', () => {
+        beforeEach(() => {
+            mockConfig.falkorDB.strictReadOnly = false;
+            mockConfig.falkorDB.defaultReadOnly = false;
+        });
+        it('should allow readOnly=false when strictReadOnly is disabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'CREATE (n:Test) RETURN n', undefined, false);
+        });
+        it('should allow readOnly=true when strictReadOnly is disabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+                readOnly: true,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should use default when readOnly is not specified', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, false);
+        });
+    });
+    describe('query_graph tool with strictReadOnly=true', () => {
+        beforeEach(() => {
+            mockConfig.falkorDB.strictReadOnly = true;
+            mockConfig.falkorDB.defaultReadOnly = true;
+        });
+        it('should reject readOnly=false when strictReadOnly is enabled', async () => {
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            })).rejects.toThrow(AppError);
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            })).rejects.toThrow('strict read-only mode');
+            expect(falkorDBService.executeQuery).not.toHaveBeenCalled();
+        });
+        it('should allow readOnly=true when strictReadOnly is enabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+                readOnly: true,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should use defaultReadOnly when readOnly is not specified in strict mode', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should include proper error information when rejecting write queries', async () => {
+            try {
+                await queryGraphHandler({
+                    graphName: 'test',
+                    query: 'CREATE (n:Test) RETURN n',
+                    readOnly: false,
+                });
+                fail('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.INVALID_INPUT);
+                expect(error.message).toContain('FALKORDB_STRICT_READONLY=true');
+            }
+        });
+        it('should reject write queries when strictReadOnly is enabled and defaultReadOnly=false and readOnly is not specified', async () => {
+            // Override defaultReadOnly for this specific test case
+            mockConfig.falkorDB.defaultReadOnly = false;
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+            })).rejects.toThrow(AppError);
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+            })).rejects.toThrow('strict read-only mode');
+            expect(falkorDBService.executeQuery).not.toHaveBeenCalled();
+        });
+    });
+    describe('query_graph tool input validation', () => {
+        it('should reject empty graph name', async () => {
+            await expect(queryGraphHandler({
+                graphName: '',
+                query: 'MATCH (n) RETURN n',
+            })).rejects.toThrow('Graph name is required and cannot be empty');
+        });
+        it('should reject empty query', async () => {
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: '',
+            })).rejects.toThrow('Query is required and cannot be empty');
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkordb/mcpserver",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Model Context Protocol server for FalkorDB graph databases - enables AI assistants to query and manage graph data using natural language",
   "main": "dist/index.js",
   "type": "module",
@@ -64,15 +64,14 @@
     "test:ci": "jest --coverage --ci --watchAll=false",
     "inspect": "npm run build && npx -y @modelcontextprotocol/inspector node $PWD/dist/index.js",
     "clean": "rm -rf dist coverage",
-    "prepublish": "npm run test:ci && npm run lint && npm run build",
     "prepublishOnly": "npm run clean && npm run test:ci && npm run lint && npm run build"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",
-    "eslint": "^9.31.0",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
     "jest": "^30.0.5",
     "nodemon": "^3.1.10",
     "ts-jest": "^29.4.0",
@@ -84,12 +83,16 @@
     "dotenv": "^17.2.1",
     "falkordb": "^6.3.0",
     "platformdirs": "^4.3.8-rc3",
-    "zod": "^3.23.0"
+    "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "overrides": {
+    "minimatch": "^10.2.1",
+    "test-exclude": "^7.0.2"
+  },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/SecKatie"