Faulkner DB MCP Server

Faulkner DB - Temporal Knowledge Graph System

Faulkner DB empowers software teams to capture, query, and analyze architectural decisions, implementation patterns, and failures as they evolve over time. Built on FalkorDB (CPU-friendly graph database) with hybrid search capabilities, it provides unparalleled insights into your project's history, fostering better decision-making and reducing technical debt.

🎯 Value Proposition

• Improved Decision Tracking - Capture the rationale behind architectural choices and their impact over time
• Enhanced Collaboration - Facilitate knowledge sharing and alignment across teams
• Reduced Technical Debt - Identify and address problematic patterns early
• Faster Onboarding - Accelerate learning for new team members with comprehensive project history
• AI-Ready Knowledge Base - Structure knowledge for AI-powered development tools (Claude Code/Desktop)

✨ Key Features

• Temporal Knowledge Graph - Track changes to decisions and patterns over time
• Hybrid Search - Graph traversal + vector embeddings + CrossEncoder reranking (<2s queries)
• Gap Detection - NetworkX-based structural analysis to identify knowledge gaps
• MCP Integration - 12 tools for seamless Claude Desktop/Code integration
• Docker Deployment - One-command startup with auto-restart support
• CPU-Friendly - Built on FalkorDB, no GPU required (gaming-friendly memory footprint)

📖 Documentation

• Integration Setup Guide - Set up Agent Genesis + Faulkner-DB sync
• Contributing Guidelines - How to contribute

🚀 Quick Start

Option 1: Automated NPM Setup (Recommended)

# Configure Claude Desktop/Code automatically
npx faulkner-db-config setup

# Clone and start the stack
git clone https://github.com/platano78/faulkner-db.git
cd faulkner-db/docker
docker-compose up -d

# Restart Claude Desktop/Code

Option 2: Manual Setup

1. Start FalkorDB Stack

git clone https://github.com/platano78/faulkner-db.git
cd faulkner-db/docker

# Copy environment template
cp .env.example .env

# Edit .env and set POSTGRES_PASSWORD

# Start services
docker-compose up -d

2. Configure Claude (Manual)

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or equivalent:

{
  "mcpServers": {
    "faulkner-db": {
      "command": "python3",
      "args": ["-m", "mcp_server.server_fastmcp"],
      "env": {
        "PYTHONPATH": "/path/to/faulkner-db",
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6380",
        "FALKORDB_PASSWORD": "changeme"
      }
    }
  }
}

3. Access Services

• Network Graph: http://localhost:VISUALIZATION_PORT/static/index.html
• Timeline View: http://localhost:VISUALIZATION_PORT/static/timeline.html
• Dashboard: http://localhost:VISUALIZATION_PORT/static/dashboard.html
• API Health: http://localhost:VISUALIZATION_PORT/health

Set VISUALIZATION_PORT and FALKORDB_REST_PORT in docker/.env. See .env.example for defaults.

Security Configuration

Authentication

FalkorDB now requires password authentication for all connections.

Port Configuration

The default port has been changed from 6379 to 6380 to avoid conflicts with standard Redis installations.

Connection Examples

Python

import os
from core.graphiti_client import GraphitiClient

password = os.environ.get('FALKORDB_PASSWORD')
client = GraphitiClient(host='localhost', port=6380, password=password)

redis-cli

redis-cli -p 6380 -a $FALKORDB_PASSWORD

Docker Compose Environment

environment:
  FALKORDB_HOST: falkordb
  FALKORDB_PORT: 6380
  FALKORDB_PASSWORD: ${FALKORDB_PASSWORD}

Destructive Commands Disabled

To prevent accidental data loss, the following commands are disabled in the FalkorDB configuration:

• FLUSHALL - Renamed to an obscure command (not directly callable)
• FLUSHDB - Renamed to an ob