Architecture

Architecture

🚀 Value Proposition

Understand the core mechanics of mysql-mcp. It uses an Adaptive Instruction Architecture. This ensures maximum efficiency for AI agents. Reduce token usage drastically with isolated sandboxing. Switch seamlessly between transports. Enforce enterprise-level security via 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, 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.
• chore(tests): strengthen anti-hallucination guardrails across coordinator workflows.
• 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.