Bi-Temporal Knowledge Graph MCP Server

# PROJECT SUMMARY ## Bi-Temporal Knowledge Graph MCP Server with Dynamic Tool Generator **Version:** 1.0.0 **Created:** December 2024 **License:** MIT --- ## 📦 Package Contents This package contains a complete, production-ready implementation of a Bi-Temporal Knowledge Graph MCP Server with Dynamic Automation Tool Generator. ### Core Application Files (3) 1. **memory.py** (33KB) - Bi-temporal Graphiti memory implementation - FalkorDB driver with connection pooling - Session store with TTL management - OpenAI entity extractor - Smart conflict resolution - Background cleanup manager 2. **tools.py** (5.5KB) - Dynamic tool container - Utility functions for webhook execution - Single and parallel webhook helpers - Auto-generated tools appended here at runtime 3. **main.py** (31KB) - FastMCP server orchestrator - Core memory tools registration - PostgreSQL database interface - Tool code generator (deterministic) - Dynamic tool loader - Lifecycle management (startup/shutdown) ### Documentation Files (4) 4. **README.md** (16KB) - Comprehensive project documentation - Architecture overview - Database schemas - Usage guide with examples - API reference - Advanced configuration 5. **QUICKSTART.md** (5KB) - 5-minute setup guide - Step-by-step installation - Quick examples - Troubleshooting 6. **DEPLOYMENT.md** (9KB) - Platform-specific deployment guides - Replit Autoscale - Railway, Render, Fly.io - Docker Compose - Manual/VPS deployment - Production checklist 7. **LICENSE** (1KB) - MIT License - Open source, commercial use allowed ### Configuration Files (4) 8. **.env.example** (600B) - Environment variables template - All configuration options documented - Easy copy-paste setup 9. **.gitignore** (250B) - Git ignore patterns - Python, IDE, OS files - Sensitive data protection 10. **requirements.txt** (512B) - Python dependencies - Version specifications - Production-ready 11. **docker-compose.yml** (2.5KB) - Complete stack definition - FalkorDB + PostgreSQL + MCP Server - Health checks included - Volume management ### Deployment Files (2) 12. **Dockerfile** (1KB) - Production-ready image - Multi-stage optimization - Non-root user - Health checks 13. **seed_db.py** (7.5KB) - Database seeding script - Example webhook configurations - Template creation - Easy testing setup ### Example Files (1) 14. **examples.py** (14KB) - 8 comprehensive scenarios - Interactive demonstrations - Best practices showcase - Testing templates --- ## 🎯 Key Features Delivered ### Bi-Temporal Memory System ✅ Full temporal tracking (created_at, valid_at, invalid_at, expired_at) ✅ Smart conflict resolution for location/employment changes ✅ Session-aware episodic memory ✅ Automatic fact invalidation ✅ TTL-based session management (30 min default) ✅ Memory-bounded session store (configurable limits) ✅ Idle connection management ### AI-Powered Features ✅ OpenAI entity extraction from natural language ✅ Automatic relationship discovery ✅ Configurable extraction prompts ✅ Graceful degradation without OpenAI ### Dynamic Tool Generation ✅ Database-driven tool configuration (PostgreSQL) ✅ Single webhook template implementation ✅ Multi-webhook parallel execution template ✅ Deterministic code generation ✅ Sanitized function names ✅ Auto-generated docstrings ✅ Hot-reload capability ### Production-Ready Architecture ✅ FastMCP server with SSE transport ✅ FalkorDB knowledge graph backend ✅ PostgreSQL webhook configuration storage ✅ Thread-safe session management ✅ Background cleanup tasks ✅ Comprehensive error handling ✅ Resource management for Autoscale ✅ Docker & Docker Compose support --- ## 🚀 Quick Start ### Minimum Setup (3 steps) ```bash # 1. Install dependencies pip install -r requirements.txt # 2. Configure (minimum: just FalkorDB) cp .env.example .env # Edit: FALKORDB_HOST=localhost # 3. Run python main.py ``` ### Full Setup (Docker Compose) ```bash # One command starts everything docker-compose up -d # Includes: FalkorDB + PostgreSQL + MCP Server ``` ### With Tool Generation ```bash # 1. Configure PostgreSQL in .env # 2. Seed example webhooks python seed_db.py # 3. Start server python main.py # 4. Generate tools (via MCP) generate_tool_from_db("demo_user", "Slack Notification") ``` --- ## 📊 Technical Specifications ### System Requirements - Python 3.9 or higher - FalkorDB (or Redis with FalkorDB module) - PostgreSQL 12+ (optional, for tool generation) - OpenAI API key (optional, for entity extraction) ### Performance Characteristics - **Memory Usage**: Bounded by MAX_SESSIONS (default: 1000) - **Session TTL**: 30 minutes (configurable) - **Cleanup Interval**: 5 minutes (configurable) - **Connection Timeout**: 10 minutes idle (configurable) - **Parallel Webhooks**: Async execution with asyncio.gather - **Entity Extraction**: ~1-2s per message with OpenAI ### Scalability - Horizontal scaling via group_id partitioning - Stateless design (session store can be externalized) - Connection pooling for database efficiency - Automatic resource cleanup - Designed for Replit Autoscale --- ## 🏗️ Architecture Overview ``` ┌─────────────────────────────────────────────────────────┐ │ FastMCP Server │ │ (main.py) │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌────────────────┐ ┌──────────────────┐ │ │ │ Memory Tools │ │ Dynamic Tools │ │ │ │ (memory.py) │ │ (tools.py) │ │ │ └────────┬───────┘ └────────┬─────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Tool Code Generator │ │ │ │ (generate_mcp_tool_code_from_db) │ │ │ └─────────────────────────────────────────────┘ │ │ │ └──────────────┬───────────────────┬─────────────────────┘ │ │ ▼ ▼ ┌────────────────┐ ┌──────────────┐ │ FalkorDB │ │ PostgreSQL │ │ (Knowledge │ │ (Webhook │ │ Graph) │ │ Configs) │ └────────────────┘ └──────────────┘ ``` --- ## 📋 Database Schemas ### FalkorDB (Graph Database) **Nodes:** - EntityNode: Entities with `name`, `group_id`, timestamps - EpisodicNode: Sessions with `session_id`, `message_count`, status **Relationships:** - RELATES_TO: Facts with bi-temporal tracking - MENTIONS: Links episodes to entities ### PostgreSQL (Relational Database) **Tables:** - webhooks: Single webhook configurations - webhook_templates: Multi-webhook configurations --- ## 🔧 Configuration Options All configurable via environment variables: **Required:** - FALKORDB_HOST, FALKORDB_PORT, FALKORDB_DATABASE **Optional - AI:** - OPENAI_API_KEY, OPENAI_MODEL **Optional - Tools:** - POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD **Optional - Tuning:** - SESSION_TTL_MINUTES (default: 30) - MAX_SESSIONS (default: 1000) - CLEANUP_INTERVAL_SECONDS (default: 300) - CONNECTION_IDLE_TIMEOUT (default: 600) --- ## 🧪 Testing ### Run Examples ```bash python examples.py ``` ### Manual Testing ```bash # Start server python main.py # In another terminal 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":{}}}' ``` --- ## 📚 Learning Path 1. **Start Here**: QUICKSTART.md (5 minutes) 2. **Understand**: README.md (15 minutes) 3. **Explore**: examples.py (interactive) 4. **Deploy**: DEPLOYMENT.md (platform-specific) 5. **Customize**: Modify memory.py and main.py --- ## 🤝 Support & Contribution ### Getting Help - Read documentation thoroughly - Check examples.py for usage patterns - Review logs for error details - Open GitHub issues for bugs ### Contributing Areas for improvement: - Additional temporal operators - Enhanced entity extraction - More webhook templates - Performance optimizations - Additional deployment guides --- ## 📦 Package Verification **Total Files:** 14 **Total Size:** ~133KB **Languages:** Python, YAML, Markdown **Dependencies:** 7 core, 3 optional **File Integrity:** - ✅ All core files present - ✅ Documentation complete - ✅ Examples included - ✅ Deployment configs ready - ✅ License included (MIT) --- ## 🎓 What You Get ### Immediate Use - Production-ready MCP server - Bi-temporal knowledge graph - AI-powered entity extraction - Dynamic tool generation - Complete documentation ### Learning Resources - 8 comprehensive examples - Best practices demonstrated - Architecture patterns - Deployment strategies ### Extensibility - Clean, modular code - Well-documented functions - Easy customization points - Plugin-friendly design --- ## 🚀 Next Steps 1. **Quick Test**: Follow QUICKSTART.md 2. **Explore**: Run examples.py 3. **Customize**: Edit configurations 4. **Deploy**: Choose your platform from DEPLOYMENT.md 5. **Build**: Create your own tools and workflows --- ## 📞 Contact & Links - **Documentation**: See README.md - **Issues**: GitHub issue tracker - **License**: MIT (commercial use allowed) - **Built With**: FastMCP, FalkorDB, OpenAI --- **Ready to deploy your intelligent, temporal knowledge graph!** 🎉 Built with ❤️ for the MCP ecosystem