AWS Neptune Support for MCP Server

[apetti1920]

Summary

Adds AWS Neptune database provider support to the Graphiti MCP server. While the graphiti-core library already supports Neptune, the MCP server lacked the configuration and factory logic to expose it. This PR implements full Neptune integration with proper validation, configuration management, and comprehensive testing.

Type of Change

• [x] New feature
• [x] Documentation/Tests

Objective

Rationale: AWS Neptune (both Database and Analytics variants) provides a fully-managed graph database service that many enterprise users prefer over self-hosted solutions. The core library supports Neptune, but the MCP server couldn't utilize it due to missing configuration schema and factory implementations.

Goals:

1. Enable Neptune as a database provider option via --database-provider neptune CLI flag
2. Implement proper validation for Neptune's dual-endpoint architecture (graph + OpenSearch)
3. Ensure seamless AWS credential integration via boto3
4. Maintain consistency with existing Neo4j and FalkorDB provider patterns

Implementation Details

Configuration Layer (mcp_server/src/config/schema.py)

• Added NeptuneProviderConfig class with validation for:
  • Endpoint format validation (neptune-db:// or neptune-graph://)
  • Required AOSS (Amazon OpenSearch Serverless) host
  • Port range validation (1-65535)
  • Optional AWS region configuration
• Integrated into DatabaseProvidersConfig

Factory Layer (mcp_server/src/services/factories.py)

• Implemented Neptune driver import checking with helpful error messages
• Added AWS credential validation using boto3.Session()
• Environment variable override support for all Neptune parameters
• Comprehensive error handling with troubleshooting guidance

Service Layer (mcp_server/src/graphiti_mcp_server.py)

• Neptune driver initialization in main service
• CLI integration with --database-provider choices
• Neptune-specific error handling with AWS diagnostic guidance

Configuration Files

• config.yaml: Added Neptune provider section with environment variable templating
• pyproject.toml: Updated to include graphiti-core[neptune] extras (version bumped to 1.0.2)
• Docker: Added Neptune support to both combined and standalone Dockerfiles
• uv.lock: Updated with Neptune dependencies (boto3, botocore, opensearch-py, langchain-aws)

Dependencies Added

• boto3>=1.39.16 - AWS SDK for Python
• botocore>=1.41.2 - AWS SDK core
• opensearch-py>=3.1.0 - OpenSearch client for AOSS
• langchain-aws>=1.1.0 - LangChain AWS integrations

Testing

• [x] Unit tests added/updated
  • test_neptune_configuration.py: Comprehensive integration tests with mocked AWS credentials
    • Configuration validation (endpoint format, AOSS requirement, port ranges)
    • Environment variable overrides
    • Factory creation with credential validation
    • Import availability checking
  • test_neptune_simple.py: Standalone validation tests
    • Endpoint format validation logic
    • Port range validation
    • Configuration requirements documentation
    • Error message quality verification
    • AWS integration requirements
    • Dependency documentation
• [x] Integration tests added/updated
• [x] All existing tests pass (Neptune tests compatible with existing test infrastructure)

Breaking Changes

• [ ] This PR contains breaking changes

No breaking changes. This is a purely additive feature that:

• Maintains backward compatibility with existing Neo4j and FalkorDB configurations
• Adds Neptune as an opt-in provider
• Does not modify existing APIs or configuration structures

Configuration Example

database:
  provider: "neptune"

  providers:
    neptune:
      host: ${NEPTUNE_HOST:neptune-db://localhost}
      aoss_host: ${AOSS_HOST}
      port: ${NEPTUNE_PORT:8182}
      aoss_port: ${AOSS_PORT:443}
      region: ${AWS_REGION:}

Or via environment variables:

export NEPTUNE_HOST="neptune-db://my-cluster.us-east-1.neptune.amazonaws.com"
export AOSS_HOST="my-aoss-endpoint.us-east-1.aoss.amazonaws.com"
export AWS_REGION="us-east-1"

Or via CLI:

python -m graphiti_mcp_server --database-provider neptune

AWS Credential Support

Neptune integration works with standard AWS credential chain:

1. AWS CLI (aws configure)
2. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
3. IAM roles (when running on AWS)
4. Credentials file (~/.aws/credentials)

Checklist

• [x] Code follows project style guidelines
• [x] Self-review completed
• [x] Documentation updated (config.yaml comments, error messages, test documentation)
• [x] No secrets or sensitive information committed
• [x] .config/uv.toml added to prevent private registry pollution in open-source project

Files Changed

• Configuration: config/config.yaml, pyproject.toml
• Schema: src/config/schema.py
• Factory: src/services/factories.py
• Service: src/graphiti_mcp_server.py
• Docker: docker/Dockerfile, docker/Dockerfile.standalone
• Tests: tests/test_neptune_configuration.py, tests/test_neptune_simple.py
• Dependencies: uv.lock

Related Issues

Resolves internal request for AWS Neptune support in MCP server

[danielchalef]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[apetti1920]

I have read the CLA Document and I hereby sign the CLA