Architecture

Architecture

🚀 Value Proposition

Unleash your AI agents with mysql-mcp's Adaptive Instruction Architecture. Built for mission-critical enterprise environments. It guarantees efficiency, security, and scalability. Slash token consumption with V8 sandboxing. Toggle dynamic transports seamlessly. Lock down data with OAuth 2.1. Rely on strict schema validation powered by Zod's Standard Schema.

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

Our Adaptive Instruction Architecture statically compiles modular markdown into an ultra-lean build-time artifact. By transmitting a pristine pointer string to the client, we obliterate token bloat while unlocking dynamic, context-aware 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 at the MCP boundary, we gracefully trap validation errors and return them as an ErrorResponse (without throwing), enforcing "strict schema validation".