V2.9.1

.agent/rules/04_best_practices.md

@@ -100,6 +100,12 @@ Beyond hard constraints, following established patterns ensures code durability,
 - Release notes MUST be verified during the `/release-manager` orchestration to prevent omission on the remote repository.
 - Ensure `releases/v[VERSION].md` exists and is synchronized with the current release.
 - **STRICT PROHIBITION**: Never modify or update the release notes of previous versions (`releases/v[OLD_VERSION].md`). Only update or edit the release notes corresponding to the current release version.
+- **SIMULTANEOUS UPDATE**: Release notes (`releases/v[VERSION].md`) MUST be updated or regenerated whenever the `Changelog` is modified to ensure version/metadata synchronization.
+
+### 16. Unit Test Decomposition
+
+- Unit tests MUST be decomposed into small, focused, human-assimilable subtests (e.g. using `subtest` blocks in Perl/Test::More) rather than monoliths to improve readability and debuggability.
+- **ADD TESTS FOR ALL CHANGES**: Every code change, modification, or enhancement MUST be accompanied by dedicated unit tests to prove correctness and prevent regressions.
 
 ## ✅ Verification
 

.agents/AGENTS.md

@@ -0,0 +1,6 @@
+# Agent Custom Rules
+
+- Always update the release notes (`releases/v[VERSION].md`) at the same time as the `Changelog`.
+- Decompose unit tests into human-assimilable parts (for example, using structured subtests).
+- Systematically add unit tests to validate every code modification.
+- For each modification, add an issue with the correct tags in Major's project and assign it to jmrenouard.

.husky/pre-commit

@@ -1,8 +1,25 @@
 #!/bin/sh
 
-# Only run tests if code, tests, build scripts, Makefile, or package configuration has changed
+# Only run checks/tests if code, tests, build scripts, Makefile, or package configuration has changed
 if git diff --cached --name-only | grep -qE '\.(pl|pm)$|^tests/|^build/|^Makefile$|^package(-lock)?\.json$'; then
+  # 1. Formatting check
+  echo "Husky [pre-commit]: Checking formatting tidiness..."
+  if ! make check-tidy; then
+    echo "ERROR [pre-commit]: mysqltuner.pl is not formatted correctly according to perltidy."
+    echo "Please run: make tidy (or format manually) before committing."
+    exit 1
+  fi
+
+  # 2. SQL Static Linter check
+  echo "Husky [pre-commit]: Running SQL static linter..."
+  if ! perl build/check_sql_linter.pl; then
+    echo "ERROR [pre-commit]: Embedded SQL queries did not pass the static linter."
+    exit 1
+  fi
+
+  # 3. Unit test execution
+  echo "Husky [pre-commit]: Executing unit test suite..."
   npm test
 else
-  echo "Husky [pre-commit]: No code or test files modified. Skipping unit tests."
+  echo "Husky [pre-commit]: No code or test files modified. Skipping checks."
 fi

AGENT.md

@@ -0,0 +1,155 @@
+# AI Agent Integration Guide & Model Context Protocol (MCP) Server
+
+This document explains how AI coding assistants, autonomous database agents, and developer workflows can utilize MySQLTuner via the **Model Context Protocol (MCP)** or direct `--agent-json` CLI queries to audit and optimize database instances safely.
+
+---
+
+## 🚀 Overview of Integration Modes
+
+MySQLTuner supports two native modes for machine integration:
+1. **Direct CLI (`--agent-json` mode)**: High-speed, zero-dependency JSON output representing actionable recommendations. Excellent for scripts and one-off agent executions.
+2. **MCP Server (stdio transport)**: Standardized protocol interface exposing tools and resources for LLM agents to query state, run audits, and execute rollback-enabled database optimizations.
+
+---
+
+## 1. Direct CLI Integration: `--agent-json`
+
+When running with `--agent-json`, MySQLTuner suppresses all human-readable ANSI terminal outputs and prints a single, structured JSON payload to stdout containing actionable findings.
+
+### CLI Invocation
+```bash
+perl mysqltuner.pl --agent-json --host <db_host> --user <db_user> --pass <db_pass>
+```
+
+### Output Schema Definition
+Each recommendation returned in the `findings` list adheres to the following structure:
+
+- **`id`**: Unique deterministic identifier for the recommendation type (e.g., `innodb_buffer_pool_size_adjust`).
+- **`topic`**: Category of the finding (`Performance`, `Security`, `Reliability`, `Modeling`, `Replication`).
+- **`description`**: Human-readable explanation of the issue.
+- **`impact_score`**: Estimated benefit score from `1` (lowest) to `10` (highest).
+- **`risk_level`**: Safety assessment associated with applying the recommendation (`Low`, `Medium`, `High`, `Critical`).
+- **`risk_description`**: Potential side effects (e.g. table locks, memory consumption).
+- **`requires_restart`**: Boolean (`true`/`false`) indicating if the change requires restarting the database service.
+- **`expected_outcome`**: Predicted benefit (e.g. "Reduces disk I/O").
+- **`action`**: Object containing:
+  - `type`: Either `SQL` (can be executed live) or `Config` (requires editing `my.cnf`).
+  - `statement`: The exact statement to execute or configuration line to write.
+  - `rollback_statement`: The exact command to revert the action to its original baseline state.
+
+### Actionable JSON Output Example
+```json
+{
+  "findings": [
+    {
+      "id": "innodb_buffer_pool_size_adjust",
+      "topic": "Performance",
+      "description": "InnoDB buffer pool size is under-allocated for the current workload.",
+      "impact_score": 9,
+      "risk_level": "Medium",
+      "risk_description": "Increases memory consumption. Ensure sufficient OS-free RAM to prevent OOM swapping.",
+      "requires_restart": false,
+      "expected_outcome": "Reduces disk I/O and increases query cache read hits.",
+      "action": {
+        "type": "SQL",
+        "statement": "SET GLOBAL innodb_buffer_pool_size = 1073741824;",
+        "rollback_statement": "SET GLOBAL innodb_buffer_pool_size = 134217728;"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 2. Model Context Protocol (MCP) Integration
+
+The containerized MCP server integrates directly with client systems (like Cursor, Claude Desktop, Antigravity, or custom LangChain/LlamaIndex pipelines).
+
+### Running the MCP Service Container
+Deploy the Docker image next to your database server:
+```bash
+docker run -d \
+  --name mysqltuner-mcp \
+  -e DB_HOST=mysql-server \
+  -e DB_USER=root \
+  -e DB_PASSWORD=secret_pass \
+  -e AUDIT_INTERVAL_HOURS=12 \
+  -v /var/cache/mysqltuner:/var/cache/mysqltuner \
+  mysqltuner-mcp
+```
+
+### Connecting to the MCP Server
+Clients communicate with the server over **stdio** (standard input/output) transport.
+Configure your agent IDE config (e.g. `project_config.json` or CLAUDE desktop config) to spawn the server:
+```json
+{
+  "mcpServers": {
+    "mysqltuner": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "DB_HOST=127.0.0.1", "mysqltuner-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Exposed MCP Tools & Resources
+
+### MCP Resources (Observability)
+- **`mysqltuner://reports/latest.json`**: Accesses the latest cached JSON report containing findings and DB variables status.
+- **`mysqltuner://reports/latest.html`**: Retreives the complete interactive pgBadger-inspired HTML analytics dashboard.
+
+### MCP Tools (Actions)
+Agents can invoke these JSON-RPC methods:
+
+1. **`get_latest_audit`**
+   - *Description*: Retrieves cached audit findings instantly without stressing the database.
+   - *Arguments*: None.
+
+2. **`run_audit`**
+   - *Description*: Triggers a fresh run of the Perl engine and returns immediate recommendations.
+   - *Arguments*: None.
+
+3. **`apply_recommendation`**
+   - *Description*: Applies a safe `SQL` adjustment (e.g. `SET GLOBAL`).
+   - *Arguments*: 
+     - `statement` (string, required): The SQL command to execute.
+     - `variable_name` (string, optional): Variable name being changed to capture and save the rollback state.
+
+4. **`rollback_recommendation`**
+   - *Description*: Reverts a previously executed command using cached transaction state.
+   - *Arguments*:
+     - `statement_id` (string, required): The ID of the transaction to revert.
+
+---
+
+## 🧠 Step-by-Step AI Agent Playbook
+
+An AI agent performing database maintenance should follow this operational path:
+
+```mermaid
+graph TD
+    A[Start: Read Latest Audit] --> B{Are there findings?}
+    B -- No --> C[End: Database is Tuned]
+    B -- Yes --> D[Filter findings by Risk Level]
+    D --> E[Filter: Risk <= Medium]
+    E --> F[Present to User: Statement & Rollback]
+    F --> G{User Confirms?}
+    G -- No --> H[Skip recommendation]
+    G -- Yes --> I[Execute apply_recommendation]
+    I --> J{Performance OK?}
+    J -- Yes --> K[Log Transaction Success]
+    J -- No --> L[Execute rollback_recommendation]
+```
+
+### Agent Prompt Instructions Template (Copy-Paste for LLM Context)
+> "You have access to the MySQLTuner MCP server. Your goal is to analyze database performance, propose optimizations, and execute them safely.
+> 1. Run `get_latest_audit` to fetch current recommendations.
+> 2. For each recommendation, analyze the `impact_score`, `risk_level`, and `requires_restart`.
+> 3. Highlight recommendations with high `impact_score` (>=7) and safe `risk_level` (Low or Medium).
+> 4. Present these recommendations to the user, showing the `description`, the exact `statement` to apply, and the `rollback_statement`.
+> 5. Wait for user consent.
+> 6. After confirmation, call `apply_recommendation` to execute the SQL.
+> 7. If the user complains of issues or latency spikes, run `rollback_recommendation` immediately with the returned `statement_id` to restore original performance levels."

CURRENT_VERSION.txt

@@ -1 +1 @@
-2.9.0
+2.9.1

Changelog

@@ -1,5 +1,108 @@
 # MySQLTuner Changelog
 
+2.9.1 2026-07-27
+
+- chore(build): allow build scope in compliance auditor
+- chore(build): rewrite dev_sync and doc_sync in Perl for consistency
+- chore(deps): update actions/checkout action to v7.0.0 (#961)
+- chore(deps): update all non-major dependencies (@commitlint/cli, @commitlint/config-conventional, brace-expansion, commitizen)
+- chore(deps): update devops-infra/action-commit-push digest to f27e0951b748268e6ac8d91861eeac5bc2bd36a8 (#958)
+- chore(deps): update devops-infra/action-commit-push digest to fa0c793 (#929)
+- chore(deps): update docker/build-push-action digest to 53b7df9 (#939)
+- chore(deps): update docker/login-action digest to abd2ef4 (#962)
+- chore(deps): update docker/login-action digest to af1e73f (#940)
+- chore(deps): update docker/setup-buildx-action digest to bb05f3f5519dd87d3ba754cc423b652a5edd6d2c (#959)
+- chore(deps): update github/codeql-action digest to 99df26d4f13ea111d4ec1a7dddef6063f76b97e9
+- chore(deps): update shogo82148/actions-setup-mysql digest to 076e636 (#930)
+- chore(deps): update softprops/action-gh-release digest to 718ea10 (#934)
+- chore(deps): update ubuntu:latest docker digest to 53958ec (#935)
+- chore(deps): update ubuntu:latest docker digest to b7f48194d4d8b763a478a621cdc81c27be222ba2206ca3ca6bc42b49685f3d9e
+- chore(docs): add custom rule for GitHub issue creation
+- chore(docs): implement rule to decompose unit tests into readable segments
+- chore(docs): update agent best practices and customization rules
+- chore(main): add doc links in localhost warnings and support custom local subdomains
+- chore(main): hide hostname, ssl, and replication warnings on localhost (#933)
+- chore(releases): start v2.9.1 branch with version bump and dependency updates
+- chore: automated project metadata update
+- chore: remove execution.log from git repository and sync docs
+- feat(cli): implement agent-json flag returning structured actionable schema (#955, jmrenouard#63)
+- feat(cli): resolve remote memory, socket override, and temptable sizing issues (#923)
+- feat(container): implement dockerized auditing daemon and zero-dependency MCP server (#954, jmrenouard#62)
+- feat(main): audit InnoDB lock monitors and print all deadlocks configuration
+- feat(main): enhance error log parser with OOM, semaphore waits, file limits, and page corruption alerts (#953)
+- feat(main): implement advanced log parser and lock monitoring (#953, jmrenouard#61)
+- feat(main): implement experimental Correlation Engine linking PFS wait events and CPU load with log events
+- feat(metadata): fix test badge and update version references in READMEs
+- feat(report): add pgBadger-inspired query, lock, and temp table visual analytics to HTML report (#791)
+- feat(report): add verbose timings, step percentages, and snapshot summary
+- feat(report): finalize HTML report, YAML output, and historical comparison
+- feat(report): implement HA InnoDB Cluster diagnostics and Group Replication checks
+- feat(report): implement advanced Galera Cluster 4 and PXC 8.0 diagnostics
+- feat(report): implement phase 6 deep engine tuning and mark phase 8 completed
+- feat(report): implement workload traffic profiling and query waits analysis (#960)
+- feat: recommend slow query log when disabled (#517)
+- fix(container): create default /defaults.cnf in Dockerfile and document volume mounts (#932)
+- fix(main): add undefined/NULL guards to hr_num to resolve uninitialized warnings (#904)
+- fix(main): address PR #931 code review feedback and enhance test validations
+- fix(main): calculate query cache efficiency using Com_select on MariaDB (MDEV-4981) (#927)
+- fix(main): exclude MariaDB user roles and support zero-config TLS (#936, #937)
+- fix(main): only recommend increasing innodb_log_buffer_size when log waits occur (#938)
+- fix(main): query events_errors_summary_global_by_error safely (#956, jmrenouard#64)
+- fix(main): resolve uninitialized warnings in auto-increment audit and fix split delimiters (#913)
+- fix(main): support '0' and 'OFF' value representations when checking slow query log status (#517) (finalized implementation)
+- fix: update documentation and code
+- test(hook): verify pre-commit hook runs tests when test files change
+- test(lab): add HA topology E2E tests, MCP server E2E test, and dedicated output analyzer
+- test(lab): add HA validation profiles (galera.json, innodb_cluster.json, replication.json)
+- test(lab): add build/analyze_mt_output.pl dedicated output analyzer with HA profile support
+- test(lab): add build/test_ha.sh E2E orchestrator for Galera, InnoDB Cluster, and Replication topologies
+- test(lab): add e2e_mcp_server.t for MCP server E2E validation with live MariaDB container
+- test(lab): add unit test test_issue_810.t for issue 810 (#810)
+- test(lab): expand unit tests for issue #517 to verify alternative representations of slow query log active state (#517)
+- test(test): add unit tests for issues #553, #605, #671, #770, #774, #777, #781, #782, #783, #796 (#553, #605, #671, #770, #774, #777, #781, #782, #783, #796)
+- test(test): add unit tests for issues #863, #864, #869, #874, #875, #881, #887 (#863, #864, #869, #874, #875, #881, #887)
+- test(test): add unit tests for issues #896, #900, #904, #913, #923, #927, #932, #938 (#896, #900, #904, #913, #923, #927, #932, #938)
+- test(test): add unit tests for potential issues and split unit_coverage_boost3
+- test(test): add unit_agent_json.t to validate actionable JSON schema (#955)
+- test(test): add unit_deadlocks_pfs.t to validate InnoDB deadlock PFS checks
+- test(test): add unit_eol_warnings.t to validate version support warnings
+- test(test): add unit_galera_pxc.t to validate Phase 9 Galera cluster checks
+- test(test): add unit_ha_cluster.t to validate Phase 7 HA cluster checks
+- test(test): add unit_log_parser.t to validate advanced log parsing and correlation (#953)
+- test(test): add unit_mcp_server.t to validate JSON-RPC protocol compliance (#954)
+- test(test): add unit_replication_internals.t to validate Phase 8 replication features
+- test(test): add unit_version_helpers.t to validate version caching and helpers
+- test(test): add unit_workload_traffic.t to validate Phase 11 workload profiling (#960)
+- test(test): split unit_coverage_boost3.t into three smaller test files
+- test(test): update workload traffic and HA cluster unit tests to use tab-delimited mock data
+- test(test): verify replication terminology and checksums in unit tests (#888)
+- ci(build): implement static SQL linter and fix PFS deadlock error query
+- ci: optimize pre-commit hook to only run unit tests when code, tests, or dependencies are modified
+- docs(metadata): promote HTML reports and add E2E examples
+- docs(metadata): remove timestamp from doc-sync generated files
+- docs(releases): regenerate release notes and changelog
+- docs(roadmap): add Phase 22 for High Availability & Replication Auto-Discovery
+- docs(roadmap): add Phase 24 (Boolean Normalization), Phase 25 (Deprecated Variables), Phase 26 (Subtest Decomposition) to ROADMAP.md
+- docs(roadmap): add Phase 27 (Multi-Language Normalization), Phase 28 (CI Version Matrix), Phase 29 (Publish Pipeline), Phase 30 (Build Stack Rationalization) from transversal audit
+- docs(roadmap): group strategic technical evolutions into phases 18 to 21
+- docs(roadmap): link strategic technical evolutions specification and enforce changelog staging
+- docs(roadmap): mark Phase 12 as completed in ROADMAP.md
+- docs(roadmap): mark Phase 16 and 17 as completed in ROADMAP.md
+- docs(roadmap): update Phase 7, Phase 9, Phase 10, and Phase 11 status to completed in ROADMAP.md
+- docs: add AGENT.md integration guide for AI and MCP server
+- docs: add LightPath as sponsor, relocate coffee button, and use star-history chart
+- docs: add MCP and AI integration guide for MySQL database tuning
+- docs: generate FEATURES.md
+- docs: generate end-of-life status files
+- docs: link recent features to GitHub issues in Changelog
+- docs: link recent features to jmrenouard fork issues in Changelog
+- docs: regenerate release notes
+- docs: update potential issues log with Phase 9 Galera audit findings
+- docs: update potential issues log with Renovate dependency dashboard analysis
+- docs: update potential issues log with release v2.9.0 and v2.9.1 audit results
+- docs: update repository links to major/MySQLTuner-perl and add GitHub stars badge
+- style: tidy mysqltuner.pl
+
 2.9.0 2026-07-03
 
 - chore(build): allow build scope in compliance auditor
@@ -56,6 +159,7 @@
 - test(lab): add unit test test_issue_517.t for slow query log recommendations (#517)
 - test(lab): add unit test test_issue_810.t for issue 810
 - test(lab): add unit test test_issue_810.t for remote host forcemem MB interpretation correctness (issue #810)
+- test(lab): add unit test test_issue_932.t for Dockerfile and README volume mount documentation (#932)
 - test(lab): add unit test test_issue_938.t for InnoDB write log efficiency
 - test(lab): add unit tests for query cache efficiency logic on MySQL and MariaDB in tests/test_issue_927.t (renamed from tests/issue_927.t).
 - test(lab): normalize all repro_issue_*.t and issue_*.t test file names to test_issue_*.t

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:latest@sha256:53958ec7b67c2c9355df922dd08dbf0360611f8c3cdb656875e81873db9ffdba
+FROM ubuntu:latest@sha256:b7f48194d4d8b763a478a621cdc81c27be222ba2206ca3ca6bc42b49685f3d9e
 
 LABEL maintainer="jmrenouard@gmail.com"
 
@@ -20,6 +20,7 @@ RUN apt clean all
 WORKDIR /
 COPY ./mysqltuner.pl /mysqltuner.pl 
 COPY ./basic_passwords.txt /basic_passwords.txt
+RUN touch /defaults.cnf
 
 #Problem with generateion of CVE files
 COPY ./vulnerabilities.csv /vulnerabilities.txt
@@ -28,4 +29,4 @@ ENTRYPOINT [ "perl", "/mysqltuner.pl", "--passwordfile", "/basic_passwords.txt",
   "--nosysstat", "--defaults-file", "/defaults.cnf", "--cvefile", "/vulnerabilities.txt", \
   "--dumpdir", "/results", "--outputfile", \
   "/results/mysqltuner.txt", \
-  "--reportfile", "/results/mysqltuner.html" , "--verbose" ]
+  "--reportfile", "/results/mysqltuner.html" ]