Architecture

Architecture

🚀 Value Proposition

Unleash the full potential of your AI agents with mysql-mcp's state-of-the-art Adaptive Instruction Architecture. Built for mission-critical enterprise environments, it guarantees unprecedented efficiency, ironclad security, and limitless scalability. Drastically slash token consumption with native V8 sandboxing, seamlessly toggle between dynamic transports, and lock down your data with zero-trust OAuth 2.1 compliance.

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, where modular markdown files (src/constants/server-instructions/*.md) are compiled into a single build-time artifact, transmitting a slim pointer string to the client and exposing dynamic help via mysql://help resources.

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.
• 21 Observability Resources and 28 AI-Powered Prompts to empower proactive agent workflows.

Infrastructure & Transport

• Code Mode Execution: Powered by an isolated-vm sandbox, massively reducing token overhead with a strict 100KB payload cap 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.

Recent Architecture Changes & Fixes

• 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(admin): make server config action required and fix audit default limit.
• fix(sysschema): strict validation and aliases for user and host summaries.
• fix(docstore): add alias handling for collectionName.
• fix(core): add conditional update aliases for data and conditions.
• fix(optimization): allow database-wide index audit in indexRecommendation by removing empty payload validation.

MCP Builder Rules & 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.