Architecture

Architecture

🚀 Value Proposition

Unleash your AI agents with mysql-mcp's Adaptive Instruction Architecture. Built for mission-critical enterprise environments. It guarantees unprecedented efficiency, ironclad security, and limitless scalability. Slash token consumption with V8 sandboxing. Toggle dynamic transports seamlessly. Lock down data with OAuth 2.1.

For the complete architectural layout, logic flows, and module tree, please see the code-map.md file in the main repository.

The mysql-mcp project uses the Adaptive Instruction Architecture. We compile modular markdown files into a single build-time artifact. We transmit a slim pointer string to the client. We expose dynamic help via mysql://help resources.

⚡ Unlock Core Capabilities

• 241 Specialized Tools distributed across 28 Tool Groups to handle everything from CRUD to Spatial analysis.
• 16 Shortcuts (Tool Filtering) to easily configure context-friendly setups.
• 23 Observability Resources and 19 AI-Powered Prompts to empower proactive agent workflows.

🏗️ Scale Infrastructure Seamlessly

• Code Mode Execution: Powered by an isolated-vm sandbox, massively reducing token overhead—translating to massive cost savings for enterprise scaling—with a configurable payload cap (default 100KB, up to 50MB) and built-in rate limiting.
• Supported Transports: Seamlessly switch between stdio, http (Streamable HTTP /mcp), and sse (Legacy /sse).
• Authentication: Enterprise-ready security with Simple Bearer Token or full OAuth 2.1 (RFC 9728/8414) via Keycloak.

🔄 Review Recent Enhancements

• fix(security): allow mask data alias validation at MCP boundary.
• docs(tests): strengthen anti-hallucination guardrails across coordinator workflows (list_dir requirements, task.md checklist).
• fix(core): add conditional update aliases for data and conditions.
• fix(security): require at least one filter for audit tool to prevent payload bloat.
• fix(optimization): allow database-wide index audit in indexRecommendation by removing empty payload validation.
• test(http): streamable and http transport tests added.

📏 Enforce Builder Standards

• Dual-Schema Pattern: Tools use a plain z.object() Base schema for MCP parameter visibility, and a z.preprocess() wrapper for handler parsing to support aliases and coercion without breaking standard JSON Schema generation. By invoking Zod 4's Standard Schema spec and strict .safeParse() execution, we enforce "Zero-Hallucination Execution".