kuzudb-mcp-server

# Archive Notice ## Status: Archived This project has been archived as of October 21, 2025. ## Reason The Kuzu graph database repository has been archived by its maintainers as of October 10, 2025. The repository is now read-only with no further updates planned. **Official Repository**: https://github.com/kuzudb/kuzu > "This repository was archived by the owner on Oct 10, 2025. It is now read-only." As Kuzu is no longer actively maintained, this MCP server built around it is also being archived. ## What Was Built This project successfully implemented a production-ready MCP server for Kuzu with significant features: ### Core Features Implemented - **Robust Connection Management**: Automatic recovery with exponential backoff (1s → 2s → 4s delays) - **Multi-Agent Coordination**: File-based locking for safe concurrent access from multiple AI agents - **Dual Transport Support**: Both stdio (Claude Desktop) and HTTP (remote access) modes - **Web UI**: Complete database management interface with backup/restore capabilities - **Authentication**: OAuth and Basic Auth support for secure deployments - **Docker Integration**: Pre-built images and docker-compose workflow - **Error Recovery**: Automatic handling of Parser/Binder errors and connection failures - **Query Validation**: MERGE query validation to prevent database crashes - **Health Monitoring**: Built-in health checks and monitoring endpoints ### Implementation Status **Fully Functional** - All planned features completed and tested: - ✅ Connection recovery and retry logic - ✅ Multi-agent file-based locking - ✅ Web UI with authentication - ✅ OAuth and Basic Auth - ✅ Docker images and compose files - ✅ Comprehensive test suite - ✅ Documentation and examples - ✅ Published to npm and Docker registry - ✅ Smithery package support ### Technical Achievements 1. **Connection Recovery Architecture** (docs/connection-recovery.md) - Process-level error recovery - Parser/Binder exception handling - Health monitoring with validation queries - Exponential backoff retry logic 2. **Multi-Agent Coordination** (docs/Multi-Agent Coordination Design for kuzudb-mcp-server.md) - File-based write locks - Stale lock detection and cleanup - Lock-free read operations - Clear error messages for lock conflicts 3. **Kuzu Bug Workarounds** (kuzu-bug-report/KUZU_BUG_WORKAROUNDS.md) - DDL timeout handling (`getAll()` hang bug) - BigInt serialization fixes - MERGE query validation 4. **Production Features** - JWT token authentication with configurable expiration - Web UI with backup/restore capabilities - Docker health checks - Comprehensive environment variable configuration ## Future Considerations For users who were using this server: ### Current Options 1. **Continue using current version**: The server works perfectly with existing Kuzu databases (v1.4.1-r.4) 2. **Fork and maintain**: All source code is MIT licensed and well-documented 3. **Migrate to alternatives**: Consider Neo4j, ArangoDB, or other graph databases with active maintenance ### Alternative Graph Databases - **Neo4j**: Most popular graph database with extensive tooling - **ArangoDB**: Multi-model database with graph capabilities - **MemGraph**: High-performance in-memory graph database - **TypeDB**: Knowledge graph with type system - **JanusGraph**: Distributed graph database ## Technical Learnings ### What Worked Exceptionally Well 1. **FastMCP Framework** (`@jordanburke/fastmcp`): Simplified HTTP transport implementation significantly 2. **Connection Recovery Pattern**: Exponential backoff with health validation proved robust 3. **Multi-Agent File Locking**: Simple and effective for local concurrent access 4. **Web UI Integration**: Provided significant value for database management 5. **Docker Containerization**: Made deployment straightforward ### Challenges Overcome 1. **Kuzu `getAll()` hang bug**: Implemented 5-second timeout workaround 2. **BigInt JSON serialization**: Custom replacer for JSON.stringify 3. **MERGE query crashes**: Pre-execution validation with schema caching 4. **Multi-agent coordination**: File-based locks with stale detection 5. **Connection corruption**: Parser/Binder error recovery without restart ### Architecture Patterns Worth Reusing 1. **MCP Server Structure**: - `src/server-core.ts` - Database abstraction layer - `src/server-fastmcp.ts` - HTTP transport - `src/index.ts` - CLI and configuration - `src/lock-manager.ts` - Coordination logic 2. **Error Recovery Flow**: ```typescript Query Request → Health Check ↓ (if invalid) Discard Connection → Create New → Validate ↓ Retry with Backoff → Return Results ``` 3. **Web UI Integration**: - Separate port (3001) from MCP endpoint (3000) - Optional authentication - RESTful API design - File upload/download handling ### Performance Metrics Achieved Based on testing with movie database (1000+ nodes): - Simple queries: < 100ms - Complex multi-hop: 200-500ms - Schema retrieval: 100-200ms - Connection recovery: < 2 seconds ## Repository Preservation This repository will remain available as: - **Reference Implementation**: Example of production-ready MCP server - **Architecture Template**: Patterns applicable to other database MCP servers - **Historical Record**: Snapshot of Kuzu integration before archival ## Acknowledgments Thanks to: - The Kuzu team for building an excellent graph database - The MCP community for the protocol specification - Contributors and users who tested and provided feedback ## License MIT License - See LICENSE file for details --- **Last Updated**: October 21, 2025 **Final Version**: Published to npm and Docker registry **Status**: Archived but fully functional **Kuzu Version**: v1.4.1-r.4 (last supported version)