Added detailed documentation for SEMAPHORE_LIMIT configuration to help users optimize episode processing concurrency based on their LLM provider's rate limits.
Changes:
1. **graphiti_mcp_server.py**
- Expanded inline comments from 3 lines to 26 lines
- Added provider-specific tuning guidelines (OpenAI, Anthropic, Azure, Ollama)
- Documented symptoms of too-high/too-low settings
- Added monitoring recommendations
2. **README.md**
- Expanded "Concurrency and LLM Provider 429 Rate Limit Errors" section
- Added tier-specific recommendations for each provider
- Explained relationship between episode concurrency and LLM request rates
- Added troubleshooting symptoms and monitoring guidance
- Included example .env configuration
3. **config.yaml**
- Added header comment referencing detailed documentation
- Noted default value and suitable use case
4. **.env.example**
- Added SEMAPHORE_LIMIT with inline tuning guidelines
- Quick reference for all major LLM provider tiers
- Cross-reference to README for full details
Benefits:
- Users can now make informed decisions about concurrency settings
- Reduces likelihood of 429 rate limit errors from misconfiguration
- Helps users maximize throughput within their rate limits
- Provides clear troubleshooting guidance
Addresses PR #1024 review comment about magic number documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed high-impact issues from PR #1024 code review:
1. **Boolean conversion bug (schema.py)**
- Fixed _expand_env_vars returning strings 'true'/'false' instead of booleans
- Now properly converts boolean-like strings (true/false/1/0/yes/no/on/off) to actual booleans
- Simplified logic by removing redundant string-to-string conversions
- Added support for common boolean string variations
2. **Dependency management (pyproject.toml)**
- Removed pytest from main dependencies (now only in dev dependencies)
- Moved azure-identity to optional dependencies under new [azure] group
- Prevents forcing Azure and testing dependencies on all users
3. **Conditional Azure imports (utils.py)**
- Made azure-identity import conditional in create_azure_credential_token_provider()
- Raises helpful ImportError with installation instructions if not available
- Follows lazy-import pattern for optional dependencies
4. **Documentation fix (graphiti_mcp_server.py)**
- Fixed confusing JSON escaping in add_memory docstring example
- Changed from triple-backslash escaping to standard JSON string
- Updated comment to clarify standard JSON escaping is used
Issues verified as already fixed:
- Docker build context (all docker-compose files use context: ..)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removed all remaining Kuzu references from:
- Test fixtures (test_fixtures.py): Changed default database to falkordb, removed kuzu configuration
- Test runner (run_tests.py): Removed kuzu from database choices, checks, and markers
- Integration tests (test_comprehensive_integration.py): Removed kuzu from parameterized tests and environment setup
- Test README: Updated all examples and documentation to reflect falkordb as default
- Docker README: Completely rewrote to remove KuzuDB section, updated with FalkorDB combined image as default
All Kuzu support has been completely removed from the MCP server codebase. FalkorDB (via combined container) is now the default database backend.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Pydantic BaseModel reserves 'name' as a protected attribute. Removed
the 'name' attribute from dynamically created entity type models as
it's not needed - the entity type name is already stored as the class
name and dict key.
Fixed error: name cannot be used as an attribute for Requirement as
it is a protected attribute name.
The Graphiti add_episode() API expects entity_types as a
dict[str, type[BaseModel]], not a list. Changed entity type
building to create a dictionary mapping entity names to their
Pydantic model classes.
Fixed error: 'list' object has no attribute 'items'
Changes:
- Build entity_types as dict instead of list in config processing
- Add fallback to convert ENTITY_TYPES list to dict if needed
- Map entity type names to their model classes
The UTC constant was added in Python 3.11. Changed to use
timezone.utc which is available in Python 3.10+.
Fixed ImportError: cannot import name 'UTC' from 'datetime'
- Replace bare except with except Exception
- Remove unused imports and variables
- Fix type hints to use modern syntax
- Apply ruff formatting for line length
- Ensure all tests pass linting checks
- Use simplified format matching uvicorn's default (LEVEL message)
- Remove timestamps from custom logger format
- Suppress verbose MCP and uvicorn access logs
- Improve readability of server startup output
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove incorrect /status endpoint reference
- Update logging to show correct MCP endpoint at /mcp/
- Align with FastMCP documentation standards
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added comprehensive logging showing exact URLs to access the MCP server
- Display localhost instead of 0.0.0.0 for better usability
- Show MCP endpoint, transport type, and status endpoint information
- Added visual separators to make server info stand out in logs
This helps users understand exactly how to connect to the MCP server
and troubleshoot connection issues.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Changed hardcoded default in schema.py from gpt-4o to gpt-4.1
- Fixed default config path to look in config/config.yaml relative to mcp_server directory
- This ensures the server uses gpt-4.1 as the default model everywhere
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix API key detection: Remove hardcoded OpenAI checks, let factories handle provider-specific validation
- Fix .env file loading: Search for .env in mcp_server directory first
- Change default transport to SSE for broader compatibility (was stdio)
- Add proper error handling with warnings for failed client initialization
- Model already defaults to gpt-4o as requested
These changes ensure the MCP server properly loads API keys from .env files
and creates the appropriate LLM/embedder clients based on configuration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This is a major refactoring of the MCP Server to support multiple providers
through a YAML-based configuration system with factory pattern implementation.
## Key Changes
### Architecture Improvements
- Modular configuration system with YAML-based settings
- Factory pattern for LLM, Embedder, and Database providers
- Support for multiple database backends (Neo4j, FalkorDB, KuzuDB)
- Clean separation of concerns with dedicated service modules
### Provider Support
- **LLM**: OpenAI, Anthropic, Gemini, Groq
- **Embedders**: OpenAI, Voyage, Gemini, Anthropic, Sentence Transformers
- **Databases**: Neo4j, FalkorDB, KuzuDB (new default)
- Azure OpenAI support with AD authentication
### Configuration
- YAML configuration with environment variable expansion
- CLI argument overrides for runtime configuration
- Multiple pre-configured Docker Compose setups
- Proper boolean handling in environment variables
### Testing & CI
- Comprehensive test suite with unit and integration tests
- GitHub Actions workflows for linting and testing
- Multi-database testing support
### Docker Support
- Updated Docker images with multi-stage builds
- Database-specific docker-compose configurations
- Persistent volume support for all databases
### Bug Fixes
- Fixed KuzuDB connectivity checks
- Corrected Docker command paths
- Improved error handling and logging
- Fixed boolean environment variable expansion
Co-authored-by: Claude <noreply@anthropic.com>
