docs: Update README with comprehensive features and database options

- Add comprehensive features list including all supported databases, LLM providers, and transports
- Document Kuzu as the default database with explanation of its benefits and archived status
- Add detailed instructions for running with different databases (Kuzu, Neo4j, FalkorDB)
- Update transport references from SSE to HTTP (default transport)
- Add database-specific Docker Compose instructions
- Update MCP client configurations to use /mcp/ endpoint
- Clarify prerequisites to reflect optional nature of external databases
- Add detailed database configuration examples for all supported backends

mcp_server/README.md

@@ -13,13 +13,20 @@ graph capabilities.
 
 ## Features
 
-The Graphiti MCP server exposes the following key high-level functions of Graphiti:
+The Graphiti MCP server provides comprehensive knowledge graph capabilities:
 
 - **Episode Management**: Add, retrieve, and delete episodes (text, messages, or JSON data)
 - **Entity Management**: Search and manage entity nodes and relationships in the knowledge graph
 - **Search Capabilities**: Search for facts (edges) and node summaries using semantic and hybrid search
 - **Group Management**: Organize and manage groups of related data with group_id filtering
 - **Graph Maintenance**: Clear the graph and rebuild indices
+- **Graph Database Support**: Multiple backend options including Kuzu (default), Neo4j, and FalkorDB
+- **Multiple LLM Providers**: Support for OpenAI, Anthropic, Gemini, Groq, and Azure OpenAI
+- **Multiple Embedding Providers**: Support for OpenAI, Voyage, Sentence Transformers, and Gemini embeddings
+- **Custom Entity Types**: Define and use custom entity types for domain-specific knowledge extraction
+- **HTTP Transport**: Default HTTP transport with MCP endpoint at `/mcp/` for broad client compatibility
+- **Queue-based Processing**: Asynchronous episode processing with configurable concurrency limits
+- **Telemetry**: Optional anonymous usage statistics to help improve the framework
 
 ## Quick Start
 
@@ -47,25 +54,33 @@ cd graphiti && pwd
 
 3. Configure Claude, Cursor, or other MCP client to use [Graphiti with a `stdio` transport](#integrating-with-mcp-clients). See the client documentation on where to find their MCP configuration files.
 
-### For Cursor and other `sse`-enabled clients
+### For Cursor and other HTTP-enabled clients
 
 1. Change directory to the `mcp_server` directory
 
 `cd graphiti/mcp_server`
 
-2. Start the service using Docker Compose
+2. Option A: Run with default Kuzu database (no Docker required)
 
-`docker compose up`
+```bash
+uv run graphiti_mcp_server.py
+```
 
-3. Point your MCP client to `http://localhost:8000/sse`
+3. Option B: Run with Neo4j using Docker Compose
+
+```bash
+docker compose up  # or docker compose -f docker/docker-compose-neo4j.yml up
+```
+
+4. Point your MCP client to `http://localhost:8000/mcp/`
 
 ## Installation
 
 ### Prerequisites
 
 1. Ensure you have Python 3.10 or higher installed.
-2. A running Neo4j database (version 5.26 or later required)
+2. OpenAI API key for LLM operations (or API keys for other supported LLM providers)
-3. OpenAI API key for LLM operations
+3. (Optional) A running Neo4j or FalkorDB instance if you prefer not to use the default Kuzu database
 
 ### Setup
 
@@ -87,17 +102,76 @@ uv sync --extra providers
 
 The server can be configured using a `config.yaml` file, environment variables, or command-line arguments (in order of precedence).
 
+### Default Configuration
+
+The MCP server comes with sensible defaults:
+- **Transport**: HTTP (accessible at `http://localhost:8000/mcp/`)
+- **Database**: Kuzu (in-memory, no external dependencies required)
+- **LLM**: OpenAI with model gpt-4.1
+- **Embedder**: OpenAI text-embedding-ada-002
+
+### Database Configuration
+
+#### Kuzu (Default)
+
+The server defaults to using Kuzu, an embedded graph database that runs in-memory without requiring any external services. While the Kuzu project has been archived by its original authors, we continue to use it as the default because:
+- It requires no external dependencies or containers
+- It runs entirely in-memory, making it perfect for development and testing
+- It's fully self-contained within the Python environment
+- We're hopeful the community will continue maintaining this excellent project
+
+```yaml
+database:
+  provider: "kuzu"  # Default - no additional setup required
+  providers:
+    kuzu:
+      db: ":memory:"  # In-memory database (default)
+      # Or use a persistent file: db: "/path/to/database.kuzu"
+```
+
+#### Neo4j
+
+For production use or when you need a full-featured graph database, Neo4j is recommended:
+
+```yaml
+database:
+  provider: "neo4j"
+  providers:
+    neo4j:
+      uri: "bolt://localhost:7687"
+      username: "neo4j"
+      password: "your_password"
+      database: "neo4j"  # Optional, defaults to "neo4j"
+```
+
+#### FalkorDB
+
+FalkorDB is another graph database option based on Redis:
+
+```yaml
+database:
+  provider: "falkordb"
+  providers:
+    falkordb:
+      uri: "redis://localhost:6379"
+      password: ""  # Optional
+      database: "default_db"  # Optional
+```
+
 ### Configuration File (config.yaml)
 
 The server supports multiple LLM providers (OpenAI, Anthropic, Gemini, Groq) and embedders. Edit `config.yaml` to configure:
 
 ```yaml
+server:
+  transport: "http"  # Default. Options: stdio, http
+
 llm:
   provider: "openai"  # or "anthropic", "gemini", "groq", "azure_openai"
-  model: "gpt-4o"
+  model: "gpt-4.1"  # Default model
-  
+
 database:
-  provider: "neo4j"  # or "falkordb" (requires additional setup)
+  provider: "kuzu"  # Default. Options: "neo4j", "falkordb"
 ```
 
 ### Using Ollama for Local LLM
@@ -135,27 +209,85 @@ You can set these variables in a `.env` file in the project directory.
 
 ## Running the Server
 
-To run the Graphiti MCP server directly using `uv`:
+### Default Setup (Kuzu Database)
+
+To run the Graphiti MCP server with the default Kuzu in-memory database:
 
 ```bash
 uv run graphiti_mcp_server.py
 ```
 
-With options:
+This starts the server with:
+- HTTP transport on `http://localhost:8000/mcp/`
+- Kuzu in-memory database (no external dependencies)
+- OpenAI LLM with gpt-4.1 model
+
+### Running with Neo4j
+
+#### Option 1: Using Docker Compose
+
+The easiest way to run with Neo4j is using the provided Docker Compose configuration:
 
 ```bash
-uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse
+# This starts both Neo4j and the MCP server
+docker compose -f docker/docker-compose.neo4j.yaml up
 ```
 
-Available arguments:
+#### Option 2: Direct Execution with Existing Neo4j
+
+If you have Neo4j already running:
+
+```bash
+# Set environment variables
+export NEO4J_URI="bolt://localhost:7687"
+export NEO4J_USER="neo4j"
+export NEO4J_PASSWORD="your_password"
+
+# Run with Neo4j
+uv run graphiti_mcp_server.py --database-provider neo4j
+```
+
+Or use the Neo4j configuration file:
+
+```bash
+uv run graphiti_mcp_server.py --config config/config-docker-neo4j.yaml
+```
+
+### Running with FalkorDB
+
+#### Option 1: Using Docker Compose
+
+```bash
+# This starts both FalkorDB (Redis-based) and the MCP server
+docker compose -f docker/docker-compose.falkordb.yaml up
+```
+
+#### Option 2: Direct Execution with Existing FalkorDB
+
+```bash
+# Set environment variables
+export FALKORDB_URI="redis://localhost:6379"
+export FALKORDB_PASSWORD=""  # If password protected
+
+# Run with FalkorDB
+uv run graphiti_mcp_server.py --database-provider falkordb
+```
+
+Or use the FalkorDB configuration file:
+
+```bash
+uv run graphiti_mcp_server.py --config config/config-docker-falkordb.yaml
+```
+
+### Available Command-Line Arguments
 
 - `--config`: Path to YAML configuration file (default: config.yaml)
 - `--llm-provider`: LLM provider to use (openai, anthropic, gemini, groq, azure_openai)
 - `--embedder-provider`: Embedder provider to use (openai, azure_openai, gemini, voyage)
-- `--database-provider`: Database provider to use (neo4j, falkordb)
+- `--database-provider`: Database provider to use (kuzu, neo4j, falkordb) - default: kuzu
 - `--model`: Model name to use with the LLM client
 - `--temperature`: Temperature setting for the LLM (0.0-2.0)
-- `--transport`: Choose the transport method (sse or stdio, default: sse)
+- `--transport`: Choose the transport method (http or stdio, default: http)
 - `--group-id`: Set a namespace for the graph (optional). If not provided, defaults to "main"
 - `--destroy-graph`: If set, destroys all Graphiti graphs on startup
 - `--use-custom-entities`: Enable entity extraction using the predefined ENTITY_TYPES
@@ -169,8 +301,7 @@ If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT
 
 ### Docker Deployment
 
-The Graphiti MCP server can be deployed using Docker. The Dockerfile uses `uv` for package management, ensuring
+The Graphiti MCP server can be deployed using Docker with your choice of database backend. The Dockerfile uses `uv` for package management, ensuring consistent dependency installation.
-consistent dependency installation.
 
 #### Environment Configuration
 
@@ -186,7 +317,7 @@ Before running the Docker Compose setup, you need to configure the environment v
      ```
      # Required for LLM operations
      OPENAI_API_KEY=your_openai_api_key_here
-     MODEL_NAME=gpt-4.1-mini
+     MODEL_NAME=gpt-4.1
      # Optional: OPENAI_BASE_URL only needed for non-standard OpenAI endpoints
      # OPENAI_BASE_URL=https://api.openai.com/v1
      ```
@@ -195,41 +326,57 @@ Before running the Docker Compose setup, you need to configure the environment v
 2. **Using environment variables directly**:
    - You can also set the environment variables when running the Docker Compose command:
      ```bash
-     OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
+     OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1 docker compose up
      ```
 
-#### Neo4j Configuration
+#### Database Options with Docker Compose
 
-The Docker Compose setup includes a Neo4j container with the following default configuration:
+A Graphiti MCP container is available at: `zepai/knowledge-graph-mcp`.
 
-- Username: `neo4j`
+##### Default: Kuzu Database
-- Password: `demodemo`
-- URI: `bolt://neo4j:7687` (from within the Docker network)
-- Memory settings optimized for development use
 
-#### Running with Docker Compose
+The default `docker-compose.yml` uses Kuzu (in-memory database):
-
-A Graphiti MCP container is available at: `zepai/knowledge-graph-mcp`. The latest build of this container is used by the Compose setup below.
-
-Start the services using Docker Compose:
 
 ```bash
 docker compose up
 ```
 
-Or if you're using an older version of Docker Compose:
+This runs the MCP server with Kuzu, requiring no external database container.
+
+##### Neo4j Configuration
+
+For Neo4j, use the dedicated compose file:
 
 ```bash
-docker-compose up
+docker compose -f docker/docker-compose-neo4j.yml up
 ```
 
-This will start both the Neo4j database and the Graphiti MCP server. The Docker setup:
+This includes a Neo4j container with:
+- Username: `neo4j`
+- Password: `demodemo`
+- URI: `bolt://neo4j:7687` (from within the Docker network)
+- Memory settings optimized for development use
+
+##### FalkorDB Configuration
+
+For FalkorDB (Redis-based graph database):
+
+```bash
+docker compose -f docker/docker-compose-falkordb.yml up
+```
+
+This includes a FalkorDB container configured for graph operations.
+
+#### What the Docker Setup Provides
+
+The Docker deployment:
 
 - Uses `uv` for package management and running the server
 - Installs dependencies from the `pyproject.toml` file
-- Connects to the Neo4j container using the environment variables
+- Automatically configures database connections based on the compose file used
-- Exposes the server on port 8000 for HTTP-based SSE transport
+- Exposes the server on port 8000 with HTTP transport (access at `http://localhost:8000/mcp/`)
-- Includes a healthcheck for Neo4j to ensure it's fully operational before starting the MCP server
+- Includes healthchecks to ensure databases are operational before starting the MCP server
+- Supports all Graphiti features including custom entity types and multiple LLM providers
 
 ## Integrating with MCP Clients
 
@@ -241,9 +388,9 @@ VS Code with GitHub Copilot Chat extension supports MCP servers. Add to your VS
 {
   "mcpServers": {
     "graphiti": {
-      "uri": "http://localhost:8000/sse",
+      "uri": "http://localhost:8000/mcp/",
       "transport": {
-        "type": "sse"
+        "type": "http"
       }
     }
   }
@@ -288,14 +435,14 @@ To use the Graphiti MCP server with other MCP-compatible clients, configure it t
 }
 ```
 
-For SSE transport (HTTP-based), you can use this configuration:
+For HTTP transport (default), you can use this configuration:
 
 ```json
 {
   "mcpServers": {
     "graphiti-memory": {
-      "transport": "sse",
+      "transport": "http",
-      "url": "http://localhost:8000/sse"
+      "url": "http://localhost:8000/mcp/"
     }
   }
 }
@@ -335,13 +482,13 @@ source_description="CRM data"
 
 To integrate the Graphiti MCP Server with the Cursor IDE, follow these steps:
 
-1. Run the Graphiti MCP server using the SSE transport:
+1. Run the Graphiti MCP server using the default HTTP transport:
 
 ```bash
-python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>
+uv run graphiti_mcp_server.py --use-custom-entities --group-id <your_group_id>
 ```
 
-Hint: specify a `group_id` to namespace graph data. If you do not specify a `group_id`, the server will use "default" as the group_id.
+Hint: specify a `group_id` to namespace graph data. If you do not specify a `group_id`, the server will use "main" as the group_id.
 
 or
 
@@ -355,7 +502,7 @@ docker compose up
 {
   "mcpServers": {
     "graphiti-memory": {
-      "url": "http://localhost:8000/sse"
+      "url": "http://localhost:8000/mcp/"
     }
   }
 }
@@ -370,12 +517,14 @@ capabilities.
 
 ## Integrating with Claude Desktop (Docker MCP Server)
 
-The Graphiti MCP Server container uses the SSE MCP transport. Claude Desktop does not natively support SSE, so you'll need to use a gateway like `mcp-remote`.
+The Graphiti MCP Server uses HTTP transport by default (at endpoint `/mcp/`). Claude Desktop does not natively support HTTP transport, so you'll need to use a gateway like `mcp-remote`.
 
-1.  **Run the Graphiti MCP server using SSE transport**:
+1.  **Run the Graphiti MCP server**:
 
     ```bash
     docker compose up
+    # Or run directly with uv:
+    uv run graphiti_mcp_server.py
     ```
 
 2.  **(Optional) Install `mcp-remote` globally**:
@@ -396,7 +545,7 @@ The Graphiti MCP Server container uses the SSE MCP transport. Claude Desktop doe
           "command": "npx", // Or the full path to mcp-remote if npx is not in your PATH
           "args": [
             "mcp-remote",
-            "http://localhost:8000/sse" // Ensure this matches your Graphiti server's SSE endpoint
+            "http://localhost:8000/mcp/" // The Graphiti server's HTTP endpoint
           ]
         }
       }
@@ -410,9 +559,9 @@ The Graphiti MCP Server container uses the SSE MCP transport. Claude Desktop doe
 ## Requirements
 
 - Python 3.10 or higher
-- Neo4j database (version 5.26 or later required)
+- OpenAI API key (for LLM operations and embeddings) or other LLM provider API keys
-- OpenAI API key (for LLM operations and embeddings)
 - MCP-compatible client
+- (Optional) Neo4j database (version 5.26 or later) or FalkorDB if not using default Kuzu
 
 ## Telemetry