mysql-aiops 0.1.0__tar.gz

mysql_aiops-0.1.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

mysql_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

mysql_aiops-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.coverage

mysql_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to mysql-aiops are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic
+versioning (currently 0.x preview — the API may change).
+
+## v0.1.0 — 2026-07-17
+
+Initial preview release: governed AI-ops for **MySQL 8.x and MariaDB 10.6+ DBA
+operations** — connecting via **PyMySQL** and reading `information_schema` /
+`performance_schema` — with a bundled governance harness. **Mock-validated only
+— not run against a live server.** Community-maintained; not affiliated with
+Oracle or the MariaDB Foundation.
+
+### Added
+
+- **PyMySQL connection layer** (`mysql_aiops.connection`) — parameterised reads
+  with a `DictCursor`, autocommit for maintenance statements (OPTIMIZE /
+  ANALYZE / KILL), 30s connect/read/write timeouts, an injectable connection
+  for tests, teaching error translation (`MySQLError`, with connect / privilege
+  / missing-performance_schema hints), and **flavor detection** (mysql vs
+  mariadb from `version()`) so flavor-dependent statements branch
+  (`SHOW REPLICA STATUS` vs `SHOW SLAVE STATUS`;
+  `performance_schema.data_lock_waits` vs `information_schema.innodb_lock_waits`).
+- **33 governed MCP tools**, every one wrapped with `@governed_tool`:
+  - **Overview** — `overview` (one-shot server health snapshot incl. flavor,
+    connection headroom, replica role).
+  - **Server** — `server_version`, `show_variables`, `show_status`,
+    `list_databases`, `list_engines`, `connection_stats`.
+  - **Activity** — `list_sessions`, `long_running_queries`,
+    `list_transactions`, `lock_waits`.
+  - **Queries** — `top_queries` (statement digests), `explain_query`
+    (EXPLAIN FORMAT=JSON).
+  - **Indexes** — `unused_indexes`, `redundant_indexes`, `index_stats`.
+  - **Tables** — `table_sizes`, `table_fragmentation`, `table_status`.
+  - **Replication** — `replica_status`, `binlog_status`.
+  - **Analysis (flagship)** — `slow_query_rca`, `lock_wait_rca` (incl. last
+    deadlock parsed from `SHOW ENGINE INNODB STATUS`), `replication_lag_rca`,
+    `fragmentation_analysis`.
+  - **Writes** — `kill_session` (high), `kill_query` (high), `drop_index`
+    (high), `optimize_table` (medium), `analyze_table` (medium), `create_index`
+    (medium), `set_global_variable` (medium), `reset_query_stats` (medium).
+- **Guarded writes** — every write supports a `dry_run` preview and (at the
+  CLI) double confirmation. Reversible writes fetch the **real before-state**
+  and record a faithful inverse: `create_index`↔`drop_index` (drop rebuilds the
+  index definition from `SHOW CREATE TABLE` so undo recreates it exactly;
+  the descriptor replays through `create_index(definition=...)`);
+  `set_global_variable` captures the prior value from `SHOW GLOBAL VARIABLES`.
+  Irreversible ops record prior state for audit but no undo.
+- **SQL-injection defenses** — all values are bound query parameters; the few
+  identifiers that cannot be parameterised (schema/table/index/column/variable
+  names, ORDER BY columns) are validated against a strict charset / allow-lists
+  and backtick-quoted before interpolation. EXPLAIN rejects multi-statement
+  input.
+- **Bundled governance harness** (`mysql_aiops.governance`) — audit log, policy
+  engine, token/runaway budget guard, undo-token recording, graduated risk
+  tiers (secure by default: high-risk needs a named approver), output
+  `sanitize`. State under `~/.mysql-aiops/` (relocatable via
+  `MYSQL_AIOPS_HOME`).
+- **Encrypted secret store** — account passwords in `~/.mysql-aiops/secrets.enc`
+  (Fernet + scrypt); legacy `MYSQL_<TARGET>_PASSWORD` env fallback +
+  `secret migrate`.
+- **CLI** — `init` wizard (targets, TLS mode with verify_ca/verify_identity,
+  encrypted password, seeded rules.yaml), `overview`, `server`, `activity`,
+  `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`,
+  `doctor` (connectivity + flavor + performance_schema + replica-role probes),
+  `mcp`.
+
+### Known limitations
+
+- Preview / mock-only: the `information_schema` / `performance_schema` queries
+  need live verification against MySQL 8.x and MariaDB 10.6+.
+- `top_queries` / `slow_query_rca` require `performance_schema=ON`.
+- `SET GLOBAL` changes are runtime-only (persist in my.cnf / SET PERSIST
+  yourself).
+- Coverage is a curated subset of MySQL's surface; open an issue/PR for gaps.
+
+[v0.1.0]: https://github.com/AIops-tools/MySQL-AIops/releases/tag/v0.1.0

mysql_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mysql_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: mysql-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for MySQL/MariaDB DBA operations: slow-query RCA, InnoDB lock-wait & deadlock analysis, replication-lag RCA and fragmentation analysis with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pymysql<2.0,>=1.1
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/mysql-aiops -->
+
+# MySQL AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Oracle Corporation or the MariaDB Foundation.** "MySQL" is a trademark of Oracle Corporation; "MariaDB" is a trademark of MariaDB plc; all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **MySQL 8.x and MariaDB 10.6+ DBA operations** — connecting
+to a server with **PyMySQL** and reading `information_schema` /
+`performance_schema` — with a **built-in governance harness**: unified audit
+log, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. The server **flavor** (mysql vs mariadb) is
+detected from `version()` and flavor-dependent statements branch automatically
+(`SHOW REPLICA STATUS` vs `SHOW SLAVE STATUS`).
+**Preview — mock-validated only, not run against a live server.**
+
+## What it does
+
+Four flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Slow-query RCA** — take the worst `events_statements_summary_by_digest`
+  entry (plus an optional `EXPLAIN FORMAT=JSON` plan) and map its numbers —
+  no-index share (`SUM_NO_INDEX_USED`), lock-time share, rows-examined/sent
+  ratio, tmp-disk spill, call count, plan access types — to a cited cause and a
+  concrete action. Every finding carries its measured number, not a black-box
+  verdict.
+- **InnoDB lock-wait & deadlock chain RCA** — build the wait-for tree from
+  `performance_schema.data_lock_waits` (MariaDB:
+  `information_schema.innodb_lock_waits`), name the **root blocker** (blocks
+  others, waits on none), and parse the **last deadlock** out of
+  `SHOW ENGINE INNODB STATUS`.
+- **Replication lag RCA** — map the replica's IO/SQL thread state,
+  `Seconds_Behind_Source` and error fields to a cited cause + action
+  (stopped IO thread, failed applier statement, lagging applier, intentional
+  `SQL_Delay`).
+- **Table fragmentation analysis** — rank tables by reclaimable `data_free`
+  from `information_schema.tables` into cited `OPTIMIZE TABLE` candidates.
+
+## What works
+
+- **CLI** (`mysql-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`mysql-aiops mcp` or `mysql-aiops-mcp`): **33 tools** (25 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the account password lives in an encrypted store `~/.mysql-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `MYSQL_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
+- **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse — `create_index`↔`drop_index`; `drop_index` captures the index definition out of `SHOW CREATE TABLE` so undo recreates it exactly; `set_global_variable` captures the prior value from `SHOW GLOBAL VARIABLES` so undo sets it back. Irreversible ops (`kill_session`, `kill_query`, `optimize_table`, `analyze_table`, `reset_query_stats`) record prior state for audit but declare no undo.
+- **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview. All identifiers that cannot be parameterised (schema/table/index/column/variable names) are validated against a strict charset and backtick-quoted; all values are bound query parameters.
+
+## Capability matrix (33 MCP tools)
+
+| Domain | Tools | Count | R/W |
+|--------|-------|:-----:|:---:|
+| **Overview** | `overview` | 1 | read |
+| **Server** | `server_version`, `show_variables`, `show_status`, `list_databases`, `list_engines`, `connection_stats` | 6 | read |
+| **Activity** | `list_sessions`, `long_running_queries`, `list_transactions`, `lock_waits` | 4 | read |
+| **Queries** | `top_queries`, `explain_query` | 2 | read |
+| **Indexes** | `unused_indexes`, `redundant_indexes`, `index_stats` | 3 | read |
+| **Tables** | `table_sizes`, `table_fragmentation`, `table_status` | 3 | read |
+| **Replication** | `replica_status`, `binlog_status` | 2 | read |
+| **Analysis (flagship)** | `slow_query_rca`, `lock_wait_rca`, `replication_lag_rca`, `fragmentation_analysis` | 4 | read |
+| **Writes** | `kill_session`, `kill_query`, `drop_index` | 3 | write (high) |
+| | `optimize_table`, `analyze_table`, `create_index`, `set_global_variable`, `reset_query_stats` | 5 | write (medium) |
+
+The flagship analyses accept injected records for pure/offline analysis, or pull
+live from a configured target. `top_queries`/`slow_query_rca` require
+`performance_schema=ON`; the read account should have `PROCESS`,
+`REPLICATION CLIENT` and `SELECT` on `performance_schema`.
+
+## Support scope
+
+| Platform | Status |
+|----------|--------|
+| MySQL 8.0 / 8.4 | supported (preview; `SHOW REPLICA STATUS`, `performance_schema.data_lock_waits`) |
+| MariaDB 10.6+ / 11.x | supported (preview; `SHOW SLAVE STATUS`, `information_schema.innodb_lock_waits`) |
+| MySQL 5.7 and older | not targeted (EOL; pre-8.0 digest/lock views untested) |
+| Cloud-managed MySQL (RDS/Aurora/Cloud SQL flavors) | wire-compatible reads should work; managed restrictions (KILL, SET GLOBAL) apply — untested |
+
+## Quick start
+
+```bash
+uv tool install mysql-aiops             # or: pipx install mysql-aiops
+mysql-aiops init                        # wizard: add a target + store the password (encrypted)
+mysql-aiops doctor                      # verify config, secrets, connectivity, flavor, perf-schema
+mysql-aiops overview                    # one-shot server health snapshot
+mysql-aiops analyze slow-query          # RCA the worst statement digest
+mysql-aiops analyze fragmentation       # OPTIMIZE TABLE candidates
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MYSQL_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
+mysql-aiops-mcp
+```
+
+Claude Desktop / MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "mysql-aiops": {
+      "command": "uvx",
+      "args": ["--from", "mysql-aiops", "mysql-aiops-mcp"],
+      "env": { "MYSQL_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: the `env` block above is the only environment the MCP
+> server sees — GUI-launched clients do **not** inherit your shell profile. Put
+> `MYSQL_AIOPS_MASTER_PASSWORD` (and `MYSQL_AIOPS_HOME` / `MYSQL_AUDIT_APPROVED_BY`
+> if you use them) there, or the server cannot unlock the secret store.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.mysql-aiops/audit.db` (relocatable via
+  `MYSQL_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker
+  (`MYSQL_MAX_TOOL_CALLS`, `MYSQL_MAX_TOOL_SECONDS`, `MYSQL_RUNAWAY_MAX`).
+- **Risk tiers** — graduated autonomy, **secure by default**: with no
+  `rules.yaml`, high-risk writes require a named approver
+  (`MYSQL_AUDIT_APPROVED_BY` / `MYSQL_AUDIT_RATIONALE`); `mysql-aiops init`
+  seeds an explicit starter `rules.yaml` with that dual-control tier.
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state, replayable through the tool it names.
+
+## Scope
+
+This is the **MySQL / MariaDB DBA-ops** member of the AIops-tools family
+(governed AI-ops with audit + budget + undo + risk tiers). Do **NOT** use it
+for PostgreSQL — use **postgres-aiops**. Do **NOT** use it for OT / industrial
+edge — see the separate `industrial-aiops` line — nor for application-schema
+migrations or ORM management.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of MySQL's catalogs and maintenance
+surface. Missing a view, a metric, or a maintenance command? **Open an issue or
+PR** — contributions welcome. 缺功能提 issue/PR 欢迎留言。
+
+## Status
+
+**Preview — mock-validated only, not run against a live server.** The catalog
+queries are modelled from the documented `information_schema` /
+`performance_schema` shapes for MySQL 8.x and MariaDB 10.6+ and need live
+verification. `mysql-aiops doctor` is the fastest live check (connectivity,
+flavor, performance_schema, replica role).

mysql_aiops-0.1.0/README.md

@@ -0,0 +1,148 @@
+<!-- mcp-name: io.github.AIops-tools/mysql-aiops -->
+
+# MySQL AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Oracle Corporation or the MariaDB Foundation.** "MySQL" is a trademark of Oracle Corporation; "MariaDB" is a trademark of MariaDB plc; all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **MySQL 8.x and MariaDB 10.6+ DBA operations** — connecting
+to a server with **PyMySQL** and reading `information_schema` /
+`performance_schema` — with a **built-in governance harness**: unified audit
+log, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. The server **flavor** (mysql vs mariadb) is
+detected from `version()` and flavor-dependent statements branch automatically
+(`SHOW REPLICA STATUS` vs `SHOW SLAVE STATUS`).
+**Preview — mock-validated only, not run against a live server.**
+
+## What it does
+
+Four flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Slow-query RCA** — take the worst `events_statements_summary_by_digest`
+  entry (plus an optional `EXPLAIN FORMAT=JSON` plan) and map its numbers —
+  no-index share (`SUM_NO_INDEX_USED`), lock-time share, rows-examined/sent
+  ratio, tmp-disk spill, call count, plan access types — to a cited cause and a
+  concrete action. Every finding carries its measured number, not a black-box
+  verdict.
+- **InnoDB lock-wait & deadlock chain RCA** — build the wait-for tree from
+  `performance_schema.data_lock_waits` (MariaDB:
+  `information_schema.innodb_lock_waits`), name the **root blocker** (blocks
+  others, waits on none), and parse the **last deadlock** out of
+  `SHOW ENGINE INNODB STATUS`.
+- **Replication lag RCA** — map the replica's IO/SQL thread state,
+  `Seconds_Behind_Source` and error fields to a cited cause + action
+  (stopped IO thread, failed applier statement, lagging applier, intentional
+  `SQL_Delay`).
+- **Table fragmentation analysis** — rank tables by reclaimable `data_free`
+  from `information_schema.tables` into cited `OPTIMIZE TABLE` candidates.
+
+## What works
+
+- **CLI** (`mysql-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`mysql-aiops mcp` or `mysql-aiops-mcp`): **33 tools** (25 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the account password lives in an encrypted store `~/.mysql-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `MYSQL_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
+- **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse — `create_index`↔`drop_index`; `drop_index` captures the index definition out of `SHOW CREATE TABLE` so undo recreates it exactly; `set_global_variable` captures the prior value from `SHOW GLOBAL VARIABLES` so undo sets it back. Irreversible ops (`kill_session`, `kill_query`, `optimize_table`, `analyze_table`, `reset_query_stats`) record prior state for audit but declare no undo.
+- **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview. All identifiers that cannot be parameterised (schema/table/index/column/variable names) are validated against a strict charset and backtick-quoted; all values are bound query parameters.
+
+## Capability matrix (33 MCP tools)
+
+| Domain | Tools | Count | R/W |
+|--------|-------|:-----:|:---:|
+| **Overview** | `overview` | 1 | read |
+| **Server** | `server_version`, `show_variables`, `show_status`, `list_databases`, `list_engines`, `connection_stats` | 6 | read |
+| **Activity** | `list_sessions`, `long_running_queries`, `list_transactions`, `lock_waits` | 4 | read |
+| **Queries** | `top_queries`, `explain_query` | 2 | read |
+| **Indexes** | `unused_indexes`, `redundant_indexes`, `index_stats` | 3 | read |
+| **Tables** | `table_sizes`, `table_fragmentation`, `table_status` | 3 | read |
+| **Replication** | `replica_status`, `binlog_status` | 2 | read |
+| **Analysis (flagship)** | `slow_query_rca`, `lock_wait_rca`, `replication_lag_rca`, `fragmentation_analysis` | 4 | read |
+| **Writes** | `kill_session`, `kill_query`, `drop_index` | 3 | write (high) |
+| | `optimize_table`, `analyze_table`, `create_index`, `set_global_variable`, `reset_query_stats` | 5 | write (medium) |
+
+The flagship analyses accept injected records for pure/offline analysis, or pull
+live from a configured target. `top_queries`/`slow_query_rca` require
+`performance_schema=ON`; the read account should have `PROCESS`,
+`REPLICATION CLIENT` and `SELECT` on `performance_schema`.
+
+## Support scope
+
+| Platform | Status |
+|----------|--------|
+| MySQL 8.0 / 8.4 | supported (preview; `SHOW REPLICA STATUS`, `performance_schema.data_lock_waits`) |
+| MariaDB 10.6+ / 11.x | supported (preview; `SHOW SLAVE STATUS`, `information_schema.innodb_lock_waits`) |
+| MySQL 5.7 and older | not targeted (EOL; pre-8.0 digest/lock views untested) |
+| Cloud-managed MySQL (RDS/Aurora/Cloud SQL flavors) | wire-compatible reads should work; managed restrictions (KILL, SET GLOBAL) apply — untested |
+
+## Quick start
+
+```bash
+uv tool install mysql-aiops             # or: pipx install mysql-aiops
+mysql-aiops init                        # wizard: add a target + store the password (encrypted)
+mysql-aiops doctor                      # verify config, secrets, connectivity, flavor, perf-schema
+mysql-aiops overview                    # one-shot server health snapshot
+mysql-aiops analyze slow-query          # RCA the worst statement digest
+mysql-aiops analyze fragmentation       # OPTIMIZE TABLE candidates
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MYSQL_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
+mysql-aiops-mcp
+```
+
+Claude Desktop / MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "mysql-aiops": {
+      "command": "uvx",
+      "args": ["--from", "mysql-aiops", "mysql-aiops-mcp"],
+      "env": { "MYSQL_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: the `env` block above is the only environment the MCP
+> server sees — GUI-launched clients do **not** inherit your shell profile. Put
+> `MYSQL_AIOPS_MASTER_PASSWORD` (and `MYSQL_AIOPS_HOME` / `MYSQL_AUDIT_APPROVED_BY`
+> if you use them) there, or the server cannot unlock the secret store.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.mysql-aiops/audit.db` (relocatable via
+  `MYSQL_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker
+  (`MYSQL_MAX_TOOL_CALLS`, `MYSQL_MAX_TOOL_SECONDS`, `MYSQL_RUNAWAY_MAX`).
+- **Risk tiers** — graduated autonomy, **secure by default**: with no
+  `rules.yaml`, high-risk writes require a named approver
+  (`MYSQL_AUDIT_APPROVED_BY` / `MYSQL_AUDIT_RATIONALE`); `mysql-aiops init`
+  seeds an explicit starter `rules.yaml` with that dual-control tier.
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state, replayable through the tool it names.
+
+## Scope
+
+This is the **MySQL / MariaDB DBA-ops** member of the AIops-tools family
+(governed AI-ops with audit + budget + undo + risk tiers). Do **NOT** use it
+for PostgreSQL — use **postgres-aiops**. Do **NOT** use it for OT / industrial
+edge — see the separate `industrial-aiops` line — nor for application-schema
+migrations or ORM management.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of MySQL's catalogs and maintenance
+surface. Missing a view, a metric, or a maintenance command? **Open an issue or
+PR** — contributions welcome. 缺功能提 issue/PR 欢迎留言。
+
+## Status
+
+**Preview — mock-validated only, not run against a live server.** The catalog
+queries are modelled from the documented `information_schema` /
+`performance_schema` shapes for MySQL 8.x and MariaDB 10.6+ and need live
+verification. `mysql-aiops doctor` is the fastest live check (connectivity,
+flavor, performance_schema, replica role).

mysql_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,60 @@
+# MySQL AIops v0.1.0 — preview
+
+Governed AI-ops for **MySQL 8.x / MariaDB 10.6+ DBA operations** for AI agents
+— connecting via **PyMySQL** and reading `information_schema` /
+`performance_schema` — with a built-in governance harness (audit, policy,
+token/runaway budget, undo-token recording, graduated risk tiers) and an
+encrypted credential store. Standalone — no external skill-family dependency.
+
+> **Preview / mock-only.** All behaviour is validated against a mocked PyMySQL
+> cursor/connection; it has **not** been run against a live MySQL or MariaDB
+> server. The fastest live check is `mysql-aiops doctor`.
+>
+> Community-maintained; **not affiliated with or endorsed by Oracle Corporation
+> or the MariaDB Foundation.** "MySQL" and "MariaDB" trademarks belong to their
+> owners.
+
+## Highlights
+
+- **33 MCP tools** (25 read, 8 write), every one wrapped with `@governed_tool`.
+  - Read: server `overview`; server reads (6); activity (4); query stats (2);
+    index health (3); table health (3); replication (2); and four flagship
+    analyses.
+  - Write: `kill_session`/`kill_query`/`drop_index` (high);
+    `optimize_table`/`analyze_table`/`create_index`/`set_global_variable`/
+    `reset_query_stats` (medium).
+- **Four signature analyses** — `slow_query_rca` (worst statement digest +
+  EXPLAIN → cited cause/action), `lock_wait_rca` (InnoDB wait-for tree with the
+  root blocker named + last deadlock parsed from `SHOW ENGINE INNODB STATUS`),
+  `replication_lag_rca` (thread state / lag / error fields → cause + action),
+  and `fragmentation_analysis` (`data_free` → OPTIMIZE TABLE candidates).
+- **Flavor-aware** — mysql vs mariadb detected from `version()`;
+  `SHOW REPLICA STATUS` vs `SHOW SLAVE STATUS` and the lock-wait source branch
+  automatically; doctor and overview report the flavor.
+- **Encrypted password store** (`~/.mysql-aiops/secrets.enc`, Fernet + scrypt)
+  — never plaintext on disk; legacy `MYSQL_<TARGET>_PASSWORD` env fallback.
+- **CLI** with an `init` onboarding wizard (TLS modes incl. verify_ca /
+  verify_identity), `secret` management, and `doctor`.
+- **PyMySQL connection layer** — parameterised catalog reads, `DictCursor`
+  results, autocommit for maintenance commands, 30s timeouts, and teaching
+  error translation (`MySQLError`). Reversible writes fetch the real
+  before-state first.
+
+## Install
+
+```bash
+uv tool install mysql-aiops
+mysql-aiops init
+mysql-aiops doctor
+```
+
+## Caveats
+
+- The `information_schema` / `performance_schema` queries are modelled from the
+  documented MySQL 8.x / MariaDB 10.6+ shapes and need live verification.
+- `top_queries` / `slow_query_rca` require `performance_schema=ON`; the read
+  account should have `PROCESS`, `REPLICATION CLIENT` and `SELECT` on
+  `performance_schema`.
+- Out of scope by design: application-schema migrations, ORM management,
+  logical backup/restore orchestration, and any bulk destructive DDL.
+- Missing a view, metric, or maintenance command? Open an issue or PR.

mysql_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,95 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by Oracle Corporation or the MariaDB Foundation.** "MySQL" and
+"MariaDB" trademarks belong to their respective owners. Source is publicly
+auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/MySQL-AIops](https://github.com/AIops-tools/MySQL-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target MySQL account passwords live **encrypted** in
+  `~/.mysql-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is never
+  stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `MYSQL_<TARGET_NAME_UPPER>_PASSWORD` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `mysql-aiops secret migrate`).
+- The password is passed to `pymysql.connect` at connect time and held only in
+  memory. It is never logged or echoed; `config.yaml` holds only host, port,
+  database, user, `ssl_mode` (and optionally `ssl_ca`). The redacted DSN
+  (`dsn_redacted`) masks it.
+
+### SQL-Injection Defenses
+- **All values are bound query parameters** (session ids, thresholds, limits,
+  variable values) — never string-formatted into SQL.
+- The few identifiers that cannot be parameterised (schema/table/index/column
+  names, global variable names, `ORDER BY` columns) are validated against a
+  strict identifier charset / allow-lists (`mysql_aiops.ops._util`) and
+  backtick-quoted before the single interpolation site; anything that is not a
+  plain identifier is rejected, not interpolated.
+- `EXPLAIN` rejects multi-statement input (an embedded `;` is refused).
+- The `drop_index` undo replay path (`create_index(definition=...)`) is
+  shape-gated: single statement, must be `CREATE [UNIQUE] INDEX ... ON ...`.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`mysql_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.mysql-aiops/`
+  (relocatable via `MYSQL_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`MYSQL_MAX_TOOL_CALLS` /
+  `MYSQL_MAX_TOOL_SECONDS` — the env-var names the bundled harness reads) plus
+  an on-by-default guard that trips a tight poll/retry loop.
+- **Graduated risk tiers** — **secure by default**: with no
+  `~/.mysql-aiops/rules.yaml`, high/critical writes are denied unless
+  `MYSQL_AUDIT_APPROVED_BY` names an approver (`MYSQL_AUDIT_RATIONALE` for
+  why); `mysql-aiops init` seeds an explicit starter rules.yaml.
+- **Undo-token recording** — reversible writes fetch the **real before-state
+  first** and record a faithful inverse (`create_index`↔`drop_index`, where
+  drop rebuilds the definition from `SHOW CREATE TABLE`;
+  `set_global_variable` restores the prior value).
+
+### State-Changing Operations
+Every write supports `--dry-run` (CLI) / `dry_run=True` (MCP) and requires double
+confirmation at the CLI layer. Destructive/irreversible ops (`kill_session`,
+`kill_query`, `drop_index`) are `risk_level=high`; mutating maintenance ops
+(`optimize_table`, `analyze_table`, `create_index`, `set_global_variable`,
+`reset_query_stats`) are `medium`. Irreversible ops capture prior state for the
+audit record but record no undo token. `SET GLOBAL` is runtime-only and reports
+(but does not auto-perform) the my.cnf / SET PERSIST persistence step.
+
+### SSL/TLS
+`ssl_mode` follows MySQL client semantics (default `preferred`); set
+`verify_ca` / `verify_identity` (with `ssl_ca`) on untrusted networks;
+`disabled` is for isolated labs only.
+
+### Output Sanitisation
+All catalog- and query-returned text (query text, object names, error strings)
+is passed through a `sanitize()` truncate + control-character strip before
+reaching the agent. This bounds length and strips control/format characters;
+semantic resistance to adversarial text must come from the consuming agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured MySQL
+connection. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r mysql_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

mysql_aiops-0.1.0/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package for mysql-aiops."""