Bi-Temporal Knowledge Graph MCP Server

# Quick Start Guide Get your Bi-Temporal Knowledge Graph MCP Server up and running in 5 minutes! ## Prerequisites Checklist - [ ] Python 3.9 or higher installed - [ ] FalkorDB or Redis with FalkorDB module running - [ ] (Optional) PostgreSQL database for tool generation - [ ] (Optional) OpenAI API key for entity extraction ## Step 1: Install Dependencies ```bash pip install -r requirements.txt ``` ## Step 2: Configure Environment Copy the example environment file and customize it: ```bash cp .env.example .env ``` Edit `.env` with your values: ```bash # Minimum configuration (required) FALKORDB_HOST=localhost FALKORDB_PORT=6379 FALKORDB_DATABASE=graphiti # Optional but recommended OPENAI_API_KEY=sk-your-key-here ``` ## Step 3: Start FalkorDB ### Option A: Using Docker ```bash docker run -d -p 6379:6379 falkordb/falkordb:latest ``` ### Option B: Using Redis with FalkorDB Module ```bash redis-server --loadmodule /path/to/falkordb.so ``` ### Option C: Using Managed FalkorDB Update `FALKORDB_HOST` in `.env` with your managed instance URL. ## Step 4: (Optional) Set Up PostgreSQL If you want to use the dynamic tool generation feature: ### Using Docker: ```bash docker run -d \ -e POSTGRES_PASSWORD=yourpassword \ -p 5432:5432 \ postgres:15 ``` ### Update .env: ```bash POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=automation_db POSTGRES_USER=postgres POSTGRES_PASSWORD=yourpassword ``` ### Seed the database: ```bash python seed_db.py ``` ## Step 5: Start the Server ```bash python main.py ``` You should see: ``` ╔═══════════════════════════════════════════════════════════════╗ ║ Bi-Temporal Knowledge Graph MCP Server ║ ║ with Dynamic Automation Tool Generator ║ ╚═══════════════════════════════════════════════════════════════╝ 🚀 Starting server on 0.0.0.0:8080 📡 MCP endpoint: sse ``` ## Step 6: Test the Server ### Using Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac): ```json { "mcpServers": { "bitemporal-graph": { "url": "http://localhost:8080/sse" } } } ``` ### Using cURL ```bash # Check server status curl -X POST http://localhost:8080/sse \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_status", "arguments": {} } }' ``` ## Step 7: Try It Out! ### Add Your First Fact ```python # Via MCP tool await add_fact( source_entity="Alice", relation="works at", target_entity="Acme Corp", session_id="test_session" ) ``` ### Use AI Entity Extraction ```python # AI automatically extracts entities await add_message( content="Bob moved to San Francisco and joined Google as a software engineer", session_id="test_session" ) ``` ### Query the Knowledge Graph ```python # Get current facts await query_facts(entity_name="Bob") # Query historical state await query_at_time( timestamp="2024-01-01T00:00:00Z", entity_name="Bob" ) ``` ### Generate a Dynamic Tool ```python # Generate a tool from database config await generate_tool_from_db( user_id="demo_user", item_name="Slack Notification", item_type="single" ) # Use the generated tool await slack_notification( message="Hello from MCP!", channel="#general" ) ``` ## Troubleshooting ### "Cannot connect to FalkorDB" - Check if FalkorDB is running: `redis-cli -h localhost -p 6379 ping` - Verify `FALKORDB_HOST` and `FALKORDB_PORT` in `.env` ### "OpenAI API error" - Verify `OPENAI_API_KEY` is set correctly - Check your OpenAI account has credits ### "PostgreSQL connection failed" - This is optional - server will work without it - If needed, verify PostgreSQL is running and credentials are correct ## Next Steps 1. 📖 Read the full [README.md](README.md) for detailed documentation 2. 🔧 Customize the configuration for your use case 3. 🚀 Deploy to production (Replit, Railway, Render, etc.) 4. 🤝 Contribute improvements back to the project ## Common Use Cases ### Personal Knowledge Management Store and query facts about your life, work, and relationships with temporal tracking. ### Customer Relationship Management Track customer interactions, preferences, and history with automatic conflict resolution. ### Workflow Automation Combine knowledge graph queries with webhook tools to create intelligent automation workflows. ### AI Agent Memory Provide your AI agents with persistent, queryable memory that understands time and context. ## Support - 📖 Documentation: See [README.md](README.md) - 🐛 Issues: Open a GitHub issue - 💬 Questions: Check existing issues or start a discussion --- Happy building! 🎉