MCP-MySQL-Ops copilot-instructions.md

MCP MySQL Operations Server - AI Coding Agent Instructions

Architecture Overview

This is a Model Context Protocol (MCP) server built with FastMCP that provides MySQL database monitoring and operations through natural language queries. The server acts as a safe, read-only bridge between AI assistants and MySQL databases.

Core Components

• mcp_main.py: Main MCP server with 19+ @mcp.tool() decorated functions
• functions.py: Database connection layer using aiomysql with multi-database support
• version_compat.py: MySQL 5.7.9+ and 8.0+ version detection and adaptive feature handling (MIN_SUPPORTED_VERSION = 5.7.9 is enforced via ensure_min_supported_version)
• prompt_template.md: Comprehensive prompt definitions loaded via @mcp.prompt() decorators
• Docker stack: MySQL + MCP server + MCPO proxy + Open WebUI integration

Key Patterns

Multi-Database Architecture: All tools accept optional database_name parameter to target specific databases while maintaining a default connection database from MYSQL_DATABASE env var.

Performance Schema Integration: Core functionality leverages MySQL's Performance Schema and Information Schema. Tools automatically detect available features and adapt accordingly.

Version-Aware Tools: Use version_compat.py for MySQL 5.7.9+/8.0+ compatibility. Tools auto-adapt features based on detected version, and ensure_min_supported_version() raises UnsupportedMySQLVersionError for servers older than 5.7.9 (which lack performance_schema.processlist). MySQL 8.0+ recommended for enhanced capabilities.

Tool Structure: Each MCP tool follows this pattern:

@mcp.tool()
async def get_something(limit: int = 20, database_name: str = None) -> str:
    """Detailed docstring with [Tool Purpose], [Exact Functionality], [Required Use Cases], [Strictly Prohibited Use Cases]"""
    try:
        # Validate inputs (limit constraints: max 1-100)
        # Execute queries via functions.py
        # Return formatted table data
    except Exception as e:
        logger.error(f"Failed to...: {e}")
        return f"Error: {str(e)}"