queue-aiops 0.1.0__tar.gz → 0.2.0__tar.gz

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.1.1 — 2026-07-17
+
+### Fixed
+- Added the MCP Registry ownership marker (mcp-name) to the README so the server publishes to the MCP Registry.
+
 ## v0.1.0 — 2026-07-17
 
 Initial preview release.

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queue-aiops
-Version: 0.1.0
+Version: 0.2.0
 Summary: Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: wei <zhouwei008@gmail.com>
 License-Expression: MIT
@@ -15,7 +15,9 @@ Requires-Dist: rich<16.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
 Description-Content-Type: text/markdown
 
-# Queue AIops (preview)
+<!-- mcp-name: io.github.AIops-tools/queue-aiops -->
+
+# Queue AIops
 
 **Governed AI-ops for redis + rabbitmq.** queue-aiops is for the team running
 their own cache and message broker — a redis that "suddenly eats memory", a
@@ -31,9 +33,10 @@ by the built-in governance harness.
 > with, endorsed by, or sponsored by the Redis or RabbitMQ projects or their
 > respective owners.** Redis and RabbitMQ are trademarks of their respective owners.
 >
-> **Preview / mock-only**: not yet validated against production brokers. Both
-> redis and rabbitmq are free/self-hostable (one lab container or package install each), so a lab
-> check is easy — `queue-aiops doctor` is the fastest live probe.
+> **Verification**: behaviour is covered by a mock-based test suite; not yet validated
+> against live brokers. Both redis and rabbitmq are free/self-hostable (one lab container
+> or package install each), so a lab check is easy — `queue-aiops doctor` is the fastest
+> live probe, and [docs/VERIFICATION.md](docs/VERIFICATION.md) is the checklist.
 
 ## Quick start
 
@@ -56,6 +59,46 @@ queue-aiops redis bigkeys      # SCAN-budgeted big-key sample (never KEYS *)
 queue-aiops rabbitmq queues    # deepest backlog first
 ```
 
+## Security: read-only mode
+
+This tool is meant to be handed to an AI agent, so its safety story is enforced
+by the server rather than requested in a prompt:
+
+```bash
+export QUEUE_READ_ONLY=1
+```
+
+With that set, the **8 write tools are never registered**. An MCP client
+lists **20 tools instead of 28** — the writes are not hidden, not
+gated behind a flag, and not merely refused when called. They are absent from
+the session. A model cannot invoke a tool it was never offered, and cannot be
+argued into one.
+
+That distinction is the whole point. A tool that exists but refuses still invites
+retry loops and "I'll describe the call instead" behaviour from smaller models,
+and it leaves a reviewer trusting a promise. An absent tool is a fact you can
+check: connect, list the tools, and see that the writes are not there.
+
+Enforcement is two layers deep, so the switch cannot be sidestepped by changing
+entry point:
+
+| Layer | What it does | Covers |
+|---|---|---|
+| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
+| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
+
+Read operations are unaffected, and every call is still audited to
+`~/.queue-aiops/audit.db`.
+
+> The read/write split is derived from each tool's declared `risk_level`, and a
+> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
+> tool's own documentation — so a write can't quietly present itself as a read.
+
+Running a smaller / local model? See
+[agent-guardrails.md](skills/queue-aiops/references/agent-guardrails.md) — it lists
+the guardrails this tool now enforces for you (so you don't spend prompt budget
+restating them) and gives a ready-made system prompt for what's left.
+
 ## Support scope
 
 | Platform | Protocol | Coverage |
@@ -63,7 +106,7 @@ queue-aiops rabbitmq queues    # deepest backlog first
 | **redis** (5.x–7.x wire protocol via `redis` Python client) | RESP, password optional, TLS optional | INFO (server/memory/clients/stats/persistence/keyspace), SLOWLOG, CLIENT LIST/KILL, CONFIG GET/SET, MEMORY STATS/USAGE, SCAN-budgeted big-key sampling, DBSIZE, PING |
 | **rabbitmq** (management plugin HTTP API) | HTTP(S), Basic auth | /api/overview, /api/queues (+ per-vhost, detail, purge, declare, delete), /api/connections, /api/channels, /api/consumers, /api/policies (get/set/delete), /api/nodes |
 
-**26 MCP tools** — 19 reads (incl. 4 flagship RCAs) + 7 governed writes.
+**28 MCP tools** — 20 reads (incl. 4 flagship RCAs) + 8 governed writes.
 
 | Group | Tools | R/W |
 |-------|-------|:---:|
@@ -73,6 +116,7 @@ queue-aiops rabbitmq queues    # deepest backlog first
 | Flagship RCAs | redis_memory_pressure_rca, redis_latency_rca, rabbitmq_queue_backlog_rca, connection_churn_analysis | read |
 | Writes (medium) | redis_config_set, redis_kill_client, declare_queue, set_policy, delete_policy | write |
 | Writes (**high**) | purge_queue, delete_queue | write |
+| Undo | undo_list, undo_apply | read / write |
 
 The four RCAs are transparent heuristics that report their numbers — thresholds
 are named constants, every finding carries its evidence, never a black-box
@@ -148,12 +192,17 @@ queue-aiops analyze memory|latency|backlog|churn
 
 ## Verification status
 
-Preview / mock-only: the full test suite runs against mocked clients (no live
-broker needed), and the REST paths / INFO fields are modelled from the public
-docs of both platforms. Not yet validated against live production brokers —
-both are trivially self-hostable, so `queue-aiops doctor` against a
-local lab redis instance / rabbitmq broker (management plugin enabled) is
-the quickest live check.
+**Mock-validated; not yet run against live brokers.** The full test suite runs against
+mocked clients (no live broker needed): every module imports, every MCP tool carries the
+governance marker, the four flagship RCAs are unit-tested against synthetic telemetry,
+and reversible writes are asserted to record the correct inverse undo descriptor. The
+REST paths and `INFO` field names are modelled from the public docs of both platforms
+and have not been exercised against a real broker.
+
+Both platforms are trivially self-hostable, so `queue-aiops doctor` against a local lab
+redis instance / rabbitmq broker (management plugin enabled) is the quickest live check.
+[docs/VERIFICATION.md](docs/VERIFICATION.md) is the full checklist a live run must
+satisfy.
 
 ## Contributing
 

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/README.md

@@ -1,4 +1,6 @@
-# Queue AIops (preview)
+<!-- mcp-name: io.github.AIops-tools/queue-aiops -->
+
+# Queue AIops
 
 **Governed AI-ops for redis + rabbitmq.** queue-aiops is for the team running
 their own cache and message broker — a redis that "suddenly eats memory", a
@@ -14,9 +16,10 @@ by the built-in governance harness.
 > with, endorsed by, or sponsored by the Redis or RabbitMQ projects or their
 > respective owners.** Redis and RabbitMQ are trademarks of their respective owners.
 >
-> **Preview / mock-only**: not yet validated against production brokers. Both
-> redis and rabbitmq are free/self-hostable (one lab container or package install each), so a lab
-> check is easy — `queue-aiops doctor` is the fastest live probe.
+> **Verification**: behaviour is covered by a mock-based test suite; not yet validated
+> against live brokers. Both redis and rabbitmq are free/self-hostable (one lab container
+> or package install each), so a lab check is easy — `queue-aiops doctor` is the fastest
+> live probe, and [docs/VERIFICATION.md](docs/VERIFICATION.md) is the checklist.
 
 ## Quick start
 
@@ -39,6 +42,46 @@ queue-aiops redis bigkeys      # SCAN-budgeted big-key sample (never KEYS *)
 queue-aiops rabbitmq queues    # deepest backlog first
 ```
 
+## Security: read-only mode
+
+This tool is meant to be handed to an AI agent, so its safety story is enforced
+by the server rather than requested in a prompt:
+
+```bash
+export QUEUE_READ_ONLY=1
+```
+
+With that set, the **8 write tools are never registered**. An MCP client
+lists **20 tools instead of 28** — the writes are not hidden, not
+gated behind a flag, and not merely refused when called. They are absent from
+the session. A model cannot invoke a tool it was never offered, and cannot be
+argued into one.
+
+That distinction is the whole point. A tool that exists but refuses still invites
+retry loops and "I'll describe the call instead" behaviour from smaller models,
+and it leaves a reviewer trusting a promise. An absent tool is a fact you can
+check: connect, list the tools, and see that the writes are not there.
+
+Enforcement is two layers deep, so the switch cannot be sidestepped by changing
+entry point:
+
+| Layer | What it does | Covers |
+|---|---|---|
+| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
+| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
+
+Read operations are unaffected, and every call is still audited to
+`~/.queue-aiops/audit.db`.
+
+> The read/write split is derived from each tool's declared `risk_level`, and a
+> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
+> tool's own documentation — so a write can't quietly present itself as a read.
+
+Running a smaller / local model? See
+[agent-guardrails.md](skills/queue-aiops/references/agent-guardrails.md) — it lists
+the guardrails this tool now enforces for you (so you don't spend prompt budget
+restating them) and gives a ready-made system prompt for what's left.
+
 ## Support scope
 
 | Platform | Protocol | Coverage |
@@ -46,7 +89,7 @@ queue-aiops rabbitmq queues    # deepest backlog first
 | **redis** (5.x–7.x wire protocol via `redis` Python client) | RESP, password optional, TLS optional | INFO (server/memory/clients/stats/persistence/keyspace), SLOWLOG, CLIENT LIST/KILL, CONFIG GET/SET, MEMORY STATS/USAGE, SCAN-budgeted big-key sampling, DBSIZE, PING |
 | **rabbitmq** (management plugin HTTP API) | HTTP(S), Basic auth | /api/overview, /api/queues (+ per-vhost, detail, purge, declare, delete), /api/connections, /api/channels, /api/consumers, /api/policies (get/set/delete), /api/nodes |
 
-**26 MCP tools** — 19 reads (incl. 4 flagship RCAs) + 7 governed writes.
+**28 MCP tools** — 20 reads (incl. 4 flagship RCAs) + 8 governed writes.
 
 | Group | Tools | R/W |
 |-------|-------|:---:|
@@ -56,6 +99,7 @@ queue-aiops rabbitmq queues    # deepest backlog first
 | Flagship RCAs | redis_memory_pressure_rca, redis_latency_rca, rabbitmq_queue_backlog_rca, connection_churn_analysis | read |
 | Writes (medium) | redis_config_set, redis_kill_client, declare_queue, set_policy, delete_policy | write |
 | Writes (**high**) | purge_queue, delete_queue | write |
+| Undo | undo_list, undo_apply | read / write |
 
 The four RCAs are transparent heuristics that report their numbers — thresholds
 are named constants, every finding carries its evidence, never a black-box
@@ -131,12 +175,17 @@ queue-aiops analyze memory|latency|backlog|churn
 
 ## Verification status
 
-Preview / mock-only: the full test suite runs against mocked clients (no live
-broker needed), and the REST paths / INFO fields are modelled from the public
-docs of both platforms. Not yet validated against live production brokers —
-both are trivially self-hostable, so `queue-aiops doctor` against a
-local lab redis instance / rabbitmq broker (management plugin enabled) is
-the quickest live check.
+**Mock-validated; not yet run against live brokers.** The full test suite runs against
+mocked clients (no live broker needed): every module imports, every MCP tool carries the
+governance marker, the four flagship RCAs are unit-tested against synthetic telemetry,
+and reversible writes are asserted to record the correct inverse undo descriptor. The
+REST paths and `INFO` field names are modelled from the public docs of both platforms
+and have not been exercised against a real broker.
+
+Both platforms are trivially self-hostable, so `queue-aiops doctor` against a local lab
+redis instance / rabbitmq broker (management plugin enabled) is the quickest live check.
+[docs/VERIFICATION.md](docs/VERIFICATION.md) is the full checklist a live run must
+satisfy.
 
 ## Contributing
 

queue_aiops-0.2.0/RELEASE_NOTES.md

@@ -0,0 +1,48 @@
+# Release notes — queue-aiops 0.2.0
+
+Previous release: 0.1.1.
+
+## Headline: read-only mode
+
+```bash
+export QUEUE_READ_ONLY=1
+```
+
+With this set the **8 write tools are never registered** — an MCP
+client lists **20 tools instead of 28**. The writes are not hidden
+behind a flag and not merely refused on call: they are absent from the session,
+so a model cannot invoke one and cannot be argued into one. For a reviewer this
+is checkable rather than promised — connect, list the tools, and the writes are
+not there.
+
+Enforcement is two layers deep: the `@governed_tool` harness refuses every
+non-read operation (covering the CLI and in-process callers too), and the MCP
+server removes write tools from `list_tools()`. Changing entry point does not
+get around it.
+
+## BREAKING — return shapes changed
+
+This release changes payloads that callers may be parsing. Both changes exist
+to stop a result from misrepresenting itself:
+
+1. **Absent fields are now `null`, not `""`.** A missing value and an empty value
+   were previously indistinguishable, which invited consumers to invent the
+   difference. Keys are still always present — only the value may be null.
+2. **Anything with a `limit` now returns an envelope** —
+   `{"<items>": [...], "returned": N, "limit": L, "truncated": bool}`. Truncation is
+   *measured* (one extra row is fetched), never inferred from the page happening to
+   be full. Where a genuine pre-cap total is knowable it is reported as `total`;
+   where it isn't, `total` is deliberately omitted rather than echoing `returned`.
+
+## Also in this release
+
+- **`docs/VERIFICATION.md`** — what the mock suite actually guarantees, a live
+  verification checklist, and the criteria for claiming this tool verified.
+- **`skills/queue-aiops/references/agent-guardrails.md`** — for driving this tool with a
+  smaller / local model: which guardrails are now enforced for you, and a
+  ready-made system prompt for the rest.
+- Expanded operator playbooks in the skill documentation.
+- The advertised tool count now matches what an MCP client actually lists
+  (it includes `undo_list` / `undo_apply`), and a release gate keeps it honest.
+- The `(preview)` label has been dropped. It never meant unreleased; verification
+  status now lives in `docs/VERIFICATION.md` where it can be specific.

queue_aiops-0.2.0/docs/VERIFICATION.md

@@ -0,0 +1,200 @@
+# Live verification — redis / rabbitmq
+
+`queue-aiops` is exercised by a **mock-only** test suite (`uv run pytest`, no real
+broker). It has **not** yet been validated end-to-end against a live redis instance or
+rabbitmq broker. This document says exactly what the mock suite already guarantees, and
+what a live run has to prove before anyone may describe this tool as verified against a
+real broker.
+
+It is deliberately checklist-shaped so the result is reproducible and auditable — not a
+subjective "seems fine".
+
+## What the mock suite already guarantees
+
+- Every module imports; the CLI builds; **all 28 MCP tools** carry the `@governed_tool`
+  harness marker (`tests/test_smoke.py`, which also asserts the tool count and that
+  `__version__` matches `pyproject.toml`).
+- The four flagship analyses (`redis_memory_pressure_rca`, `redis_latency_rca`,
+  `rabbitmq_queue_backlog_rca`, `connection_churn_analysis`) are unit-tested against
+  synthetic telemetry: each cause classification fires on the right signal
+  (noeviction-near-limit vs active eviction vs fragmentation vs swapping; O(N) command
+  patterns and fork/AOF stalls; no-consumers vs unacked pile-up vs rate deficit),
+  findings cite the measured number, and partial/missing fields do not crash.
+- The **platform registry** resolves each tool to the correct redis (RESP, via the
+  `redis` Python client) or rabbitmq (management HTTP API, HTTP Basic) shape.
+- **Safety invariants** are tested: the redis surface is a typed command **allow-list**
+  with no generic passthrough; big-key sampling is `SCAN`-based under a hard budget and
+  **never** issues `KEYS *`; and rabbitmq path segments (queue/policy names, and the
+  default vhost `/` → `%2F`) are percent-encoded centrally.
+- Reversible writes record a faithful **inverse** undo descriptor built from a fetched
+  before-state (`redis_config_set` restores the prior value from `CONFIG GET`;
+  `set_policy` / `delete_policy` restore the captured definition; `declare_queue`'s undo
+  deletes it only when newly created). `purge_queue` declares **no** undo;
+  `delete_queue`'s undo re-declares the captured definition and the tests assert that
+  **messages are not claimed to be restored**.
+- Governance persistence is tested against a real on-disk SQLite audit DB: calls land as
+  rows, failures record `status=error` and no undo, and the secure-by-default approver
+  gate refuses high-risk ops when no `rules.yaml` exists.
+
+What it does **not** guarantee: that the concrete `INFO` field names, `SLOWLOG` entry
+shape, and rabbitmq management-API JSON match a real broker build. Those are modelled
+from each project's public documentation and are the **largest verification debt in this
+repo** — `INFO` field names in particular have shifted across redis 5/6/7.
+
+## Prerequisites for a live run
+
+Both platforms are free and trivially containerised:
+
+```bash
+docker run -d --name redis-verify -p 6379:6379 redis:7 \
+  redis-server --maxmemory 128mb --maxmemory-policy noeviction
+docker run -d --name rabbit-verify -p 5672:5672 -p 15672:15672 rabbitmq:3-management
+```
+
+The rabbitmq **management plugin** must be enabled (the `-management` image does this),
+and the API user needs the `monitoring` or `management` tag.
+
+Use a **throwaway broker with throwaway data**. The checklist purges and deletes queues,
+kills clients, and changes the running config — `purge_queue` destroys real messages and
+records **no undo**. Never point it at a broker carrying traffic you care about.
+
+Set the lab up so the reads have something to find:
+
+- Fill redis past 80% of a small `maxmemory` and leave the policy at `noeviction`, so the
+  most dangerous finding is reachable.
+- Create a few deliberately oversized keys (a large hash and a large list).
+- Run some `KEYS`/`SMEMBERS` calls so the SLOWLOG has genuine O(N) entries.
+- On rabbitmq, create three queues: one with **no consumer** and messages published, one
+  with a consumer that **never acks**, and one healthy — the three backlog causes.
+
+```bash
+uv tool install queue-aiops
+queue-aiops init      # wizard: pick platform, optional encrypted secret
+```
+
+Record the exact versions tested (e.g. "redis 7.4, rabbitmq 3.13") — a tick is only
+meaningful with the build it was ticked against.
+
+## Verification checklist
+
+Tick every box, **per platform**. A box that cannot be ticked is a verification gap —
+record it, do not silently pass.
+
+### 1. Connectivity (the fastest live gate)
+- [ ] `queue-aiops doctor` → green on each target: config parsed, secret store unlocks,
+      and a real `PING` / `/api/overview` returns.
+- [ ] `queue-aiops doctor --skip-auth` → passes offline (config/secret checks only).
+- [ ] An **auth-less** lab redis connects with no stored secret (this is a supported
+      configuration and a common mock-vs-reality divergence).
+- [ ] One config spanning both platforms works with `--target` switching.
+
+### 2. Reads return real, well-shaped data
+- [ ] `queue-aiops overview` → real version/role, memory posture, client counts, ops/sec,
+      hit rate and key count (redis); version, queue/message totals, connection/channel/
+      consumer counts and node alarms (rabbitmq). Confirm a **partial** failure degrades
+      into the `errors` list rather than failing the whole call.
+- [ ] `queue-aiops redis info` / `redis memory` → fields match `redis-cli INFO`
+      **on each of redis 6 and 7**, since field names have moved between versions.
+- [ ] `queue-aiops redis clients` → matches `CLIENT LIST`; `redis keyspace` matches
+      `DBSIZE` per database.
+- [ ] `queue-aiops redis slowlog --limit 50` → matches `SLOWLOG GET`, with timings
+      parsed correctly.
+- [ ] `queue-aiops redis config-get maxmemory*` → glob patterns work and match
+      `CONFIG GET`.
+- [ ] `queue-aiops redis bigkeys --count 500` → finds the oversized keys you planted, and
+      reports a **coverage %** consistent with the keyspace size. Confirm with
+      `MONITOR` or the slowlog that it issued `SCAN`, **never** `KEYS *` — this is the
+      single most important safety check in the file.
+- [ ] `queue-aiops rabbitmq queues` / `queue <name>` / `connections` / `channels` /
+      `policies` / `nodes` → match the management UI, including ready-vs-unacked splits.
+- [ ] A queue and a policy whose **names need percent-encoding** (a `/`, a space, a `%`)
+      are read correctly, and the default vhost `/` resolves as `%2F`.
+
+### 3. The analyses are right, not just non-crashing
+- [ ] With redis near `maxmemory` under `noeviction`,
+      `queue-aiops analyze memory --used-pct 85` raises the **noeviction-near-limit**
+      finding and cites the real used/max numbers. Switch to `allkeys-lru`, drive
+      evictions, and confirm the finding changes to active eviction.
+- [ ] Fragmentation vs swapping are distinguished correctly (do not accept "flagged
+      something" — check it names the right one).
+- [ ] `queue-aiops analyze latency --slow-us 10000` digests the planted O(N) entries by
+      **command pattern** and suggests the incremental variant (`KEYS` → `SCAN`).
+- [ ] Trigger a background save on a large dataset; the fork/AOF stall signal appears.
+- [ ] `queue-aiops analyze backlog --top 20` classifies each of your three planted
+      queues correctly: **no consumers**, **unacked pile-up**, and healthy.
+- [ ] Drive the node past its memory watermark; the alarm is reported as blocking **all**
+      publishers, and outranks the per-queue findings.
+- [ ] `queue-aiops analyze churn` on both platforms pins reconnect churn to the right
+      client source.
+
+### 4. A reversible write + its undo (governance closes the loop)
+- [ ] `queue-aiops redis config-set maxmemory-policy allkeys-lru --dry-run` → prints the
+      call, `CONFIG GET` shows the value unchanged.
+- [ ] `queue-aiops redis config-set maxmemory-policy allkeys-lru` → the running config
+      changes, the result carries an `_undo_id`, and a row lands in
+      `~/.queue-aiops/audit.db`.
+- [ ] `queue-aiops undo list` shows it; `undo apply <id>` restores the **prior** policy —
+      verify starting from a non-default value, where a naive undo would wrongly set
+      `noeviction`.
+- [ ] `queue-aiops rabbitmq set-policy <name> <pattern> '{"max-length":1000}'` over an
+      **existing** policy, then `undo apply` → the prior definition returns intact (not
+      a deletion).
+- [ ] `queue-aiops rabbitmq declare-queue <new> --dry-run` then for real, then
+      `undo apply` → the newly created queue is deleted. Repeat against a queue that
+      **already existed**: the undo must **not** delete it.
+
+### 5. Irreversible / asymmetric writes behave as declared
+- [ ] `queue-aiops rabbitmq purge <queue> --dry-run` → reports the message count about to
+      be destroyed; the real run destroys exactly that many and records **no** undo.
+- [ ] `queue-aiops rabbitmq delete-queue <queue>` on a queue **with messages**, then
+      `undo apply` → the queue is re-declared with the right durable/auto-delete flags,
+      and the **messages are gone**. Confirm the tool never claimed otherwise.
+- [ ] `queue-aiops redis kill-client --addr <ip:port>` drops that connection, records no
+      undo, and is audited.
+
+### 6. Governance actually gates
+- [ ] With no `~/.queue-aiops/rules.yaml`, `purge_queue` and `delete_queue` are
+      **refused** unless `QUEUE_AUDIT_APPROVED_BY` is set (secure-by-default); with it
+      plus `QUEUE_AUDIT_RATIONALE`, both appear in the audit row.
+- [ ] A tight poll loop trips the runaway budget guard rather than hammering the broker.
+- [ ] A failed call (nonexistent queue) is audited `status=error` and records no undo.
+- [ ] Attempting a redis command outside the typed allow-list is rejected **before** the
+      client sends anything — confirm against the live server that nothing executes.
+
+### 7. Cleanup
+- [ ] Restore every config value you changed, delete the throwaway queues and policies,
+      and flush the lab redis.
+- [ ] `queue-aiops overview` matches the baseline you captured before starting.
+- [ ] Skim `~/.queue-aiops/audit.db` — every write is there with the right risk tier.
+
+## Criteria to consider it live-verified
+
+All of the following must hold:
+
+1. Every box above is ticked against **both** a real redis and a real rabbitmq, with the
+   exact builds recorded (e.g. "redis 7.4 + rabbitmq 3.13"), and the redis reads
+   re-checked on at least **two major redis versions** given the `INFO` field drift.
+2. Every field-name or API-shape mismatch found is **fixed and covered by a regression
+   test**, so the mock suite would now catch it.
+3. Section 4 passed, including the asymmetric `declare_queue` case (undo must delete only
+   a queue it created). Recording an undo descriptor is not the same as the undo
+   working, and this product line has shipped broken undo pairs before.
+4. The big-key sampler was confirmed **live** to issue `SCAN` under budget and never
+   `KEYS *` — a mock cannot prove this, and getting it wrong stalls a production redis.
+5. The run is written up in the release notes / product-line memory with the date and
+   package version, matching how the line records its other live-verified tools.
+
+Until then, this repo says only what is true: mock-validated, live-unverified. Claiming
+otherwise would break that promise.
+
+## Notes for maintainers
+
+- `queue-aiops doctor` is the single fastest live entry point; start there.
+- Weight the run toward **redis `INFO` field names** and **rabbitmq percent-encoded path
+  segments** — those are the two places the mocks are least able to model.
+- Managed cloud queue services (ElastiCache, Amazon MQ, CloudAMQP, …) are a **separate**
+  verification target: wire-compatible reads may work, but `CONFIG SET` and
+  `CLIENT KILL` are commonly restricted. Do not infer managed support from a self-hosted
+  run.
+- Add this tool's result to the product-line verification ledger once green, so the
+  central "verification debt" list stays accurate.

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/mcp_server/_shared.py

@@ -75,7 +75,7 @@ def tool_errors(shape: str = "dict") -> Callable:
 mcp = FastMCP(
     "queue-aiops",
     instructions=(
-        "Queue/cache broker operations (preview) over redis and rabbitmq: for a "
+        "Queue/cache broker operations over redis and rabbitmq: for a "
         "redis target — server/memory/keyspace reads, clients, slowlog, config, "
         "and a SCAN-budgeted big-key sample (never KEYS *); for a rabbitmq "
         "target — management-API overview, queues, connections, channels, "

queue_aiops-0.2.0/mcp_server/server.py

@@ -0,0 +1,76 @@
+"""MCP server wrapping queue-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``queue_aiops`` ops package and is wrapped with the
+queue-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed broker operations over redis and rabbitmq:
+redis server/memory/clients/slowlog/config/keyspace/big-key reads, rabbitmq
+overview/queues/connections/channels/policies/node reads, four flagship
+analyses, and governed writes (redis config set + client kill; rabbitmq queue
+purge/delete/declare and policy set/delete).
+
+Source: https://github.com/AIops-tools/Queue-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
+    analysis,
+    overview,
+    rabbit_reads,
+    redis_reads,
+    undo,
+    writes,
+)
+from queue_aiops.governance import READ_ONLY_ENV, is_read_only
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors", "apply_read_only"]
+
+logger = logging.getLogger(__name__)
+
+
+def apply_read_only() -> list[str]:
+    """Unregister every write tool when read-only mode is on.
+
+    The ``@governed_tool`` harness already refuses writes in this mode, so this
+    is a second layer — and the one that matters for smaller local models:
+    a tool absent from ``list_tools()`` cannot be hallucinated into a call,
+    whereas a tool that exists but refuses invites retry loops. It also gives a
+    compliance reviewer something checkable — the write tools are simply not
+    exposed.
+
+    ``risk_level == "low"`` is the read/write discriminator; a smoke test
+    asserts it stays in agreement with each tool's ``[READ]``/``[WRITE]``
+    docstring tag so the two can never drift apart silently.
+
+    Returns the names that were removed (empty when not in read-only mode).
+    """
+    if not is_read_only():
+        return []
+    registry = mcp._tool_manager._tools
+    dropped = [
+        name
+        for name, tool in registry.items()
+        if getattr(getattr(tool, "fn", None), "_risk_level", "low") != "low"
+    ]
+    for name in dropped:
+        del registry[name]
+    if dropped:
+        logger.info(
+            "%s is set — read-only mode: %d write tool(s) not exposed",
+            READ_ONLY_ENV, len(dropped),
+        )
+    return dropped
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    apply_read_only()
+    mcp.run(transport="stdio")

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/mcp_server/tools/rabbit_reads.py

@@ -28,6 +28,10 @@ def list_queues(vhost: Optional[str] = None, target: Optional[str] = None) -> di
     Args:
         vhost: Restrict to one vhost (the default vhost is '/'); omit for all.
         target: rabbitmq target name from config; omit for the default.
+
+    Returns an envelope: {"queues": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.list_queues(_get_connection(target), vhost)
 
@@ -54,6 +58,10 @@ def list_connections(target: Optional[str] = None) -> dict:
 
     Args:
         target: rabbitmq target name from config; omit for the default.
+
+    Returns an envelope: {"connections": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.list_connections(_get_connection(target))
 
@@ -66,6 +74,10 @@ def list_channels(target: Optional[str] = None) -> dict:
 
     Args:
         target: rabbitmq target name from config; omit for the default.
+
+    Returns an envelope: {"channels": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.list_channels(_get_connection(target))
 
@@ -79,6 +91,10 @@ def list_policies(vhost: Optional[str] = None, target: Optional[str] = None) ->
     Args:
         vhost: Restrict to one vhost (the default vhost is '/'); omit for all.
         target: rabbitmq target name from config; omit for the default.
+
+    Returns an envelope: {"policies": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.list_policies(_get_connection(target), vhost)
 

{queue_aiops-0.1.0 → queue_aiops-0.2.0}/mcp_server/tools/redis_reads.py

@@ -39,6 +39,10 @@ def redis_clients(target: Optional[str] = None) -> dict:
 
     Args:
         target: redis target name from config; omit for the default.
+
+    Returns an envelope: {"clients": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.list_clients(_get_connection(target))
 
@@ -52,6 +56,10 @@ def redis_slowlog(count: int = 128, target: Optional[str] = None) -> dict:
     Args:
         count: Max entries to pull (capped at 128).
         target: redis target name from config; omit for the default.
+
+    Returns an envelope: {"entries": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.slowlog(_get_connection(target), count)
 
@@ -94,5 +102,9 @@ def redis_big_keys(top: int = 20, target: Optional[str] = None) -> dict:
     Args:
         top: How many key rows to return, largest first (default 20).
         target: redis target name from config; omit for the default.
+
+    Returns an envelope: {"topKeys": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — do not treat this as the complete set.
     """
     return ops.big_key_sample(_get_connection(target), top)