Rebase from SecKatie/FalkorDB-MCPServer

.env.example

@@ -1,12 +1,18 @@
-# Server Configuration
-PORT=3000
+# Environment Configuration
 NODE_ENV=development
 
 # FalkorDB Configuration
 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
 
-# MCP Configuration
-MCP_API_KEY=your_mcp_api_key_here
+# Redis Configuration (for key-value operations)
+REDIS_URL=redis://localhost:6379
+REDIS_USERNAME=
+REDIS_PASSWORD=
+
+# Logging Configuration (optional)
+ENABLE_FILE_LOGGING=false

.github/workflows/node.yml

@@ -1,74 +1,84 @@
-name: Node.js CI/CD
+name: CI/CD
+
+permissions:
+  contents: read
 
 on:
   push:
-    branches: [ main, master, develop ]
+    branches: [ main, develop ]
   pull_request:
-    branches: [ main, master ]
+    branches: [ main ]
+  release:
+    types: [ published ]
 
 jobs:
-  build:
+  test:
+    name: Test & Build
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 22.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - name: Checkout code
+      uses: actions/checkout@v4
 
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+    - name: Setup Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
 
     - name: Install dependencies
       run: npm ci
 
-    - name: Build
-      run: npm run build --if-present
+    - name: Lint code
+      run: npm run lint
 
-    - name: Lint
-      run: npm run lint --if-present
+    - name: Run tests with coverage
+      run: npm run test:coverage
 
-    - name: Test
-      run: npm test --if-present
-      env:
-        CI: true
-
-  docker:
-    needs: build
-    if: github.event_name != 'pull_request'
+    - name: Build project
+      run: npm run build
+
+    - name: Upload coverage to Codecov
+      if: matrix.node-version == '20.x'
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage/lcov.info
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+
+  publish:
+    name: Publish to NPM
+    needs: [test]
     runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment:
+      name: Default
+      url: https://www.npmjs.com/package/falkordb-mcpserver/v/${{ github.event.release.tag_name }}
 
     steps:
-    - uses: actions/checkout@v3
-
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
+    - name: Checkout code
+      uses: actions/checkout@v4
 
-    - name: Login to GitHub Container Registry
-      uses: docker/login-action@v2
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
       with:
-        registry: ghcr.io
-        username: ${{ github.repository_owner }}
-        password: ${{ secrets.GITHUB_TOKEN }}
+        node-version: '20.x'
+        cache: 'npm'
+        registry-url: 'https://registry.npmjs.org'
 
-    - name: Extract metadata for Docker
-      id: meta
-      uses: docker/metadata-action@v4
-      with:
-        images: ghcr.io/${{ github.repository }}
-        tags: |
-          type=sha,format=long
-          type=ref,event=branch
-          type=ref,event=tag
-
-    - name: Build and push Docker image
-      uses: docker/build-push-action@v4
-      with:
-        context: .
-        push: true
-        tags: ${{ steps.meta.outputs.tags }}
-        labels: ${{ steps.meta.outputs.labels }}
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build project
+      run: npm run build
+
+    - name: Publish to NPM
+      run: npm publish
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -134,3 +134,7 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# MCP and project-specific
+logs/
+*.mcp.log

CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Build**: `npm run build` - Compiles TypeScript to JavaScript in `dist/`
+- **Dev server**: `npm run dev` - Starts development server with hot-reloading using nodemon
+- **Production start**: `npm start` - Runs the built application from `dist/index.js`
+- **Lint**: `npm run lint` - Runs ESLint on TypeScript files
+- **Test**: `npm test` - Runs Jest test suite
+- **Test with coverage**: `npm run test:coverage` - Runs tests with coverage report
+
+## Project Architecture
+
+This is a Model Context Protocol (MCP) server that enables AI models to interact with FalkorDB graph databases through natural language. The server communicates via stdio transport and provides tools for graph operations.
+
+### MCP Server Implementation
+- **Entry point**: `src/index.ts` - Creates MCP server using `@modelcontextprotocol/sdk`
+- **Communication**: Uses stdio transport for MCP protocol (not HTTP)
+- **MCP Tools registered**:
+  - `query_graph` - Execute OpenCypher queries on specific graphs
+  - `list_graphs` - List all available graphs in the database
+  - `delete_graph` - Delete specific graphs
+  - `set_key`/`get_key` - Redis key-value operations for data storage
+- **MCP Resources**: `graph_list` resource provides markdown-formatted graph listings
+
+### Core Services
+- **FalkorDB Service** (`src/services/falkordb.service.ts`): 
+  - Singleton service managing FalkorDB connections
+  - Uses `falkordb` npm package
+  - Handles connection retries and pooling
+  - Main operations: `executeQuery()`, `listGraphs()`, `deleteGraph()`
+
+- **Redis Service** (`src/services/redis.service.ts`):
+  - Manages Redis operations for key-value storage
+  - Used alongside graph operations
+
+### Configuration
+- **Config system** (`src/config/index.ts`): Centralized configuration using dotenv
+- **Environment variables**: Defined in `.env` file (copy from `.env.example`)
+- **Key variables**: `FALKORDB_HOST`, `FALKORDB_PORT`, `FALKORDB_USERNAME`, `FALKORDB_PASSWORD`
+
+### Current Project Structure
+```
+src/
+├── index.ts                    # MCP server entry point with tool/resource registration
+├── services/
+│   ├── falkordb.service.ts     # FalkorDB connection and graph operations
+│   └── redis.service.ts        # Redis key-value operations
+├── config/
+│   └── index.ts                # Centralized configuration using dotenv
+├── models/                     # TypeScript type definitions
+│   ├── mcp.types.ts           # MCP protocol interfaces
+│   └── mcp-client-config.ts   # Configuration models
+└── utils/
+    └── connection-parser.ts    # Utility functions
+```
+
+## Testing
+- **Framework**: Jest with ts-jest preset
+- **Test files**: Located alongside source files with `.test.ts` extension
+- **Coverage**: Configured to exclude test files and type definitions
+- **Test environment**: Node.js environment
+
+## Key Dependencies
+- `@modelcontextprotocol/sdk` - MCP protocol implementation
+- `falkordb` - FalkorDB Node.js client
+- `zod` - Schema validation for MCP tools
+
+## MCP Integration Setup
+
+### Claude Desktop Configuration
+To use this server with Claude Desktop, add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "falkordb": {
+      "command": "node",
+      "args": ["/absolute/path/to/falkordb-mcpserver/dist/index.js"]
+    }
+  }
+}
+```
+
+### Environment Configuration
+Required environment variables in `.env`:
+- `FALKORDB_HOST` - FalkorDB hostname (default: localhost)
+- `FALKORDB_PORT` - FalkorDB port (default: 6379)
+- `FALKORDB_USERNAME` - Optional authentication
+- `FALKORDB_PASSWORD` - Optional authentication
+- `REDIS_URL` - Redis connection for key-value operations
+
+## Development Notes
+- Uses ES modules (`"type": "module"` in package.json)
+- TypeScript configuration in `tsconfig.json`
+- Nodemon watches `src/**/*.ts` for development hot-reload
+- **Important**: This is an MCP server, not a web server - it communicates via stdio transport
+- Build output in `dist/` directory is executed by MCP clients
+- The server automatically closes FalkorDB and Redis connections on exit