Rebase from SecKatie/FalkorDB-MCPServer #14
Streamline to MCP-only architecture and enhance documentation
- Remove legacy HTTP API components (controllers, routes, middleware) - Clean up Express dependencies from package.json - Simplify graph_list resource to return markdown format - Add comprehensive CLAUDE.md for development guidance - Modernize README with enhanced setup instructions and examples - Focus entirely on MCP server functionality via stdio transport 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Loading branch information
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| # CLAUDE.md | ||
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| ## Development Commands | ||
|
|
||
| - **Build**: `npm run build` - Compiles TypeScript to JavaScript in `dist/` | ||
| - **Dev server**: `npm run dev` - Starts development server with hot-reloading using nodemon | ||
| - **Production start**: `npm start` - Runs the built application from `dist/index.js` | ||
| - **Lint**: `npm run lint` - Runs ESLint on TypeScript files | ||
| - **Test**: `npm test` - Runs Jest test suite | ||
| - **Test with coverage**: `npm test:coverage` - Runs tests with coverage report | ||
|
|
||
| ## Project Architecture | ||
|
|
||
| This is a Model Context Protocol (MCP) server that enables AI models to interact with FalkorDB graph databases through natural language. The server communicates via stdio transport and provides tools for graph operations. | ||
|
|
||
| ### MCP Server Implementation | ||
| - **Entry point**: `src/index.ts` - Creates MCP server using `@modelcontextprotocol/sdk` | ||
| - **Communication**: Uses stdio transport for MCP protocol (not HTTP) | ||
| - **MCP Tools registered**: | ||
| - `query_graph` - Execute OpenCypher queries on specific graphs | ||
| - `list_graphs` - List all available graphs in the database | ||
| - `delete_graph` - Delete specific graphs | ||
| - `set_key`/`get_key` - Redis key-value operations for data storage | ||
| - **MCP Resources**: `graph_list` resource provides markdown-formatted graph listings | ||
|
|
||
| ### Core Services | ||
| - **FalkorDB Service** (`src/services/falkordb.service.ts`): | ||
| - Singleton service managing FalkorDB connections | ||
| - Uses `falkordb` npm package | ||
| - Handles connection retries and pooling | ||
| - Main operations: `executeQuery()`, `listGraphs()`, `deleteGraph()` | ||
|
|
||
| - **Redis Service** (`src/services/redis.service.ts`): | ||
| - Manages Redis operations for key-value storage | ||
| - Used alongside graph operations | ||
|
|
||
| ### Configuration | ||
| - **Config system** (`src/config/index.ts`): Centralized configuration using dotenv | ||
| - **Environment variables**: Defined in `.env` file (copy from `.env.example`) | ||
| - **Key variables**: `FALKORDB_HOST`, `FALKORDB_PORT`, `FALKORDB_USERNAME`, `FALKORDB_PASSWORD` | ||
|
|
||
| ### Current Project Structure | ||
| ``` | ||
| src/ | ||
| ├── index.ts # MCP server entry point with tool/resource registration | ||
| ├── services/ | ||
| │ ├── falkordb.service.ts # FalkorDB connection and graph operations | ||
| │ └── redis.service.ts # Redis key-value operations | ||
| ├── config/ | ||
| │ └── index.ts # Centralized configuration using dotenv | ||
| ├── models/ # TypeScript type definitions | ||
| │ ├── mcp.types.ts # MCP protocol interfaces | ||
| │ └── mcp-client-config.ts # Configuration models | ||
| └── utils/ | ||
| └── connection-parser.ts # Utility functions | ||
| ``` | ||
|
|
||
| ## Testing | ||
| - **Framework**: Jest with ts-jest preset | ||
| - **Test files**: Located alongside source files with `.test.ts` extension | ||
| - **Coverage**: Configured to exclude test files and type definitions | ||
| - **Test environment**: Node.js environment | ||
|
|
||
| ## Key Dependencies | ||
| - `@modelcontextprotocol/sdk` - MCP protocol implementation | ||
| - `falkordb` - FalkorDB Node.js client | ||
| - `zod` - Schema validation for MCP tools | ||
|
|
||
| ## MCP Integration Setup | ||
|
|
||
| ### Claude Desktop Configuration | ||
| To use this server with Claude Desktop, add to `claude_desktop_config.json`: | ||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "falkordb": { | ||
| "command": "node", | ||
| "args": ["/absolute/path/to/falkordb-mcpserver/dist/index.js"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Environment Configuration | ||
| Required environment variables in `.env`: | ||
| - `FALKORDB_HOST` - FalkorDB hostname (default: localhost) | ||
| - `FALKORDB_PORT` - FalkorDB port (default: 6379) | ||
| - `FALKORDB_USERNAME` - Optional authentication | ||
| - `FALKORDB_PASSWORD` - Optional authentication | ||
| - `REDIS_URL` - Redis connection for key-value operations | ||
|
|
||
| ## Development Notes | ||
| - Uses ES modules (`"type": "module"` in package.json) | ||
| - TypeScript configuration in `tsconfig.json` | ||
| - Nodemon watches `src/**/*.ts` for development hot-reload | ||
| - **Important**: This is an MCP server, not a web server - it communicates via stdio transport | ||
| - Build output in `dist/` directory is executed by MCP clients | ||
| - The server automatically closes FalkorDB and Redis connections on exit | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,118 +1,230 @@ | ||
| # FalkorDB MCP Server | ||
|
|
||
| > 🚀 **Connect AI models to FalkorDB graph databases through the Model Context Protocol** | ||
|
|
||
| [](https://opensource.org/licenses/MIT) | ||
| [](https://modelcontextprotocol.io) | ||
|
|
||
| FalkorDB MCP Server enables AI assistants like Claude to interact with FalkorDB graph databases using natural language. Query your graph data, create relationships, and manage your knowledge graph - all through conversational AI. | ||
|
|
||
| ## 🎯 What is this? | ||
|
|
||
| This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing AI models to: | ||
| - **Query graph databases** using OpenCypher | ||
| - **Create and manage** nodes and relationships | ||
| - **Store and retrieve** key-value data | ||
| - **List and explore** multiple graphs | ||
| - **Delete graphs** when needed | ||
|
|
||
| ## 🚀 Quick Start | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - Node.js 16+ | ||
|
gkorland marked this conversation as resolved.
Outdated
|
||
| - FalkorDB instance (running locally or remotely) | ||
| - Claude Desktop app (for AI integration) | ||
|
|
||
| ### Installation | ||
|
|
||
| 1. **Clone and install:** | ||
| ```bash | ||
| git clone https://github.com/falkordb/falkordb-mcpserver.git | ||
| cd falkordb-mcpserver | ||
| npm install | ||
| ``` | ||
|
|
||
| 2. **Configure environment:** | ||
| ```bash | ||
| cp .env.example .env | ||
| ``` | ||
|
|
||
| Edit `.env`: | ||
| ```env | ||
| # FalkorDB Connection | ||
| FALKORDB_HOST=localhost | ||
| FALKORDB_PORT=6379 | ||
| FALKORDB_USERNAME= # Optional | ||
| FALKORDB_PASSWORD= # Optional | ||
|
|
||
| # Redis Connection (for key-value storage) | ||
| REDIS_URL=redis://localhost:6379 | ||
| REDIS_USERNAME= # Optional | ||
| REDIS_PASSWORD= # Optional | ||
| ``` | ||
|
|
||
| 3. **Build the project:** | ||
| ```bash | ||
| npm run build | ||
| ``` | ||
|
|
||
| ## 🤖 Claude Desktop Integration | ||
|
|
||
| Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "falkordb": { | ||
| "command": "node", | ||
| "args": [ | ||
| "/absolute/path/to/falkordb-mcpserver/dist/index.js" | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Restart Claude Desktop and you'll see the FalkorDB tools available! | ||
|
|
||
| ## 📚 Available MCP Tools | ||
|
|
||
| Once connected, you can ask Claude to: | ||
|
|
||
| ### 🔍 Query Graphs | ||
| ``` | ||
| "Show me all people who know each other" | ||
| "Find the shortest path between two nodes" | ||
| "What relationships does John have?" | ||
| ``` | ||
|
|
||
| ### 📝 Manage Data | ||
| ``` | ||
| "Create a new person named Alice who knows Bob" | ||
| "Add a 'WORKS_AT' relationship between Alice and TechCorp" | ||
| "Store my API key in the database" | ||
| ``` | ||
|
|
||
| ### 📊 Explore Structure | ||
| ``` | ||
| "List all available graphs" | ||
| "Show me the structure of the user_data graph" | ||
| "Delete the old_test graph" | ||
| ``` | ||
|
|
||
| ## 🛠️ Development | ||
|
|
||
| ### Commands | ||
|
|
||
| ```bash | ||
| # Development with hot-reload | ||
| npm run dev | ||
|
|
||
| # Run tests | ||
| npm test | ||
|
|
||
| # Lint code | ||
| npm run lint | ||
|
|
||
| # Build for production | ||
| npm run build | ||
|
|
||
| # Start production server | ||
| npm start | ||
| ``` | ||
|
|
||
| ### Project Structure | ||
|
|
||
| ``` | ||
| src/ | ||
| ├── index.ts # MCP server entry point | ||
| ├── services/ | ||
| │ ├── falkordb.service.ts # FalkorDB operations | ||
| │ └── redis.service.ts # Key-value operations | ||
| ├── config/ | ||
| │ └── index.ts # Configuration management | ||
| ├── models/ # TypeScript type definitions | ||
| └── utils/ # Utility functions | ||
| ``` | ||
|
|
||
| ## 🔧 Advanced Configuration | ||
|
|
||
| ### Using with Remote FalkorDB | ||
|
|
||
| For cloud-hosted FalkorDB instances: | ||
|
|
||
| ```env | ||
| FALKORDB_HOST=your-instance.falkordb.com | ||
| FALKORDB_PORT=6379 | ||
| FALKORDB_USERNAME=your-username | ||
| FALKORDB_PASSWORD=your-secure-password | ||
| ``` | ||
|
|
||
| ### Running Multiple Instances | ||
|
|
||
| You can run multiple MCP servers for different FalkorDB instances: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "falkordb-dev": { | ||
| "command": "node", | ||
| "args": ["path/to/server/dist/index.js"], | ||
| "env": { | ||
| "FALKORDB_HOST": "dev.falkordb.local" | ||
| } | ||
| }, | ||
| "falkordb-prod": { | ||
| "command": "node", | ||
| "args": ["path/to/server/dist/index.js"], | ||
| "env": { | ||
| "FALKORDB_HOST": "prod.falkordb.com" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## 📖 Example Usage | ||
|
|
||
| Here's what you can do once connected: | ||
|
|
||
| ```cypher | ||
| // Claude can help you write queries like: | ||
| MATCH (p:Person)-[:KNOWS]->(friend:Person) | ||
| WHERE p.name = 'Alice' | ||
| RETURN friend.name, friend.age | ||
|
|
||
| // Or create complex data structures: | ||
| CREATE (alice:Person {name: 'Alice', age: 30}) | ||
| CREATE (bob:Person {name: 'Bob', age: 25}) | ||
| CREATE (alice)-[:KNOWS {since: 2020}]->(bob) | ||
|
|
||
| // And even analyze your graph: | ||
| MATCH path = shortestPath((start:Person)-[*]-(end:Person)) | ||
| WHERE start.name = 'Alice' AND end.name = 'Charlie' | ||
| RETURN path | ||
| ``` | ||
|
|
||
| ## 🤝 Contributing | ||
|
|
||
| We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details. | ||
|
|
||
| ### Development Workflow | ||
|
|
||
| 1. Fork the repository | ||
| 2. Create a feature branch (`git checkout -b feature/amazing-feature`) | ||
| 3. Commit your changes (`git commit -m 'Add amazing feature'`) | ||
| 4. Push to the branch (`git push origin feature/amazing-feature`) | ||
| 5. Open a Pull Request | ||
|
|
||
| ## 📝 License | ||
|
|
||
| This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. | ||
|
|
||
| ## 🙏 Acknowledgments | ||
|
|
||
| - Built on the [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol) | ||
| - Powered by [FalkorDB](https://www.falkordb.com/) | ||
| - Inspired by the growing MCP ecosystem | ||
|
|
||
| ## 🔗 Resources | ||
|
|
||
| - [FalkorDB Documentation](https://docs.falkordb.com) | ||
| - [MCP Specification](https://modelcontextprotocol.io/docs) | ||
| - [OpenCypher Query Language](https://opencypher.org/) | ||
|
|
||
| --- | ||
|
|
||
| <p align="center"> | ||
| Made with ❤️ by the FalkorDB team & Katie Mulliken | ||
| </p> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.