{"id":31177865,"url":"https://github.com/call518/mcp-mysql-ops","last_synced_at":"2026-05-07T10:31:23.459Z","repository":{"id":311808971,"uuid":"1045086389","full_name":"call518/MCP-MySQL-Ops","owner":"call518","description":"🔍 Professional MySQL database monitoring \u0026 operations server with 19 specialized tools. Natural language queries, Performance Schema integration, MySQL 5.7+/8.0+ support. MCP-compatible for AI assistants.","archived":false,"fork":false,"pushed_at":"2025-09-17T17:42:41.000Z","size":451,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T19:54:46.412Z","etag":null,"topics":["database-health-check","database-management","database-monitoring","docker-compose","fastmcp","information-schema","llm","mcp-server","mcpo","mysql","mysql-database","mysql-diagnostics","mysql-management","mysql-performance","mysql-server","natural-language","openwebui","performance"],"latest_commit_sha":null,"homepage":"https://deepwiki.com/call518/MCP-MySQL-Ops","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/call518.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T16:25:42.000Z","updated_at":"2025-09-17T17:42:32.000Z","dependencies_parsed_at":"2025-08-27T01:44:00.074Z","dependency_job_id":"2be74dfe-3665-4f4c-814d-c57c2861bf2c","html_url":"https://github.com/call518/MCP-MySQL-Ops","commit_stats":null,"previous_names":["call518/mcp-mysql-ops"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/call518/MCP-MySQL-Ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/call518%2FMCP-MySQL-Ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/call518%2FMCP-MySQL-Ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/call518%2FMCP-MySQL-Ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/call518%2FMCP-MySQL-Ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/call518","download_url":"https://codeload.github.com/call518/MCP-MySQL-Ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/call518%2FMCP-MySQL-Ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275952447,"owners_count":25558705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database-health-check","database-management","database-monitoring","docker-compose","fastmcp","information-schema","llm","mcp-server","mcpo","mysql","mysql-database","mysql-diagnostics","mysql-management","mysql-performance","mysql-server","natural-language","openwebui","performance"],"created_at":"2025-09-19T14:31:19.279Z","updated_at":"2026-05-07T10:31:23.449Z","avatar_url":"https://github.com/call518.png","language":"Python","funding_links":["https://www.buymeacoffee.com/call518"],"categories":[],"sub_categories":[],"readme":"# MCP Server for MySQL Operations and Monitoring\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![Python](https://img.shields.io/badge/Python-3776AB?style=flat\u0026logo=python\u0026logoColor=white)\n![Docker Pulls](https://img.shields.io/docker/pulls/call518/mcp-server-mysql-ops)\n![MySQL](https://img.shields.io/badge/MySQL-4479A1?style=flat\u0026logo=mysql\u0026logoColor=white)\n[![BuyMeACoffee](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-donate-yellow.svg)](https://www.buymeacoffee.com/call518)\n\n[![Deploy to PyPI with tag](https://github.com/call518/MCP-MySQL-Ops/actions/workflows/pypi-publish.yml/badge.svg)](https://github.com/call518/MCP-MySQL-Ops/actions/workflows/pypi-publish.yml)\n![PyPI](https://img.shields.io/pypi/v/MCP-MySQL-Ops?label=pypi%20package)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/MCP-MySQL-Ops)\n\n---\n\n## Architecture \u0026 Internal (DeepWiki)\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/call518/MCP-MySQL-Ops)\n\n---\n\n## Overview\n\nYou are working with the **MCP MySQL Operations Server**, a powerful tool that provides comprehensive MySQL database monitoring and analysis capabilities through natural language queries. This server offers **19 specialized tools** for database administration, performance monitoring, and system analysis. Leverages MySQL's Performance Schema and Information Schema for deep insights into database operations and performance metrics.\n\n---\n\n## Features\n\n- ✅ **Zero Configuration**: Works with MySQL 5.7.9+ and 8.0+ out-of-the-box with automatic version detection.\n- ✅ **Natural Language**: Ask questions like \"Show me slow queries\" or \"Analyze table sizes.\"\n- ✅ **Production Safe**: Read-only operations, AWS RDS/Aurora MySQL compatible with regular user permissions.\n- ✅ **Performance Schema Integration**: Advanced query analytics using MySQL's built-in Performance Schema.\n- ✅ **Comprehensive Database Monitoring**: Storage engine analysis, connection monitoring, and performance insights.\n- ✅ **Smart Query Analysis**: Query performance identification using Performance Schema statistics.\n- ✅ **Schema \u0026 Structure Discovery**: Database structure exploration with detailed table and index analysis.\n- ✅ **Storage Engine Intelligence**: InnoDB monitoring, table optimization recommendations.\n- ✅ **Multi-Database Operations**: Seamless cross-database analysis and monitoring.\n- ✅ **Enterprise-Ready**: Safe read-only operations with AWS RDS/Aurora MySQL compatibility.\n- ✅ **Developer-Friendly**: Simple codebase for easy customization and tool extension.\n\n### 🔧 **Advanced Capabilities**\n- Performance Schema-based query monitoring and analysis.\n- Real-time connection and process monitoring.\n- Storage engine status and optimization analysis.\n- Database capacity and table size analysis.\n- Index usage and efficiency tracking.\n\n## Tool Usage Examples\n\n---\n\n![MCP-MySQL-Ops Usage Screenshot](img/screenshot-000.png)\n\n---\n\n![MCP-MySQL-Ops Usage Screenshot](img/screenshot-001.png)\n\n---\n\n## ⭐ Quickstart (5 minutes)\n\n\u003e **Note:** The `mysql` container included in `docker-compose.yml` is intended for quickstart testing purposes only. You can connect to your own MySQL instance by adjusting the environment variables as needed.\n\n\u003e **If you want to use your own MySQL instance instead of the built-in test container:**\n\u003e - Update the target MySQL connection information in your `.env` file (see MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE).\n\u003e - In `docker-compose.yml`, comment out (disable) the `mysql` and `mysql-init-data` containers to avoid starting the built-in test database.\n\n### Flow Diagram of Quickstart/Tutorial\n\n![Flow Diagram of Quickstart/Tutorial](img/MCP-Workflow-of-Quickstart-Tutorial.png)\n\n### 1. Environment Setup\n\n\u003e **Note**: The system automatically handles user permissions - both root users and regular users are supported with appropriate access control.\n\n```bash\ngit clone https://github.com/call518/MCP-MySQL-Ops.git\ncd MCP-MySQL-Ops\n\n# Copy and check environment configuration\ncp .env.example .env\n```\n\n**Default configuration (works out-of-the-box):**\n```bash\n#### MySQL Root Configuration for Docker:\nMYSQL_ROOT_HOST=%\nMYSQL_ROOT_PASSWORD=changeme!@34\n\n#### MySQL Host Configuration:\nMYSQL_HOST=host.docker.internal\nMYSQL_PORT=13306\nMYSQL_USER=root\nMYSQL_PASSWORD=${MYSQL_PASSWORD}\nMYSQL_DATABASE=test_ecommerce\n```\n\n**For your own MySQL server:**\n```bash\n# Edit .env file with your MySQL connection details\nMYSQL_HOST=your-mysql-server.com\nMYSQL_PORT=3306\nMYSQL_USER=your_username     # Will auto-grant permissions on test DBs\nMYSQL_PASSWORD=your_password\nMYSQL_DATABASE=your_default_db\n\n# Then disable built-in containers in docker-compose.yml\n# Comment out: mysql and mysql-init-data services\n```\n\n\u003e **Note**: The MySQL container is configured with proper volume mapping for data persistence and initial database setup.\n\n**Additional Resources:**\n- **MCP Tool Features (Swagger)**: http://localhost:8004/docs  \n- **MCPO Proxy API Documentation**: http://localhost:8004/mysql-ops/docs\n\n### 2. Run Docker Stack\n\n```bash\n# Start all services (MySQL + MCP server + test interfaces)\ndocker-compose up -d\n\n# Check container status\ndocker-compose ps\n\n# Watch the logs (Ctrl+C to exit)\ndocker-compose logs -f mysql-init-data\n```\n\n**⏱️ Container Startup Sequence \u0026 Wait Time:**\n- **MySQL Container**: Starts first and initializes database (~30-60 seconds)\n- **MySQL Init Data**: Generates test data automatically (~1-2 minutes)\n- **MCP Server**: Starts after MySQL is ready (~10-20 seconds)\n- **OpenWebUI**: Starts last to ensure all services are available (~10-30 seconds)\n\n**💡 Please wait 2-3 minutes** for all containers to fully initialize before accessing the web interface. You can monitor the startup progress with:\n\n```bash\n# Monitor all container logs\ndocker-compose logs -f\n\n# Check if all containers are healthy\ndocker-compose ps\n```\n\n### 3. Automatic Test Data Generation\n\n**🎉 No manual setup required!** Test data is automatically generated during first startup by the `mysql-init-data` container.\n\n**What happens automatically:**\n- ✅ 4 comprehensive test databases created (`test_ecommerce`, `test_analytics`, `test_inventory`, `test_hr`)\n- ✅ ~2,745 realistic records with proper foreign key relationships\n- ✅ User permissions automatically configured for your `MYSQL_USER` (from .env)\n- ✅ Test users and roles created for different access scenarios\n\n**Manual execution (if needed):**\n```bash\n# Force regenerate test data (optional)\ndocker-compose run --rm mysql-init-data /scripts/create-test-data.sh\n\n# Check generation logs\ndocker logs mcp-mysql-ops-mysql-init-data\n```\n\n**Verification:**\n```bash\n# Connect and verify test databases exist\ndocker exec -it mcp-mysql-ops-mysql-8 mysql -u [your_mysql_user] -p -e \"SHOW DATABASES;\"\n```\n\n### 4. Access to OpenWebUI\n\n**🌐 Web Interface:** http://localhost:3004/\n\n\u003e **⏳ Important**: Please wait **2-3 minutes** after running `docker-compose up -d` for all containers to fully initialize. OpenWebUI starts last to ensure all backend services (MySQL, test data generation, MCP server) are ready.\n\n**Quick Status Check:**\n```bash\n# Verify all containers are running\ndocker-compose ps\n\n# If any container shows \"starting\" or \"unhealthy\", wait a bit longer\n# You can watch the startup logs:\ndocker-compose logs -f\n```\n\n### 5. Registering the Tool in OpenWebUI\n\n\u003e 📌 **Note**: Web-UI configuration instructions are based on OpenWebUI **v0.6.22**. Menu locations and settings may differ in newer versions.\n\n1. logging in to OpenWebUI with an admin account\n1. go to \"Settings\" → \"Tools\" from the top menu.\n1. Enter the `mysql-ops` Tool address (e.g., `http://localhost:8004/mysql-ops`) to connect MCP Tools.\n1. Setup Ollama or OpenAI.\n\n### 6. Complete!\n\n**Congratulations!** Your MCP MySQL Operations server is now ready for use. You can start exploring your databases with natural language queries.\n\n#### 🚀 **Try These Example Queries:**\n\n- **\"Show me the current active connections\"**\n- **\"What are the current server status and configuration?\"** \n- **\"Analyze table sizes and storage efficiency\"**\n- **\"Show me database size information\"**\n- **\"What tables have the most rows?\"**\n\n---\n\n## Security \u0026 Authentication\n\n### Bearer Token Authentication\n\nFor `streamable-http` mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.\n\n#### Configuration\n\n**Enable Authentication:**\n\n```bash\n# In .env file\nREMOTE_AUTH_ENABLE=true\nREMOTE_SECRET_KEY=your-secure-secret-key-here\n```\n\n**Or via CLI:**\n\n```bash\npython -m mcp_mysql_ops --type streamable-http --auth-enable --secret-key your-secure-secret-key-here\n```\n\n#### Security Levels\n\n1. **stdio mode** (Default): Local-only access, no authentication needed\n2. **streamable-http + REMOTE_AUTH_ENABLE=false**: Remote access without authentication ⚠️ **NOT RECOMMENDED for production**\n3. **streamable-http + REMOTE_AUTH_ENABLE=true**: Remote access with Bearer token authentication ✅ **RECOMMENDED for production**\n\n#### Client Configuration\n\nWhen authentication is enabled, MCP clients must include the Bearer token in the Authorization header:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-mysql-ops\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://your-server:8000/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secure-secret-key-here\"\n      }\n    }\n  }\n}\n```\n\n#### Security Best Practices\n\n- **Always enable authentication** when using streamable-http mode in production\n- **Use strong, randomly generated secret keys** (32+ characters recommended)\n- **Use HTTPS** when possible (configure reverse proxy with SSL/TLS)\n- **Restrict network access** using firewalls or network policies\n- **Rotate secret keys regularly** for enhanced security\n- **Monitor access logs** for unauthorized access attempts\n\n#### Error Handling\n\nWhen authentication fails, the server returns:\n- **401 Unauthorized** for missing or invalid tokens\n- **Detailed error messages** in JSON format for debugging\n\n---\n\n## 🐛 Usage \u0026 Configuration\n\nThis MCP server supports two connection modes: **stdio** (traditional) and **streamable-http** (Docker-based). You can configure the transport mode using CLI arguments or environment variables.\n\n**Configuration Priority:** CLI arguments \u003e Environment variables \u003e Default values\n\n### CLI Arguments\n\n- `--type` (`-t`): Transport type (`stdio` or `streamable-http`) - Default: `stdio`\n- `--host`: Host address for HTTP transport - Default: `127.0.0.1`  \n- `--port` (`-p`): Port number for HTTP transport - Default: `8000`\n- `--auth-enable`: Enable Bearer token authentication for streamable-http mode - Default: `false`\n- `--secret-key`: Secret key for Bearer token authentication (required when auth enabled)\n\n### Environment Variables\n\n| Variable | Description | Default | Project Default |\n|----------|-------------|---------|-----------------|\n| `PYTHONPATH` | Python module search path for MCP server imports | - | `/app/src` |\n| `MCP_LOG_LEVEL` | Server logging verbosity (DEBUG, INFO, WARNING, ERROR) | `INFO` | `INFO` |\n| `FASTMCP_TYPE` | MCP transport protocol (stdio for CLI, streamable-http for web) | `stdio` | `streamable-http` |\n| `FASTMCP_HOST` | HTTP server bind address (0.0.0.0 for all interfaces) | `127.0.0.1` | `0.0.0.0` |\n| `FASTMCP_PORT` | HTTP server port for MCP communication | `8000` | `8000` |\n| `REMOTE_AUTH_ENABLE` | Enable Bearer token authentication for streamable-http mode. **If undefined/empty, defaults to `false`**. Accepts: true/false, 1/0, yes/no, on/off (case insensitive) | `false` | `false` |\n| `REMOTE_SECRET_KEY` | Secret key for Bearer token authentication. **If undefined/empty, authentication will be disabled even if `REMOTE_AUTH_ENABLE=true`**. Recommended: 32+ character random string | `\"\"` (empty) | `your-secret-key-here` |\n| `MYSQL_HOST` | MySQL server hostname or IP address | `127.0.0.1` | `host.docker.internal` |\n| `MYSQL_PORT` | MySQL server port number | `3306` | `13306` |\n| `MYSQL_USER` | Username for MySQL server authentication | `root` | `root` |\n| `MYSQL_PASSWORD` | Password for MySQL server authentication | - | `changeme!@34` |\n| `MYSQL_DATABASE` | Name of the default target MySQL database | - | `test_ecommerce` |\n| `DOCKER_EXTERNAL_PORT_OPENWEBUI` | Host port mapping for Open WebUI container | `8080` | `3004` |\n\n### Environment Setup\n\nCopy `.env.example` to `.env` and configure your environment:\n\n```bash\ncp .env.example .env\n# Edit .env file with your specific configuration\n```\n\n#### Environment Variable Defaults Policy\n\n**Authentication Variables:**\n- `REMOTE_AUTH_ENABLE`: If undefined, commented out, or empty → defaults to `false`\n- `REMOTE_SECRET_KEY`: If undefined, commented out, or empty → defaults to `\"\"` (empty string)\n\n**Security Behavior:**\n- Authentication is **only enabled** when both conditions are met:\n  1. `REMOTE_AUTH_ENABLE` is explicitly set to a truthy value (true/1/yes/on)\n  2. `REMOTE_SECRET_KEY` is set to a non-empty string\n- If either condition fails, the server runs **without authentication**\n- This ensures safe defaults and prevents accidental authentication bypass\n\n**Example configurations:**\n```bash\n# Authentication disabled (all equivalent)\n# REMOTE_AUTH_ENABLE=            # undefined/commented\nREMOTE_AUTH_ENABLE=false         # explicit false\nREMOTE_AUTH_ENABLE=\"\"           # empty string\n\n# Authentication enabled (requires both)\nREMOTE_AUTH_ENABLE=true         # or 1, yes, on\nREMOTE_SECRET_KEY=my-secret-key # non-empty string\n```\n\n---\n\n## 🛠️ Local Development \u0026 Installation\n\nFor developers wanting to run the MCP server locally or integrate it into their own projects:\n\n### Method 1: Console Script (Recommended)\n```bash\n# Clone and install\ngit clone https://github.com/call518/MCP-MySQL-Ops.git\ncd MCP-MySQL-Ops\npip install -e .\n\n# Run with simple command\nmcp-mysql-ops --type stdio\nmcp-mysql-ops --type streamable-http --host 127.0.0.1 --port 8000\n```\n\n### Method 2: Module Execution\n```bash\n# Clone and set PYTHONPATH\ngit clone https://github.com/call518/MCP-MySQL-Ops.git\ncd MCP-MySQL-Ops\nexport PYTHONPATH=$(pwd)/src\n\n# Run as module\npython -m mcp_mysql_ops --type stdio\npython -m mcp_mysql_ops --type streamable-http --host 127.0.0.1 --port 8000\n```\n\n\u003e **💡 Pro Tip**: Use Method 1 (console script) for cleaner integration. Method 2 is useful when you need to modify the source code directly.\n\n### Running Tests\n\nTwo test suites are available:\n\n| Suite | File | Requires Docker |\n|-------|------|----------------|\n| Unit tests (version compatibility logic) | `tests/test_version_compat.py` | No |\n| Integration tests (all tools × MySQL 5.7 / 8.0 / 8.4) | `tests/test_tools_integration.py` | Yes |\n\n#### Run everything with a single command\n\n`uv run pytest` automatically starts the Docker test containers (MySQL 5.7, 8.0, 8.4), waits for them to be fully initialized (schema + seed data + Performance Schema), runs all tests, then tears everything down.\n\n```bash\n# Install dev dependencies (one-time)\nuv sync --extra dev\n\n# Run all tests (unit + integration) — Docker is managed automatically\nuv run pytest -v\n\n# Unit tests only (no Docker needed)\nuv run pytest tests/test_version_compat.py -v\n\n# Integration tests only\nuv run pytest tests/test_tools_integration.py -v\n\n# Run against a specific MySQL version only\nuv run pytest -v -k MySQL80\n```\n\n\u003e **Note**: Docker must be running. The test stack uses ports `3357` (MySQL 5.7), `3380` (8.0), and `3384` (8.4) on `127.0.0.1`.\n\u003e\n\u003e If containers are already running (e.g. between repeated debug runs), the test fixture detects them and skips the up/down lifecycle — useful for fast iteration. To pre-start manually:\n\u003e\n\u003e ```bash\n\u003e docker compose -f tests/docker/docker-compose.test.yml up -d\n\u003e uv run pytest -v   # reuses running containers, does not tear down\n\u003e ```\n\n#### Continuous Integration\n\nEvery push to `main` and every pull request triggers [`.github/workflows/test.yml`](.github/workflows/test.yml), which runs the unit suite and the full MySQL 5.7 / 8.0 / 8.4 integration matrix on GitHub-hosted runners.\n\n---\n\n## (NOTE) Sample Test Data Overview\n\nThe test data generation system follows the PostgreSQL MCP project pattern - using a dedicated `mysql-init-data` container that automatically creates comprehensive test databases on first startup.\n\n### 🚀 **Automatic Test Data Generation**\n\nThe `mysql-init-data` container (defined in docker-compose.yml) automatically executes `scripts/create-test-data.sh` and `scripts/create-test-data.sql` on first startup, generating realistic business data for MCP tool testing.\n\n| Database | Purpose | Tables | Scale |\n|----------|---------|--------|-------|\n| **test_ecommerce** | E-commerce system | categories, products, customers, orders, order_items | 10 categories, 500 products, 100 customers, 1000 orders, 2500 order items |\n| **test_analytics** | Analytics \u0026 reporting | page_views, sales_summary | 500 page views, 30 sales summaries |\n| **test_inventory** | Warehouse management | suppliers, inventory_items, purchase_orders | 10 suppliers, 100 items, 50 purchase orders |\n| **test_hr** | HR management | departments, employees, payroll | 5 departments, 50 employees, 150 payroll records |\n\n**Total Records:** ~2,745 records across all test databases\n\n**Test users created:** `app_readonly`, `app_readwrite`, `analytics_user`, `backup_user`\n\n**User Permission Management:** The system automatically creates specified `MYSQL_USER` (from .env) and grants full permissions on the 4 test databases only, ensuring secure access control.\n\n**Features for Testing:**\n- ✅ Foreign key relationships with proper referential integrity\n- ✅ Various storage engines (InnoDB optimization)\n- ✅ Mixed index types (used/unused for testing index analysis tools)\n- ✅ Time-series data for analytics testing\n- ✅ Realistic business scenarios across multiple domains\n- ✅ Safe test environment with isolated user permissions\n\n### 📋 **PostgreSQL-Style Init Pattern**\n\nSimilar to the [MCP-PostgreSQL-Ops](https://github.com/call518/MCP-PostgreSQL-Ops) project, this MySQL implementation uses:\n- Dedicated init container (`mysql-init-data`) for one-time data generation\n- Health check dependencies ensuring MySQL is ready before data creation\n- Root privileges for database creation, then permission delegation to specified user\n- Comprehensive logging and error handling during initialization\n\n---\n\n## Tool Compatibility Matrix\n\n\u003e **Automatic Adaptation:** All tools work transparently across supported versions - no configuration needed!\n\n### 🟢 **Professional MySQL Tools (19 Tools Available)**\n\n| Tool Name | MySQL Versions | Features | Information Source |\n|-----------|---------------|----------|-------------------|\n| `get_server_info` | MySQL 5.7.9+ / 8.0+ | ✅ Server version, configuration, status variables | `SHOW VERSION`, `INFORMATION_SCHEMA` |\n| `get_database_list` | MySQL 5.7.9+ / 8.0+ | ✅ Database sizes, character sets, collations | `INFORMATION_SCHEMA.SCHEMATA`, `information_schema.tables` |\n| `get_table_list` | MySQL 5.7.9+ / 8.0+ | ✅ Table information, storage engines, row counts | `INFORMATION_SCHEMA.TABLES` |\n| `get_table_schema_info` | MySQL 5.7.9+ / 8.0+ | ✅ Columns, indexes, constraints, foreign keys | `INFORMATION_SCHEMA.COLUMNS`, `INFORMATION_SCHEMA.STATISTICS` |\n| `get_database_overview` | MySQL 5.7.9+ / 8.0+ | ✅ Database summary, table counts, sizes | `INFORMATION_SCHEMA.TABLES`, aggregated statistics |\n| `get_user_list` | MySQL 5.7.9+ / 8.0+ | ✅ MySQL users, hosts, privileges, account status | `mysql.user`, `INFORMATION_SCHEMA.USER_PRIVILEGES` |\n| `get_active_connections` | MySQL 5.7.9+ / 8.0+ | ✅ Active connections, connection details, process list | `performance_schema.processlist` |\n| `get_server_status` | MySQL 5.7.9+ / 8.0+ | ✅ Server status variables, performance counters | `SHOW STATUS`, system status variables |\n| `get_table_size_info` | MySQL 5.7.9+ / 8.0+ | ✅ Table sizes, index sizes, data/index ratios | `INFORMATION_SCHEMA.TABLES` (DATA_LENGTH, INDEX_LENGTH) |\n| `get_database_size_info` | MySQL 5.7.9+ / 8.0+ | ✅ Database sizes, storage usage analysis | Aggregated `INFORMATION_SCHEMA.TABLES` data |\n| `get_index_usage_stats` | MySQL 5.7.9+ / 8.0+ | ✅ Index usage, cardinality, efficiency analysis | `INFORMATION_SCHEMA.STATISTICS`, `SHOW INDEX` |\n\n### 🚀 **Performance Schema Enhanced Tools (8 Additional Tools)**\n\n| Tool Name | MySQL Versions | Features | Information Source |\n|-----------|---------------|----------|-------------------|\n| `get_mysql_config` | MySQL 5.7.9+ / 8.0+ | ✅ MySQL configuration variables and settings | `SHOW VARIABLES`, system configuration |\n| `get_slow_queries` | MySQL 5.7.9+ / 8.0+ | ✅ Slow query analysis and performance insights | `Performance Schema`, slow query log |\n| `get_table_io_stats` | MySQL 5.7.9+ / 8.0+ | ✅ Table I/O statistics and access patterns | `Performance Schema` I/O monitoring |\n| `get_lock_monitoring` | MySQL 5.7.9+ / 8.0+ | ✅ Lock analysis and contention monitoring | `Performance Schema` lock tables |\n| `get_all_databases_tables` | MySQL 5.7.9+ / 8.0+ | ✅ Cross-database table overview and analysis | Multi-database `INFORMATION_SCHEMA` queries |\n| `get_all_databases_table_sizes` | MySQL 5.7.9+ / 8.0+ | ✅ Global table size analysis across databases | Aggregated size statistics |\n| `get_connection_info` | MySQL 5.7.9+ / 8.0+ | ✅ Connection details and session information | `performance_schema.processlist` |\n| `get_current_database_info` | MySQL 5.7.9+ / 8.0+ | ✅ Current database context and details | Active database information |\n\n### 🚀 **Version-Aware Enhancements**\n\n| Feature | MySQL 5.7.9+ | MySQL 8.0+ | Enhanced Capabilities |\n|---------|------------|-------------|---------------------|\n| **Performance Schema** | ✅ Basic | ✅ **Enhanced** | MySQL 8.0+: Advanced query monitoring, improved Performance Schema tables |\n| **Information Schema** | ✅ Standard | ✅ **Enhanced** | MySQL 8.0+: Additional metadata tables and improved statistics |\n| **Storage Engine Info** | ✅ InnoDB Focus | ✅ **Multi-Engine** | MySQL 8.0+: Enhanced storage engine statistics and monitoring |\n| **JSON Support** | ✅ Basic | ✅ **Advanced** | MySQL 8.0+: Improved JSON functions and indexing capabilities |\n| **User Management** | ✅ Traditional | ✅ **Role-Based** | MySQL 8.0+: Role-based access control and enhanced security features |\n\n\u003e **📋 MySQL Version Support**: Requires **MySQL 5.7.9 or newer** (5.7.9, 8.0+, 8.4+ are supported). The minimum is dictated by `performance_schema.processlist`, introduced in MySQL 5.7.9 and used by `get_active_connections`, `get_connection_info`, and `get_lock_monitoring`. MySQL 8.1+ and 8.2+ compatibility will be added as they reach stable release status.\n\n---\n\n## Usage Examples\n\n### Claude Desktop Integration\n\n**Method 1: Local MCP (transport=\"stdio\")**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-mysql-ops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--python\", \"3.11\", \"mcp-mysql-ops\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"127.0.0.1\",\n        \"MYSQL_PORT\": \"13306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASSWORD\": \"changeme!@34\",\n        \"MYSQL_DATABASE\": \"test_ecommerce\"\n      }\n    }\n  }\n}\n```\n\n**Method 2: Remote MCP (transport=\"streamable-http\")**\n\n**On MCP-Client Host:**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-mysql-ops\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://localhost:18004/mcp\"\n    }\n  }\n}\n```\n\n**With Bearer Token Authentication (Recommended for production):**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-mysql-ops\": {\n      \"type\": \"streamable-http\", \n      \"url\": \"http://localhost:18004/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secure-secret-key-here\"\n      }\n    }\n  }\n}\n```\n\n\"Display MySQL server capabilities and version information.\"\n![Claude Desktop Integration](img/screenshot-claude-desktop-001.png)\n\n\"Draw relationships as a Mermaid diagram\"\n![Claude Desktop Integration](img/screenshot-claude-desktop-002.png)\n\n(Optional) Run with Local Source:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-mysql-ops\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"python\", \"-m\", \"src.mcp_mysql_ops.mcp_main\"],\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/MCP-MySQL-Ops\",\n        \"MYSQL_HOST\": \"127.0.0.1\",\n        \"MYSQL_PORT\": \"13306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASSWORD\": \"changeme!@34\",\n        \"MYSQL_DATABASE\": \"test_ecommerce\"\n      }\n    }\n  }\n}\n```\n\n### Run MCP-Server as Standalon\n\n#### /w Pypi and uvx (Recommended)\n\n```bash\n# Stdio mode\nuvx --python 3.11 mcp-mysql-ops \\\n  --type stdio\n\n# HTTP mode\nuvx --python 3.11 mcp-mysql-ops\n  --type streamable-http \\\n  --host 127.0.0.1 \\\n  --port 8000 \\\n  --log-level DEBUG\n```\n\n### (Option) Configure Multiple MySQL Instances\n\n```json\n{\n  \"mcpServers\": {\n    \"MySQL-A\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--python\", \"3.11\", \"mcp-mysql-ops\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"a.foo.com\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASSWORD\": \"password\",\n        \"MYSQL_DATABASE\": \"information_schema\"\n      }\n    },\n    \"MySQL-B\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--python\", \"3.11\", \"mcp-mysql-ops\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"b.bar.com\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASSWORD\": \"password\",\n        \"MYSQL_DATABASE\": \"information_schema\"\n      }\n    }\n  }\n}\n```\n\n#### /w Local Source\n\n```bash\n# Method 1: Using installed console script (after pip install -e .)\nmcp-mysql-ops --type stdio\nmcp-mysql-ops --type streamable-http --host 127.0.0.1 --port 8000 --log-level DEBUG\n\n# Method 2: Using module execution\nPYTHONPATH=/path/to/MCP-MySQL-Ops/src\npython -m mcp_mysql_ops --type stdio\npython -m mcp_mysql_ops --type streamable-http --host 127.0.0.1 --port 8000 --log-level DEBUG\n```\n\n---\n\n## Environment Variables\n\n| Variable | Description | Default | Project Default |\n|----------|-------------|---------|-----------------|\n| `PYTHONPATH` | Python module search path for MCP server imports | - | `/app/src` |\n| `MCP_LOG_LEVEL` | Server logging verbosity (DEBUG, INFO, WARNING, ERROR) | `INFO` | `INFO` |\n| `FASTMCP_TYPE` | MCP transport protocol (stdio for CLI, streamable-http for web) | `stdio` | `streamable-http` |\n| `FASTMCP_HOST` | HTTP server bind address (0.0.0.0 for all interfaces) | `127.0.0.1` | `0.0.0.0` |\n| `FASTMCP_PORT` | HTTP server port for MCP communication | `8000` | `8000` |\n| `MYSQL_VERSION` | MySQL major version for Docker image selection | `8.0` | `8.0` |\n| `MYSQL_HOST` | MySQL server hostname or IP address | `127.0.0.1` | `host.docker.internal` |\n| `MYSQL_PORT` | MySQL server port number | `3306` | `13306` |\n| `MYSQL_USER` | MySQL connection username (auto-granted permissions on test DBs) | `root` | `testuser` |\n| `MYSQL_PASSWORD` | MySQL user password (supports special characters) | `changeme!@34` | `testpass` |\n| `MYSQL_DATABASE` | Default database name for connections | `information_schema` | `testdb` |\n| `MYSQL_ROOT_HOST` | MySQL root host access pattern for Docker container | `%` | `%` |\n| `MYSQL_ROOT_PASSWORD` | MySQL root password for Docker container initialization | `changeme!@34` | `changeme!@34` |\n| `DOCKER_EXTERNAL_PORT_OPENWEBUI` | Host port mapping for Open WebUI container | `8080` | `3004` |\n| `DOCKER_EXTERNAL_PORT_MCP_SERVER` | Host port mapping for MCP server container | `8000` | `18004` |\n| `DOCKER_EXTERNAL_PORT_MCPO_PROXY` | Host port mapping for MCPO proxy container | `8000` | `8004` |\n\n**Note**: `MYSQL_DATABASE` serves as the default target database for operations when no specific database is specified. In Docker environments, if set to a custom database name, this database will be automatically created during initial MySQL startup.\n\n**User Permission Management**: When using a non-root `MYSQL_USER`, the initialization process automatically:\n- Creates the specified user if it doesn't exist\n- Grants full permissions on the 4 test databases (`test_ecommerce`, `test_analytics`, `test_inventory`, `test_hr`)\n- Maintains security by restricting access to only the necessary databases\n- Enables monitoring capabilities through automatic information_schema/performance_schema access\n\n---\n\n## Prerequisites\n\n### Minimum Requirements\n- MySQL **5.7.9** or newer (5.7.9+, 8.0+, 8.4+ supported; tested with MySQL 8.0.37). Versions older than 5.7.9 are not supported because the server depends on `performance_schema.processlist`, introduced in 5.7.9.\n- Python 3.11+\n- Network access to MySQL server\n- Read permissions on system databases (`information_schema`, `performance_schema`)\n\n### Recommended MySQL Configuration\n\n**⚠️ Performance Monitoring Settings**:\nSome MCP tools provide enhanced functionality with specific MySQL configuration parameters. These settings are **optional** but recommended for comprehensive monitoring:\n\n**Tools enhanced by these settings**:\n- **get_server_status**: More detailed statistics with Performance Schema enabled\n- **get_index_usage_stats**: Enhanced with Performance Schema table statistics\n- **get_connection_info**: Improved connection tracking with Performance Schema\n\n**Verification**:\nAfter applying any configuration changes, verify the settings:\n```sql\nSHOW VARIABLES LIKE 'performance_schema';\nSHOW VARIABLES LIKE 'information_schema_stats_expiry';\n\n+----------------------------------+-------+\n| Variable_name                    | Value |\n+----------------------------------+-------+\n| performance_schema               | ON    |\n| information_schema_stats_expiry  | 86400 |\n+----------------------------------+-------+\n```\n\n#### Method 1: my.cnf Configuration (Recommended for Self-Managed MySQL)\nAdd the following to your `my.cnf` or `my.ini`:\n\n```ini\n[mysqld]\n# Performance Schema (usually enabled by default in MySQL 8.0+)\nperformance_schema = ON\n\n# Enhanced statistics collection\ninformation_schema_stats_expiry = 0  # Real-time statistics (use 86400 for cached)\n\n# Optional: Enhanced query logging (use carefully in production)\n# slow_query_log = ON\n# slow_query_log_file = /var/log/mysql/slow.log\n# long_query_time = 2\n```\n\nThen restart MySQL server.\n\n#### Method 2: MySQL Startup Parameters\nFor Docker or command-line MySQL startup:\n\n```bash\n# Docker example\ndocker run -d \\\n  -e MYSQL_ROOT_PASSWORD=mypassword \\\n  mysql:8.0 \\\n  --performance-schema=ON \\\n  --information-schema-stats-expiry=0\n\n# Direct mysqld command\nmysqld \\\n  --performance-schema=ON \\\n  --information-schema-stats-expiry=0\n```\n\n#### Method 3: Dynamic Configuration (MySQL 8.0+, AWS RDS, Azure, GCP)\nFor managed MySQL services where you cannot modify `my.cnf`, use SQL commands to change dynamic settings:\n\n```sql\n-- Enable real-time statistics (requires SUPER privilege or SYSTEM_VARIABLES_ADMIN)\nSET GLOBAL information_schema_stats_expiry = 0;\n\n-- Verify Performance Schema status (usually enabled by default)\nSHOW VARIABLES LIKE 'performance_schema';\n\n-- Optional: Enable slow query log for enhanced monitoring\nSET GLOBAL slow_query_log = 'ON';\nSET GLOBAL long_query_time = 2;\n```\n\n**Note for session-level testing**:\n```sql\n-- Set for current session only (temporary)\nSET SESSION information_schema_stats_expiry = 0;\n```\n\n---\n\n## RDS/Aurora MySQL Compatibility\n\n- This server is read-only and works with regular roles on AWS RDS MySQL and Aurora MySQL. All core functionality is available through standard Information Schema and Performance Schema access.\n- Performance Schema is enabled by default on RDS/Aurora MySQL 8.0+ instances.\n- For enhanced monitoring capabilities, consider Parameter Group configuration:\n  ```sql\n  -- Check Performance Schema status\n  SHOW VARIABLES LIKE 'performance_schema';\n\n  -- Verify Information Schema settings\n  SHOW VARIABLES LIKE 'information_schema_stats_expiry';\n\n  -- Recommended user permissions for monitoring\n  GRANT SELECT ON *.* TO \u003cmonitoring_user\u003e@'%';\n  GRANT PROCESS ON *.* TO \u003cmonitoring_user\u003e@'%';\n  ```\n\n---\n\n## Example Queries\n\n### 🟢 Core MySQL Monitoring Tools (Always Available)\n\n- **get_server_info**\n  - \"Show MySQL server version and configuration status.\"\n  - \"Check server system variables and runtime configuration.\"\n  - \"Display MySQL server capabilities and version information.\"\n  - 📋 **Features**: Server version, system variables, configuration status, feature availability\n  - 🔧 **MySQL 5.7.9+/8.0+**: Fully compatible, no additional setup required\n\n- **get_database_list**\n  - \"List all databases and their sizes.\"\n  - \"Show database list with character sets and collation information.\"\n  - \"Display database storage usage and table counts.\"\n  - 📋 **Features**: Database sizes, character sets, collations, table counts, storage usage\n  - 🔧 **MySQL 5.7.9+/8.0+**: Uses Information Schema for comprehensive database information\n\n- **get_table_list**\n  - \"List all tables in the test_ecommerce database.\"\n  - \"Show table information with storage engines and row counts.\"\n  - \"Display table creation dates and update timestamps.\"\n  - 📋 **Features**: Table names, storage engines, row counts, sizes, creation/update times\n  - ⚠️ **Required**: `database_name` parameter must be specified\n  - 💡 **Usage**: Supports filtering by table name patterns\n\n- **get_table_schema_info**\n  - \"Show detailed schema information for the customers table in test_ecommerce database.\"\n  - \"Get column details and constraints for products table in test_ecommerce database.\"\n  - \"Analyze table structure with indexes and foreign keys for orders table in test_ecommerce database.\"\n  - \"Show schema overview for all tables in test_inventory database.\"\n  - 📋 **Features**: Column types, constraints, indexes, foreign keys, table metadata\n  - ⚠️ **Required**: `database_name` parameter must be specified\n  - 💡 **Usage**: Leave `table_name` empty for database-wide schema analysis\n\n- **get_database_overview**\n  - \"Show comprehensive database overview for test_ecommerce database.\"\n  - \"Get detailed summary of test_analytics database structure and statistics.\"\n  - \"Analyze database overview with table counts and sizes for test_inventory database.\"\n  - \"Show database structure summary for test_hr database.\"\n  - 📋 **Features**: Database overview, table statistics, storage summary, schema analysis\n  - ⚠️ **Required**: `database_name` parameter must be specified\n\n- **get_user_list**\n  - \"List all MySQL users and their privileges.\"\n  - \"Show user accounts with host information and account status.\"\n  - \"Display user privilege summary and authentication details.\"\n  - 📋 **Features**: User accounts, host patterns, privileges, account status, authentication info\n  - 🔧 **MySQL 5.7.9+/8.0+**: Enhanced user management information in MySQL 8.0+\n\n- **get_active_connections**\n  - \"Show all active connections and their details.\"\n  - \"List current database connections with user and host information.\"\n  - \"Monitor active sessions and their current operations.\"\n  - \"Display connection statistics and process information.\"\n  - 📋 **Features**: Active connections, process list, connection details, session information\n  - 🔧 **MySQL 5.7.9+/8.0+**: Enhanced process information with Performance Schema integration\n\n- **get_server_status**\n  - \"Show MySQL server status variables and performance counters.\"\n  - \"Display current server performance metrics and statistics.\"\n  - \"Monitor server operational status and key performance indicators.\"\n  - \"Analyze server health metrics and resource utilization.\"\n  - 📋 **Features**: Status variables, performance counters, connection statistics, resource metrics\n  - 🔧 **MySQL 5.7.9+/8.0+**: Comprehensive server status monitoring\n\n- **get_table_size_info**\n  - \"Show table and index size analysis for test_ecommerce database.\"\n  - \"Find largest tables by data and index size.\"\n  - \"Analyze storage efficiency and table size distribution.\"\n  - \"Display table size details with data/index ratios.\"\n  - 📋 **Features**: Table sizes, index sizes, data/index ratios, storage efficiency analysis\n  - ⚠️ **Required**: `database_name` parameter for accurate size analysis\n\n- **get_database_size_info**\n  - \"Show database capacity analysis and storage usage.\"\n  - \"Find the largest databases by total size.\"\n  - \"Display comprehensive database size statistics.\"\n  - \"Analyze storage distribution across databases.\"\n  - 📋 **Features**: Database sizes, table counts, storage distribution, capacity analysis\n  - 🔧 **MySQL 5.7.9+/8.0+**: Accurate size calculation using Information Schema\n\n- **get_index_usage_stats**\n  - \"Analyze index usage and efficiency statistics.\"\n  - \"Show index cardinality and selectivity information.\"\n  - \"Find potentially unused or redundant indexes.\"\n  - \"Display index performance and usage patterns.\"\n  - 📋 **Features**: Index statistics, cardinality, selectivity, usage analysis, optimization recommendations\n  - ⚠️ **Required**: `database_name` parameter for targeted index analysis\n  - 💡 **Enhanced with**: Performance Schema enabled for more detailed statistics\n\n### 🚀 Version-Enhanced Tools\n\n- **get_server_info** (Enhanced!)\n  - \"Show server version and MySQL 8.0 advanced features.\"\n  - \"Check server compatibility and available enhancements.\"\n  - \"Display MySQL version-specific capabilities and recommendations.\"\n  - 📈 **MySQL 8.0+**: Enhanced JSON support, improved Performance Schema, CTE support, window functions\n  - 📊 **MySQL 5.7.9+**: Core functionality with basic JSON and Performance Schema support\n\n### 💡 Natural Language Query Examples\n\nTest tools with realistic prompts - never use function names directly:\n- ✅ \"Show me the current server status and key performance metrics\"\n- ❌ \"Run get_server_status\"\n\n**📊 Monitoring Examples:**\n- \"What databases exist and how much space do they use?\"\n- \"Show me all tables in the ecommerce database with their sizes\"\n- \"Which tables have the most rows and largest indexes?\"\n- \"Display current database connections and their activity\"\n- \"Analyze the schema structure of the test_ecommerce database\"\n- \"Show me MySQL server configuration and performance status\"\n- \"List all users and their database privileges\"\n- \"Find tables that might need index optimization\"\n\n**💡 Pro Tip**: All tools support multi-database operations using the `database_name` parameter. This allows MySQL root users to analyze and monitor multiple databases from a single MCP server instance.\n\n---\n\n## Troubleshooting\n\n### Connection Issues\n1. Check MySQL server status\n2. Verify connection parameters in `.env` file\n3. Ensure network connectivity\n4. Check user permissions and authentication\n\n### Configuration Issues\n1. **\"Access denied\" errors**: Check user privileges\n   ```sql\n   SHOW GRANTS FOR 'username'@'host';\n   ```\n   \n   **Quick fix for monitoring user setup**:\n   ```sql\n   -- Create monitoring user with necessary permissions\n   CREATE USER 'monitoring'@'%' IDENTIFIED BY 'secure_password';\n   GRANT SELECT ON *.* TO 'monitoring'@'%';\n   GRANT PROCESS ON *.* TO 'monitoring'@'%';\n   ```\n\n2. **\"Table doesn't exist\" for Performance Schema**: Check Performance Schema status\n   ```sql\n   SHOW VARIABLES LIKE 'performance_schema';  -- Should be 'ON'\n   ```\n   \n   **Note**: Performance Schema is enabled by default in MySQL 8.0+ but may be disabled in some configurations.\n\n3. **Missing database information**: Verify Information Schema access\n   ```sql\n   SHOW VARIABLES LIKE 'information_schema_stats_expiry';\n   SELECT COUNT(*) FROM information_schema.tables;\n   ```\n   \n   **Quick fix for real-time statistics**:\n   ```sql\n   SET GLOBAL information_schema_stats_expiry = 0;\n   ```\n\n4. **Apply configuration changes**:\n   - **Self-managed**: Add settings to `my.cnf` and restart server\n   - **Managed services**: Use `SET GLOBAL` for dynamic variables or Parameter Groups\n   - **Temporary testing**: Use `SET SESSION` for current session only\n\n### Performance Issues\n1. Use `limit` parameters to reduce result size\n2. Run monitoring during off-peak hours\n3. Check database load before running analysis\n4. Consider setting `information_schema_stats_expiry` for cached statistics\n\n### Version Compatibility Issues\n\n\u003e For more details, see the [## Tool Compatibility Matrix](#tool-compatibility-matrix)\n\n1. **Run compatibility check first**:\n   ```bash\n   # \"Use get_server_info to check version and available features\"\n   ```\n\n2. **Understanding feature availability**:\n   - **MySQL 8.0+**: All features available with enhanced Performance Schema\n   - **MySQL 5.7.9+**: Core functionality with basic Performance Schema support\n   - **Earlier versions (\u003c 5.7.9)**: Not supported — `performance_schema.processlist` is unavailable\n\n3. **If features seem limited**:\n   - Check MySQL version: `SELECT VERSION();`\n   - Verify Performance Schema: `SHOW VARIABLES LIKE 'performance_schema';`\n   - Consider upgrading MySQL for enhanced monitoring capabilities\n\n### Docker-Specific Issues\n1. **Port conflicts**: Default MySQL port 3306 might be in use\n   - Project uses port 13306 by default to avoid conflicts\n   - Check port availability: `netstat -an | grep 13306`\n\n2. **Container startup issues**: Check Docker logs\n   ```bash\n   docker-compose logs mysql\n   docker-compose logs mcp-server\n   ```\n\n3. **Data persistence**: Ensure volume mounts are working\n   ```bash\n   docker volume ls\n   docker volume inspect mcp-mysql-ops_mysql_data\n   ```\n\n---\n\n## 🚀 Adding Custom Tools\n\nThis MCP server is designed for easy extensibility. Follow these 5 simple steps to add your own custom tools:\n\n### Step-by-Step Guide\n\n#### 1. **Add Helper Functions (Optional)**\n\nAdd reusable data functions to `src/\u003cpackage_name\u003e/functions.py`:\n\n```python\nasync def get_your_custom_data(target_resource: str = None) -\u003e List[Dict[str, Any]]:\n    \"\"\"Your custom data retrieval function.\"\"\"\n    # Example implementation - adapt to your service\n    data_source = await get_data_connection(target_resource)\n    results = await fetch_data_from_source(\n        source=data_source,\n        filters=your_conditions,\n        aggregations=[\"count\", \"sum\", \"avg\"],\n        sorting=[\"count DESC\", \"timestamp ASC\"]\n    )\n    return results\n```\n\n#### 2. **Create Your MCP Tool**\n\nAdd your tool function to `src/\u003cpackage_name\u003e/mcp_main.py`:\n\n```python\n@mcp.tool()\nasync def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -\u003e str:\n    \"\"\"\n    [Tool Purpose]: Brief description of what your tool does\n    \n    [Exact Functionality]:\n    - Feature 1: Data aggregation and analysis\n    - Feature 2: Resource monitoring and insights\n    - Feature 3: Performance metrics and reporting\n    \n    [Required Use Cases]:\n    - When user asks \"your specific analysis request\"\n    - Your business-specific monitoring needs\n    \n    Args:\n        limit: Maximum results (1-100)\n        target_name: Target resource/service name\n    \n    Returns:\n        Formatted analysis results\n    \"\"\"\n    try:\n        limit = max(1, min(limit, 100))  # Always validate input\n        \n        results = await get_your_custom_data(target_resource=target_name)\n        \n        if results:\n            results = results[:limit]\n        \n        return format_table_data(results, f\"Custom Analysis (Top {len(results)})\")\n        \n    except Exception as e:\n        logger.error(f\"Failed to get custom analysis: {e}\")\n        return f\"Error: {str(e)}\"\n```\n\n#### 3. **Update Imports (If Needed)**\n\nAdd your helper function to imports in `src/\u003cpackage_name\u003e/mcp_main.py`:\n\n```python\nfrom .functions import (\n    # ...existing imports...\n    get_your_custom_data,  # Add your new function\n)\n```\n\n#### 4. **Update Prompt Template (Recommended)**\n\nAdd your tool description to `src/\u003cpackage_name\u003e/prompt_template.md` for better natural language recognition:\n\n```markdown\n### **Your Custom Analysis Tool**\n\n### X. **get_your_custom_analysis**\n**Purpose**: Brief description of what your tool does\n**Usage**: \"Show me your custom analysis\" or \"Get custom analysis for database_name\"\n**Features**: Data aggregation, resource monitoring, performance metrics\n**Required**: `target_name` parameter for specific resource analysis\n```\n\n#### 5. **Test Your Tool**\n\n```bash\n# Local testing\n./scripts/run-mcp-inspector-local.sh\n\n# Or with Docker\ndocker-compose up -d\ndocker-compose logs -f mcp-server\n\n# Test with natural language:\n# \"Show me your custom analysis\"\n# \"Get custom analysis for target_name\"\n```\n\nThat's it! Your custom tool is ready to use with natural language queries.\n\n---\n\n## Development\n\n### Testing \u0026 Development\n\n```bash\n# Test with MCP Inspector\n./scripts/run-mcp-inspector-local.sh\n\n# Direct execution methods for debugging\n# Method 1: Console script (after pip install -e .)\npip install -e .\nmcp-mysql-ops --log-level DEBUG\n\n# Method 2: Module execution\nPYTHONPATH=src python -m mcp_mysql_ops --log-level DEBUG\n\n# Test with different MySQL versions\n# Modify MYSQL_HOST in .env to point to different MySQL instances\n\n# Run tests (if you add any)\nuv run pytest\n```\n\n### Version Compatibility Testing\n\nThe MCP server automatically adapts to MySQL versions 5.7.9+ and 8.0+. To test across versions:\n\n1. **Set up test databases**: Different MySQL versions (5.7, 8.0, 8.1+)\n2. **Run compatibility tests**: Point to each version and verify tool behavior\n3. **Check feature detection**: Ensure proper version detection and feature availability\n4. **Verify performance**: Confirm optimal performance across MySQL versions\n\n---\n\n## Security Notes\n\n- All tools are **read-only** - no data modification capabilities\n- Sensitive information (passwords) are masked in outputs\n- No direct SQL execution - only predefined, safe queries\n- Follows principle of least privilege\n- Compatible with MySQL security best practices\n\n---\n\n## Contributing\n\n🤝 **Got ideas? Found bugs? Want to add cool features?**\n\nWe're always excited to welcome new contributors! Whether you're fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better.\n\n**Ways to contribute:**\n- 🐛 Report issues or bugs\n- 💡 Suggest new MySQL monitoring features\n- 📝 Improve documentation \n- 🚀 Submit pull requests\n- ⭐ Star the repo if you find it useful!\n\n**Pro tip:** The codebase is designed to be super friendly for adding new tools. Check out the existing `@mcp.tool()` functions in `mcp_main.py`.\n\n---\n\n## MCPO Swagger Docs\n\n\u003e [MCPO Swagger URL] http://localhost:8004/mysql-ops/docs\n\n![MCPO Swagger APIs](img/screenshot-swagger-api-docs.png)\n\n---\n\n## License\nFreely use, modify, and distribute under the **MIT License**.\n\n---\n\n## ⭐ Other Projects\n\n**Other MCP servers by the same author:**\n\n- [MCP-PostgreSQL-Ops](https://github.com/call518/MCP-PostgreSQL-Ops)\n- [MCP-Airflow-API](https://github.com/call518/MCP-Airflow-API)\n- [MCP-Ambari-API](https://github.com/call518/MCP-Ambari-API)\n- [LogSentinelAI - LLB-Based Log Analyzer](https://github.com/call518/LogSentinelAI)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcall518%2Fmcp-mysql-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcall518%2Fmcp-mysql-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcall518%2Fmcp-mysql-ops/lists"}