Add production improvements, type safety, and documentation #47
Conversation
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
Provides development commands, architecture overview, configuration reference, and code quality rules for AI assistants working in this repository. Includes custom commands for issue fixing and PR review. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Python 3.13+ requirement to setup instructions - Clarify entry point uses anyio.run() - Document singleton EmbeddingService pattern - Add SQL backtick quoting guidance for identifiers Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update .python-version from 3.11 to 3.13 to align with pyproject.toml requires-python >= 3.13. Update README.md to match. Enhance CLAUDE.md with more accurate line references, vector store schema, and middleware documentation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Document MariaDB 11.7+ requirement for vector store features using UUID_v7(), fix line reference accuracy, and add logging configuration variables (LOG_LEVEL, LOG_FILE, LOG_MAX_BYTES, LOG_BACKUP_COUNT). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Major changes: - Add /health endpoint for HTTP/SSE transports with metrics - Add timeout configuration (DB_CONNECT_TIMEOUT, DB_READ_TIMEOUT, DB_WRITE_TIMEOUT) - Add result limit (MCP_MAX_RESULTS) to prevent memory issues - Add embedding rate limiting (EMBEDDING_MAX_CONCURRENT) with semaphore - Add HuggingFace model caching for dynamically loaded models - Add connection pool warmup on startup - Add config validation for mismatched multi-DB array lengths - Optimize _execute_query by removing unnecessary SELECT DATABASE() call - Fix silent JSON parse failures in search_vector_store (now logs warnings) - Fix test using wrong parameter name (query -> user_query) - Remove unused autocommit constructor parameter - Move json import to module level - Add metrics tracking (queries, errors, timing, embeddings) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add 7 new troubleshooting scenarios for common issues: - Connection timeout configuration - Large result sets / memory issues - Embedding rate limiting (429 errors) - Health check failures (Docker) - Multiple database config mismatch - Metadata JSON parse errors Expand environment variables table with timeout, pool, and rate limiting configuration options. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix config.py: Use temp variables to avoid reassigning str|None to list[str] - Fix server.py: Add None checks for embedding_service, type result as Dict[str, Any] - Fix embeddings.py: Use `is None` instead of truthy check, fix return type handling - Fix test file: Add missing test_step_1_list_databases function - Add mypy and pytest as dev dependencies - Configure pytest pythonpath for proper module imports Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unsupported read_timeout and write_timeout parameters from asyncmy pool config (asyncmy 0.2.10 only supports connect_timeout) - Fix default pool selection to use first successful pool instead of requiring index 0 to succeed Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
brunstof
changed the title
- Update mariadb healthcheck to use mariadb-admin (mysqladmin renamed in v11) - Add TCP socket healthcheck for mariadb-mcp service Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- populate_geography.py: Downloads and imports world geography dataset (153K+ cities, 5K+ states, 250 countries, 6 continents) - test_mcp_geography.py: Direct tool testing for geography queries - test_mcp_client.py: SSE client test for running MCP container - Update .gitignore to exclude downloaded data cache Data source: github.com/dr5hn/countries-states-cities-database Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove unsupported 'routes' param from server.py (FastMCP 2.12.1) - Add .dockerignore to exclude .venv and avoid build failures - Include scripts/ directory in Docker image - Add Docker environment detection to scripts for host/container compatibility - Remove obsolete 'version' attribute from docker-compose.yml - Add service_healthy condition for proper startup ordering - Improve CORS configuration (OPTIONS, credentials, expose headers) All scripts now work both from host and inside containers. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Views created: - v_cities_full: Complete city info with geographic hierarchy - v_cities_by_country: Query cities by country code or name - v_cities_by_region: Query cities by region/subregion - v_country_stats: Country statistics with city counts - v_region_summary: Aggregated stats by region/subregion Includes example queries and documentation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
/health)Changes
Documentation
Production Readiness
/health) returns status, uptime, pool status, and metrics for HTTP/SSE transportsType Safety & Bug Fixes
read_timeout/write_timeoutparams from asyncmy 0.2.10Dev Tooling
Test plan
uv run mypy src/ --ignore-missing-imports)🤖 Generated with Claude Code