postgres-aiops 0.1.0__tar.gz

postgres_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

postgres_aiops-0.1.0/.gitignore

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

postgres_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to postgres-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).
+
+## [0.1.0] — 2026-07-13
+
+Initial preview release: governed AI-ops for **PostgreSQL DBA operations** —
+connecting via **psycopg 3** and reading the system catalogs and `pg_stat_*`
+views — with a bundled governance harness. **Mock-validated only — not run
+against a live cluster.** Community-maintained; not affiliated with the
+PostgreSQL project.
+
+### Added
+
+- **psycopg 3 connection layer** (`postgres_aiops.connection`) — parameterised
+  reads with a `dict_row` factory, autocommit for maintenance statements
+  (VACUUM / CONCURRENTLY / REINDEX), an injectable connection for tests, and
+  teaching error translation (`PgError`, with connect/permission/missing-view
+  hints).
+- **33 governed MCP tools**, every one wrapped with `@governed_tool`:
+  - **Overview** — `overview` (one-shot cluster health snapshot).
+  - **Server** — `server_version`, `show_settings`, `list_extensions`,
+    `list_databases`, `list_roles`.
+  - **Activity** — `list_activity`, `long_running_queries`, `list_locks`.
+  - **Queries** — `top_queries` (pg_stat_statements), `explain_query`.
+  - **Indexes** — `unused_indexes`, `missing_index_hints`, `index_bloat`,
+    `invalid_indexes`.
+  - **Tables** — `table_sizes`, `table_bloat`, `autovacuum_status`.
+  - **Replication** — `replication_status`, `replication_slots`, `wal_status`.
+  - **Analysis (flagship)** — `slow_query_rca`, `bloat_and_vacuum_analysis`,
+    `blocking_lock_chain_rca`.
+  - **Writes** — `terminate_backend` (high), `cancel_query` (high),
+    `drop_index` (high), `run_vacuum` (medium), `run_analyze` (medium),
+    `create_index` (medium), `reindex` (medium), `update_setting` (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 captures
+  `pg_get_indexdef` so undo recreates it exactly); `update_setting` captures the
+  prior value. Irreversible ops record prior stats for audit but no undo.
+- **SQL-injection defenses** — all values are bound query parameters; the few
+  identifiers that cannot be parameterised (table/index/GUC names, ORDER BY
+  columns, index methods) are validated against strict allow-lists and quoted
+  before interpolation.
+- **Bundled governance harness** (`postgres_aiops.governance`) — audit log, policy
+  engine, token/runaway budget guard, undo-token recording, graduated risk tiers,
+  prompt-injection `sanitize`. State under `~/.postgres-aiops/` (relocatable via
+  `POSTGRES_AIOPS_HOME`).
+- **Encrypted secret store** — role passwords in `~/.postgres-aiops/secrets.enc`
+  (Fernet + scrypt); legacy `PG_<TARGET>_PASSWORD` env fallback + `secret migrate`.
+- **CLI** — `init` wizard, `overview`, `server`, `activity`, `query`, `index`,
+  `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
+
+### Known limitations
+
+- Preview / mock-only: catalog and `pg_stat_*` queries need live verification.
+- `top_queries` / `slow_query_rca` require the `pg_stat_statements` extension.
+- Coverage is a curated subset of PostgreSQL's surface; open an issue/PR for gaps.
+
+[0.1.0]: https://github.com/AIops-tools/Postgres-AIops/releases/tag/v0.1.0

postgres_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.

postgres_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: postgres-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock 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: psycopg[binary]<4.0,>=3.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/postgres-aiops -->
+
+# Postgres AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
+**psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
+**built-in governance harness**: unified audit log, policy engine, token/runaway
+budget guard, undo-token recording, and graduated-autonomy risk tiers.
+**Preview — mock-validated only, not run against a live cluster.**
+
+## What it does
+
+Three flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Slow-query RCA** — take the worst `pg_stat_statements` entry (plus an optional
+  `EXPLAIN` plan) and map its numbers — mean time, cache-hit ratio, temp spill,
+  call count, plan node types — to a cited cause and a concrete action. Every
+  finding carries its measured number, not a black-box verdict.
+- **Bloat & vacuum analysis** — combine per-table dead-tuple ratio and autovacuum
+  recency into a ranked, cited recommendation (VACUUM / tune autovacuum).
+- **Blocking lock-chain RCA** — build the wait-for tree from `pg_blocking_pids`,
+  name the **root blocker** (blocks others, waits on none), and give the action;
+  a cycle is flagged as a likely deadlock.
+
+## What works
+
+- **CLI** (`postgres-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **33 tools** (24 read, 9 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the role password lives in an encrypted store `~/.postgres-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `POSTGRES_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 `pg_get_indexdef` so undo recreates it exactly; `update_setting` captures the prior value so undo sets it back. Irreversible ops (`terminate_backend`, `cancel_query`, `run_vacuum`, `run_analyze`, `reindex`, `reset_query_stats`) record prior stats 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 (table/index/GUC names) are validated and 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_settings`, `list_extensions`, `list_databases`, `list_roles` | 5 | read |
+| **Activity** | `list_activity`, `long_running_queries`, `list_locks` | 3 | read |
+| **Queries** | `top_queries`, `explain_query` | 2 | read |
+| **Indexes** | `unused_indexes`, `missing_index_hints`, `index_bloat`, `invalid_indexes` | 4 | read |
+| **Tables** | `table_sizes`, `table_bloat`, `autovacuum_status` | 3 | read |
+| **Replication** | `replication_status`, `replication_slots`, `wal_status` | 3 | read |
+| **Analysis (flagship)** | `slow_query_rca`, `bloat_and_vacuum_analysis`, `blocking_lock_chain_rca` | 3 | read |
+| **Writes** | `terminate_backend`, `cancel_query`, `drop_index` | 3 | write (high) |
+| | `run_vacuum`, `run_analyze`, `create_index`, `reindex`, `update_setting`, `reset_query_stats` | 6 | 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 the
+`pg_stat_statements` extension; the read role should have `pg_monitor`.
+
+## Quick start
+
+```bash
+uv tool install postgres-aiops             # or: pipx install postgres-aiops
+postgres-aiops init                        # wizard: add a target + store the password (encrypted)
+postgres-aiops doctor                      # verify config, secrets, connectivity
+postgres-aiops overview                    # one-shot cluster health snapshot
+postgres-aiops analyze slow-query          # RCA the worst pg_stat_statements entry
+postgres-aiops table bloat                 # dead-tuple bloat proxy per table
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export POSTGRES_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
+postgres-aiops-mcp
+```
+
+## 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 `~/.postgres-aiops/audit.db` (relocatable via
+  `POSTGRES_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE` — the env-var names
+  the bundled harness reads).
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state.
+
+## Scope
+
+This is the **PostgreSQL DBA-ops** member of the AIops-tools family (governed
+AI-ops with audit + budget + undo + risk tiers). Do **NOT** use it for OT /
+industrial edge (Modbus, OPC-UA, PROFINET) — see the separate `industrial-aiops`
+line — nor for application-schema migrations or ORM management.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of PostgreSQL's catalogs and
+maintenance surface. Missing a view, a metric, or a maintenance command? **Open
+an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not run against a live cluster.** The catalog
+queries are modelled from the documented `pg_catalog` / `pg_stat_*` shapes and
+need live verification. `postgres-aiops doctor` is the fastest live check.

postgres_aiops-0.1.0/README.md

@@ -0,0 +1,103 @@
+<!-- mcp-name: io.github.AIops-tools/postgres-aiops -->
+
+# Postgres AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
+**psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
+**built-in governance harness**: unified audit log, policy engine, token/runaway
+budget guard, undo-token recording, and graduated-autonomy risk tiers.
+**Preview — mock-validated only, not run against a live cluster.**
+
+## What it does
+
+Three flagship signature analyses, plus the guarded reads and writes around them:
+
+- **Slow-query RCA** — take the worst `pg_stat_statements` entry (plus an optional
+  `EXPLAIN` plan) and map its numbers — mean time, cache-hit ratio, temp spill,
+  call count, plan node types — to a cited cause and a concrete action. Every
+  finding carries its measured number, not a black-box verdict.
+- **Bloat & vacuum analysis** — combine per-table dead-tuple ratio and autovacuum
+  recency into a ranked, cited recommendation (VACUUM / tune autovacuum).
+- **Blocking lock-chain RCA** — build the wait-for tree from `pg_blocking_pids`,
+  name the **root blocker** (blocks others, waits on none), and give the action;
+  a cycle is flagged as a likely deadlock.
+
+## What works
+
+- **CLI** (`postgres-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
+- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **33 tools** (24 read, 9 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the role password lives in an encrypted store `~/.postgres-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `POSTGRES_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 `pg_get_indexdef` so undo recreates it exactly; `update_setting` captures the prior value so undo sets it back. Irreversible ops (`terminate_backend`, `cancel_query`, `run_vacuum`, `run_analyze`, `reindex`, `reset_query_stats`) record prior stats 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 (table/index/GUC names) are validated and 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_settings`, `list_extensions`, `list_databases`, `list_roles` | 5 | read |
+| **Activity** | `list_activity`, `long_running_queries`, `list_locks` | 3 | read |
+| **Queries** | `top_queries`, `explain_query` | 2 | read |
+| **Indexes** | `unused_indexes`, `missing_index_hints`, `index_bloat`, `invalid_indexes` | 4 | read |
+| **Tables** | `table_sizes`, `table_bloat`, `autovacuum_status` | 3 | read |
+| **Replication** | `replication_status`, `replication_slots`, `wal_status` | 3 | read |
+| **Analysis (flagship)** | `slow_query_rca`, `bloat_and_vacuum_analysis`, `blocking_lock_chain_rca` | 3 | read |
+| **Writes** | `terminate_backend`, `cancel_query`, `drop_index` | 3 | write (high) |
+| | `run_vacuum`, `run_analyze`, `create_index`, `reindex`, `update_setting`, `reset_query_stats` | 6 | 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 the
+`pg_stat_statements` extension; the read role should have `pg_monitor`.
+
+## Quick start
+
+```bash
+uv tool install postgres-aiops             # or: pipx install postgres-aiops
+postgres-aiops init                        # wizard: add a target + store the password (encrypted)
+postgres-aiops doctor                      # verify config, secrets, connectivity
+postgres-aiops overview                    # one-shot cluster health snapshot
+postgres-aiops analyze slow-query          # RCA the worst pg_stat_statements entry
+postgres-aiops table bloat                 # dead-tuple bloat proxy per table
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export POSTGRES_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
+postgres-aiops-mcp
+```
+
+## 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 `~/.postgres-aiops/audit.db` (relocatable via
+  `POSTGRES_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE` — the env-var names
+  the bundled harness reads).
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state.
+
+## Scope
+
+This is the **PostgreSQL DBA-ops** member of the AIops-tools family (governed
+AI-ops with audit + budget + undo + risk tiers). Do **NOT** use it for OT /
+industrial edge (Modbus, OPC-UA, PROFINET) — see the separate `industrial-aiops`
+line — nor for application-schema migrations or ORM management.
+
+## Missing a capability?
+
+Coverage is intentionally a curated subset of PostgreSQL's catalogs and
+maintenance surface. Missing a view, a metric, or a maintenance command? **Open
+an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not run against a live cluster.** The catalog
+queries are modelled from the documented `pg_catalog` / `pg_stat_*` shapes and
+need live verification. `postgres-aiops doctor` is the fastest live check.

postgres_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,52 @@
+# Postgres AIops v0.1.0 — preview
+
+Governed AI-ops for **PostgreSQL DBA operations** for AI agents — connecting via
+**psycopg 3** and reading the system catalogs and `pg_stat_*` views — 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 psycopg
+> cursor/connection; it has **not** been run against a live PostgreSQL cluster.
+> The fastest live check is `postgres-aiops doctor`.
+>
+> Community-maintained; **not affiliated with or endorsed by the PostgreSQL
+> Global Development Group.** "PostgreSQL" and related trademarks belong to their
+> owners.
+
+## Highlights
+
+- **33 MCP tools** (24 read, 9 write), every one wrapped with `@governed_tool`.
+  - Read: cluster `overview`; server (5); activity (3); query stats (2); index
+    health (4); table health (3); replication (3); and three flagship analyses.
+  - Write: `terminate_backend`/`cancel_query`/`drop_index` (high);
+    `run_vacuum`/`run_analyze`/`create_index`/`reindex`/`update_setting`/
+    `reset_query_stats` (medium).
+- **Three signature analyses** — `slow_query_rca` (worst `pg_stat_statements`
+  entry + EXPLAIN → cited cause/action), `bloat_and_vacuum_analysis` (dead-tuple
+  ratio + autovacuum recency → recommendation), and `blocking_lock_chain_rca`
+  (build the wait-for tree, name the root blocker).
+- **Encrypted password store** (`~/.postgres-aiops/secrets.enc`, Fernet + scrypt)
+  — never plaintext on disk; legacy `PG_<TARGET>_PASSWORD` env fallback.
+- **CLI** with an `init` onboarding wizard, `secret` management, and `doctor`.
+- **psycopg 3 connection layer** — parameterised catalog reads, `dict_row`
+  results, autocommit for maintenance commands, and teaching error translation
+  (`PgError`). Reversible writes fetch the real before-state first.
+
+## Install
+
+```bash
+uv tool install postgres-aiops
+postgres-aiops init
+postgres-aiops doctor
+```
+
+## Caveats
+
+- The catalog / `pg_stat_*` queries are modelled from the documented shapes and
+  need live verification against a real cluster.
+- `top_queries` / `slow_query_rca` require the `pg_stat_statements` extension;
+  the read role should have `pg_monitor`.
+- 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.

postgres_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,89 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the PostgreSQL Global Development Group or any vendor.**
+"PostgreSQL" and related 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/Postgres-AIops](https://github.com/AIops-tools/Postgres-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target PostgreSQL role passwords live **encrypted** in
+  `~/.postgres-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 `PG_<TARGET_NAME_UPPER>_PASSWORD` is still honoured
+  as a fallback with a deprecation warning (migrate with `postgres-aiops secret
+  migrate`).
+- The password is passed to `psycopg.connect` at connect time and held only in
+  memory. It is never logged or echoed; `config.yaml` holds only host, port,
+  dbname, user, and `sslmode`. The redacted DSN (`dsn_redacted`) masks it.
+
+### SQL-Injection Defenses
+- **All values are bound query parameters** (pids, thresholds, limits, setting
+  values) — never string-formatted into SQL.
+- The few identifiers that cannot be parameterised (table/index/schema names, GUC
+  names, `ORDER BY` columns, index methods, `REINDEX` kinds) are validated
+  against strict allow-lists (`postgres_aiops.ops._util`) and double-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).
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`postgres_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.postgres-aiops/`
+  (relocatable via `POSTGRES_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`POSTGRES_MAX_TOOL_CALLS` /
+  `POSTGRES_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** — `~/.postgres-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver
+  (`POSTGRES_AUDIT_APPROVED_BY` / `POSTGRES_AUDIT_RATIONALE`).
+- **Undo-token recording** — reversible writes fetch the **real before-state
+  first** and record a faithful inverse (`create_index`↔`drop_index`, where drop
+  captures `pg_get_indexdef`; `update_setting` 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 (`terminate_backend`,
+`cancel_query`, `drop_index`) are `risk_level=high`; mutating maintenance ops
+(`run_vacuum`, `run_analyze`, `create_index`, `reindex`, `update_setting`,
+`reset_query_stats`) are `medium`. Irreversible ops capture prior stats for the
+audit record but record no undo token. `ALTER SYSTEM SET` writes
+`postgresql.auto.conf` and reports (but does not auto-run) the required
+`pg_reload_conf()` / restart.
+
+### SSL/TLS
+`sslmode` follows libpq semantics (default `prefer`); set `require`/`verify-full`
+for untrusted networks.
+
+### Prompt-Injection Protection
+All catalog- and query-returned text (query text, object names, descriptions) is
+passed through a `sanitize()` truncate + control-character strip before reaching
+the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured PostgreSQL
+connection. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r postgres_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.

postgres_aiops-0.1.0/mcp_server/__init__.py

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

postgres_aiops-0.1.0/mcp_server/_shared.py

@@ -0,0 +1,101 @@
+"""Shared MCP server primitives: the FastMCP instance, connection helper,
+error sanitisation, and the ``@tool_errors`` decorator.
+
+Tool modules under ``mcp_server/tools/`` import ``mcp`` from here and register
+their ``@mcp.tool()`` functions onto it. ``mcp_server/server.py`` then imports
+those modules and runs the server.
+
+Keep ``Optional[X]`` (never PEP 604 ``X | None``) in any FastMCP-reflected
+tool signature — on older mcp/pydantic the union eval'd to ``types.UnionType``
+crashes FastMCP's ``issubclass`` check.
+"""
+
+import functools
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from postgres_aiops.config import load_config
+from postgres_aiops.connection import ConnectionManager, PgError
+from postgres_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'postgres-aiops doctor' to verify connectivity and credentials."
+
+
+def _safe_error(exc: Exception, tool: str) -> str:
+    """Return an agent-safe error string; log full detail server-side only."""
+    logger.error("Tool %s failed", tool, exc_info=True)
+    _passthrough = (
+        ValueError,
+        FileNotFoundError,
+        KeyError,
+        PermissionError,
+        TimeoutError,
+        ConnectionError,
+        PgError,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 300)
+    return f"{type(exc).__name__}: operation failed."
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    """Wrap a tool body in the canonical try/except → ``_safe_error`` pattern.
+
+    Place this *between* ``@governed_tool`` and the function so the audit
+    decorator and FastMCP still see the original signature.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — sanitised below
+                msg = _safe_error(e, name)
+                if shape == "list":
+                    return [{"error": msg, "hint": _DOCTOR_HINT}]
+                if shape == "str":
+                    return f"Error: {msg} {_DOCTOR_HINT}"
+                return {"error": msg, "hint": _DOCTOR_HINT}
+
+        return wrapper
+
+    return decorator
+
+
+mcp = FastMCP(
+    "postgres-aiops",
+    instructions=(
+        "Governed PostgreSQL DBA operations (preview): a one-shot cluster "
+        "'overview'; server reads (version/settings/extensions/databases/roles); "
+        "activity (sessions, long-running queries, locks); query stats "
+        "(pg_stat_statements top-N, EXPLAIN); index and table health (unused / "
+        "missing / bloat / autovacuum); replication (lag, slots, WAL); three "
+        "flagship analyses — 'slow_query_rca', 'bloat_and_vacuum_analysis', and "
+        "'blocking_lock_chain_rca'; and guarded writes (terminate/cancel, "
+        "vacuum/analyze, create/drop index, reindex, ALTER SYSTEM). Every tool "
+        "runs through the postgres-aiops governance harness (audit / budget / "
+        "risk-tier / undo). Do NOT use for OT/industrial edge — see industrial-aiops."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a PostgreSQL connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("POSTGRES_AIOPS_CONFIG")
+        config_path = Path(config_path_str) if config_path_str else None
+        _conn_mgr = ConnectionManager(load_config(config_path))
+    return _conn_mgr.connect(target)

postgres_aiops-0.1.0/mcp_server/server.py

@@ -0,0 +1,37 @@
+"""MCP server wrapping postgres-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``postgres_aiops`` ops package and is wrapped with the
+postgres-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed PostgreSQL DBA operations (preview).
+For PostgreSQL servers/clusters via psycopg 3.
+
+Source: https://github.com/AIops-tools/Postgres-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    activity,
+    analysis,
+    indexes,
+    queries,
+    remediation,
+    replication,
+    server,
+    tables,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")

postgres_aiops-0.1.0/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules. Importing each registers its @mcp.tool() functions."""