Neptune MCP Support

Author: apetti1920

mcp_server/config/config.yaml

@@ -71,7 +71,7 @@ embedder:
       model: "voyage-3"
 
 database:
-  provider: "falkordb"  # Default: falkordb. Options: neo4j, falkordb
+  provider: "falkordb"  # Default: falkordb. Options: neo4j, falkordb, neptune
 
   providers:
     falkordb:
@@ -86,6 +86,13 @@ database:
       database: ${NEO4J_DATABASE:neo4j}
       use_parallel_runtime: ${USE_PARALLEL_RUNTIME:false}
 
+    neptune:
+      host: ${NEPTUNE_HOST:neptune-db://localhost}
+      aoss_host: ${AOSS_HOST}
+      port: ${NEPTUNE_PORT:8182}
+      aoss_port: ${AOSS_PORT:443}
+      region: ${AWS_REGION:}
+
 graphiti:
   group_id: ${GRAPHITI_GROUP_ID:main}
   episode_id_prefix: ${EPISODE_ID_PREFIX:}

mcp_server/docker/Dockerfile

@@ -33,16 +33,17 @@ ENV UV_COMPILE_BYTECODE=1 \
 WORKDIR /app/mcp
 
 # Accept graphiti-core version as build argument
-ARG GRAPHITI_CORE_VERSION=0.23.1
+ARG GRAPHITI_CORE_VERSION=0.24.1
 
 # Copy project files for dependency installation
 COPY pyproject.toml uv.lock ./
 
 # Remove the local path override for graphiti-core in Docker builds
+# Install with falkordb and neptune extras for maximum flexibility
 # and regenerate lock file to match the PyPI version
 RUN sed -i '/\[tool\.uv\.sources\]/,/graphiti-core/d' pyproject.toml && \
     if [ -n "${GRAPHITI_CORE_VERSION}" ]; then \
-      sed -i "s/graphiti-core\[falkordb\]>=[0-9]\+\.[0-9]\+\.[0-9]\+$/graphiti-core[falkordb]==${GRAPHITI_CORE_VERSION}/" pyproject.toml; \
+      sed -i "s/graphiti-core\[falkordb\]>=[0-9]\+\.[0-9]\+\.[0-9]\+$/graphiti-core[falkordb,neptune]==${GRAPHITI_CORE_VERSION}/" pyproject.toml; \
     fi && \
     echo "Regenerating lock file for PyPI graphiti-core..." && \
     rm -f uv.lock && \
@@ -112,7 +113,7 @@ EOF
 RUN chmod +x /start-services.sh
 
 # Add Docker labels with version information
-ARG MCP_SERVER_VERSION=1.0.1
+ARG MCP_SERVER_VERSION=1.0.2
 ARG BUILD_DATE
 ARG VCS_REF
 LABEL org.opencontainers.image.title="FalkorDB + Graphiti MCP Server" \

mcp_server/docker/Dockerfile.standalone

@@ -28,16 +28,16 @@ ENV UV_COMPILE_BYTECODE=1 \
 WORKDIR /app/mcp
 
 # Accept graphiti-core version as build argument
-ARG GRAPHITI_CORE_VERSION=0.23.1
+ARG GRAPHITI_CORE_VERSION=0.24.1
 
 # Copy project files for dependency installation
 COPY pyproject.toml uv.lock ./
 
 # Remove the local path override for graphiti-core in Docker builds
-# Install with BOTH neo4j and falkordb extras for maximum flexibility
+# Install with neo4j, falkordb, and neptune extras for maximum flexibility
 # and regenerate lock file to match the PyPI version
 RUN sed -i '/\[tool\.uv\.sources\]/,/graphiti-core/d' pyproject.toml && \
-    sed -i "s/graphiti-core\[falkordb\]>=[0-9]\+\.[0-9]\+\.[0-9]\+$/graphiti-core[neo4j,falkordb]==${GRAPHITI_CORE_VERSION}/" pyproject.toml && \
+    sed -i "s/graphiti-core\[falkordb\]>=[0-9]\+\.[0-9]\+\.[0-9]\+$/graphiti-core[neo4j,falkordb,neptune]==${GRAPHITI_CORE_VERSION}/" pyproject.toml && \
     echo "Regenerating lock file for PyPI graphiti-core..." && \
     rm -f uv.lock && \
     uv lock
@@ -58,7 +58,7 @@ COPY config/ ./config/
 RUN mkdir -p /var/log/graphiti
 
 # Add Docker labels with version information
-ARG MCP_SERVER_VERSION=1.0.1
+ARG MCP_SERVER_VERSION=1.0.2
 ARG BUILD_DATE
 ARG VCS_REF
 LABEL org.opencontainers.image.title="Graphiti MCP Server (Standalone)" \

mcp_server/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mcp-server"
-version = "1.0.1"
+version = "1.0.2"
 description = "Graphiti MCP Server"
 readme = "README.md"
 requires-python = ">=3.10,<4"
 dependencies = [
     "mcp>=1.9.4",
     "openai>=1.91.0",
-    "graphiti-core[falkordb]>=0.23.1",
+    "graphiti-core[falkordb,neptune]>=0.23.1",
     "pydantic-settings>=2.0.0",
     "pyyaml>=6.0",
     "typing-extensions>=4.0.0",

mcp_server/src/config/schema.py

@@ -191,11 +191,42 @@ class FalkorDBProviderConfig(BaseModel):
     database: str = 'default_db'
 
 
+class NeptuneProviderConfig(BaseModel):
+    """Neptune provider configuration."""
+
+    host: str = 'neptune-db://localhost'
+    aoss_host: str | None = None
+    port: int = Field(default=8182, ge=1, le=65535)
+    aoss_port: int = Field(default=443, ge=1, le=65535)
+    region: str | None = None
+
+    def model_post_init(self, __context) -> None:
+        """Validate Neptune-specific requirements."""
+        if not self.host.startswith(('neptune-db://', 'neptune-graph://')):
+            raise ValueError(
+                'Neptune host must start with neptune-db:// or neptune-graph://\n'
+                'Examples:\n'
+                '  - Database: neptune-db://my-cluster.us-east-1.neptune.amazonaws.com\n'
+                '  - Analytics: neptune-graph://g-abc123xyz'
+            )
+
+        if not self.aoss_host:
+            raise ValueError(
+                'Neptune requires aoss_host for full-text search.\n'
+                'Set AOSS_HOST environment variable or add to config:\n'
+                '  database:\n'
+                '    providers:\n'
+                '      neptune:\n'
+                '        aoss_host: "your-aoss-endpoint.us-east-1.aoss.amazonaws.com"'
+            )
+
+
 class DatabaseProvidersConfig(BaseModel):
     """Database providers configuration."""
 
     neo4j: Neo4jProviderConfig | None = None
     falkordb: FalkorDBProviderConfig | None = None
+    neptune: NeptuneProviderConfig | None = None
 
 
 class DatabaseConfig(BaseModel):

mcp_server/src/graphiti_mcp_server.py

@@ -228,6 +228,23 @@ async def initialize(self) -> None:
                         embedder=embedder_client,
                         max_coroutines=self.semaphore_limit,
                     )
+                elif self.config.database.provider.lower() == 'neptune':
+                    # For Neptune, create a NeptuneDriver instance directly
+                    from graphiti_core.driver.neptune_driver import NeptuneDriver
+
+                    neptune_driver = NeptuneDriver(
+                        host=db_config['host'],
+                        aoss_host=db_config['aoss_host'],
+                        port=db_config['port'],
+                        aoss_port=db_config['aoss_port'],
+                    )
+
+                    self.client = Graphiti(
+                        graph_driver=neptune_driver,
+                        llm_client=llm_client,
+                        embedder=embedder_client,
+                        max_coroutines=self.semaphore_limit,
+                    )
                 else:
                     # For Neo4j (default), use the original approach
                     self.client = Graphiti(
@@ -266,6 +283,25 @@ async def initialize(self) -> None:
                             f'  - Or run Neo4j manually: docker run -p 7474:7474 -p 7687:7687 neo4j:latest\n\n'
                             f'{"=" * 70}\n'
                         ) from db_error
+                    elif db_provider.lower() == 'neptune':
+                        raise RuntimeError(
+                            f'\n{"=" * 70}\n'
+                            f'Database Connection Error: Neptune is not accessible\n'
+                            f'{"=" * 70}\n\n'
+                            f'Neptune: {db_config.get("host", "unknown")}\n'
+                            f'OpenSearch: {db_config.get("aoss_host", "unknown")}\n\n'
+                            f'Troubleshooting:\n'
+                            f'  1. Verify Neptune endpoint format (neptune-db:// or neptune-graph://)\n'
+                            f'  2. Check AWS credentials: aws sts get-caller-identity\n'
+                            f'  3. Verify security groups allow access\n'
+                            f'  4. Confirm OpenSearch Serverless endpoint is accessible\n'
+                            f'  5. Check IAM permissions (neptune-db:*, aoss:*, neptune-graph:*)\n\n'
+                            f'AWS Setup:\n'
+                            f'  - Region: {db_config.get("region", "not set")}\n'
+                            f'  - Run: aws neptune describe-db-clusters (for Database)\n'
+                            f'  - Run: aws neptune-graph list-graphs (for Analytics)\n\n'
+                            f'{"=" * 70}\n'
+                        ) from db_error
                     else:
                         raise RuntimeError(
                             f'\n{"=" * 70}\n'
@@ -806,7 +842,7 @@ async def initialize_server() -> ServerConfig:
     )
     parser.add_argument(
         '--database-provider',
-        choices=['neo4j', 'falkordb'],
+        choices=['neo4j', 'falkordb', 'neptune'],
         help='Database provider to use',
     )
 

mcp_server/src/services/factories.py

@@ -16,6 +16,14 @@
 except ImportError:
     HAS_FALKOR = False
 
+# Try to import NeptuneDriver if available
+try:
+    from graphiti_core.driver.neptune_driver import NeptuneDriver  # noqa: F401
+
+    HAS_NEPTUNE = True
+except ImportError:
+    HAS_NEPTUNE = False
+
 # Kuzu support removed - FalkorDB is now the default
 from graphiti_core.embedder import EmbedderClient, OpenAIEmbedder
 from graphiti_core.llm_client import LLMClient, OpenAIClient
@@ -433,5 +441,76 @@ def create_config(config: DatabaseConfig) -> dict:
                     'database': falkor_config.database,
                 }
 
+            case 'neptune':
+                if not HAS_NEPTUNE:
+                    raise ValueError(
+                        'Neptune driver not available. Install with:\n'
+                        '  pip install graphiti-core[neptune]\n'
+                        'or:\n'
+                        '  uv add graphiti-core[neptune]'
+                    )
+
+                # Validate AWS credentials early
+                import boto3
+
+                try:
+                    session = boto3.Session()
+                    credentials = session.get_credentials()
+                    if not credentials:
+                        raise ValueError(
+                            'AWS credentials not configured for Neptune.\n'
+                            'Configure using one of:\n'
+                            '  1. AWS CLI: aws configure\n'
+                            '  2. Environment: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY\n'
+                            '  3. IAM role (if running on AWS)\n'
+                            '  4. Credentials file: ~/.aws/credentials'
+                        )
+
+                    region = session.region_name
+                    if not region:
+                        import logging
+
+                        logger = logging.getLogger(__name__)
+                        logger.warning('AWS region not detected, using default from config')
+                except Exception as e:
+                    raise ValueError(f'AWS credential error: {e}') from e
+
+                # Load Neptune config
+                if config.providers.neptune:
+                    neptune_config = config.providers.neptune
+                else:
+                    from config.schema import NeptuneProviderConfig
+
+                    neptune_config = NeptuneProviderConfig()
+
+                # Environment overrides
+                import os
+
+                host = os.environ.get('NEPTUNE_HOST', neptune_config.host)
+                aoss_host = os.environ.get('AOSS_HOST', neptune_config.aoss_host)
+                port = int(os.environ.get('NEPTUNE_PORT', str(neptune_config.port)))
+                aoss_port = int(os.environ.get('AOSS_PORT', str(neptune_config.aoss_port)))
+                region_override = os.environ.get('AWS_REGION', region or neptune_config.region)
+
+                if not aoss_host:
+                    raise ValueError(
+                        'Neptune requires AOSS_HOST for full-text search.\n'
+                        'Set it in config or environment variable.'
+                    )
+
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.info(f'Creating Neptune driver for {host} with region {region_override}')
+
+                return {
+                    'driver': 'neptune',
+                    'host': host,
+                    'aoss_host': aoss_host,
+                    'port': port,
+                    'aoss_port': aoss_port,
+                    'region': region_override,
+                }
+
             case _:
                 raise ValueError(f'Unsupported Database provider: {provider}')

mcp_server/tests/test_configuration.py

@@ -6,9 +6,6 @@
 import sys
 from pathlib import Path
 
-# Add the current directory to the path
-sys.path.insert(0, str(Path(__file__).parent.parent / 'src'))
-
 from config.schema import GraphitiConfig
 from services.factories import DatabaseDriverFactory, EmbedderFactory, LLMClientFactory