FalkorDB-MCPServer: Instructions file for Codex

Project Guidelines

Overview

FalkorDB-MCPServer is a Model Context Protocol (MCP) server that enables AI models to interact with FalkorDB graph databases through natural language. It communicates via stdio transport and exposes graph operations as MCP tools.

Build & Install

npm install          # install dependencies
npm run build        # compile TypeScript to JavaScript in dist/

Development

npm run dev          # start dev server with hot-reloading (nodemon)
npm start            # run the built application from dist/index.js

Testing

Tests require a running FalkorDB instance on localhost:6379:

docker run -p 6379:6379 -d falkordb/falkordb:edge

Run all tests:

npm test

Run with coverage:

npm run test:coverage

• Framework: Jest with ts-jest preset
• Test files: Located alongside source files with .test.ts extension

Pre-commit Checks

Always run these checks before every commit:

npm run lint         # ESLint on TypeScript files
npm run build        # ensure TypeScript compiles without errors
npm test             # ensure all tests pass

Code Style

• Linter: ESLint (configured in eslint.config.js)
• Language: TypeScript (ES modules, "type": "module" in package.json)
• Node.js: requires a recent LTS version
• Imports: use .js specifiers in TypeScript source (ESM convention)

Project Structure

src/
├── index.ts                    # MCP server entry point — tool/resource registration, stdio transport
├── services/
│   ├── falkordb.service.ts     # FalkorDB connection and graph operations (singleton)
│   └── logger.service.ts       # Logging and MCP notifications
├── config/
│   └── index.ts                # Centralized configuration using dotenv
├── models/
│   ├── mcp.types.ts            # MCP protocol interfaces
│   └── mcp-client-config.ts    # Configuration models
└── utils/
    └── connection-parser.ts    # Utility functions