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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxy-aiops
-Version: 0.1.0
+Version: 0.2.0
 Summary: Governed AI-ops for Traefik + Caddy + HAProxy reverse proxies / load balancers: routes, services, upstream health, TLS cert expiry sweep, 5xx error-rate RCA, route conflict analysis, and governed writes (caddy config, haproxy server state/weight) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: wei <zhouwei008@gmail.com>
 License-Expression: MIT
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.AIops-tools/proxy-aiops -->
 
-# Proxy AIops (preview)
+# Proxy AIops
 
 Governed, audited AI-ops for **Traefik**, **Caddy** and **HAProxy** reverse proxies / load balancers — for AI agents (via MCP) and humans (via CLI).
 
@@ -57,7 +57,47 @@ risk-tier approval, undo-token recording, and output sanitisation.
   restores the prior value) — all with `dry_run` previews; delete/load are
   **risk=high** behind an approver gate.
 
-## Tool inventory (26 tools)
+## 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 PROXY_READ_ONLY=1
+```
+
+With that set, the **6 write tools are never registered**. An MCP client
+lists **22 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
+`~/.proxy-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/proxy-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.
+
+## Tool inventory (28 tools)
 
 | Domain | Tools | # | Kind |
 |--------|-------|:-:|------|
@@ -71,6 +111,7 @@ risk-tier approval, undo-token recording, and output sanitisation.
 | **Writes (caddy)** | `set_config_value` | 1 | write (**med**) |
 | **Writes (caddy)** | `delete_config_path`, `load_config` | 2 | write (**high**) |
 | **Writes (haproxy)** | `set_server_state`, `set_server_weight` | 2 | write (**med**) |
+| **Undo** | `undo_list`, `undo_apply` | 2 | read / write |
 
 Reversible writes record an inverse **undo descriptor** built from the real fetched
 before-state (`set_config_value` restores the prior subtree; `delete_config_path`
@@ -191,17 +232,20 @@ Every MCP tool is wrapped by `@governed_tool`:
 - **Sanitisation** — all proxy-returned text is bounded + control-character
   sanitised before it reaches the agent.
 
-## Preview status
+## Platform support & verification status
 
 - **Platforms**: Traefik (API + /metrics), Caddy (admin API), HAProxy (Data Plane
   API v2).
-- **Preview — mock-validated only. Not run against a live proxy.** All behaviour is
-  validated against mocked JSON/metrics responses; the concrete REST paths are
-  modelled from each project's public API and need live verification. All three
-  platforms are free and self-hostable (a small container-compose lab with
-  traefik + caddy + haproxy/dataplaneapi is a one-evening setup), so
-  `proxy-aiops doctor` — a health/info probe per platform — is the fastest
-  live check.
+- **Test coverage**: behaviour is validated against mocked JSON/metrics responses —
+  every module imports, every MCP tool carries the governance marker, the four flagship
+  analyses are unit-tested against synthetic telemetry, the support matrix is asserted
+  to raise teaching errors (never a silent no-op), and reversible writes are asserted to
+  record the correct inverse undo descriptor. The concrete REST paths are modelled from
+  each project's public API and have not yet been exercised against a live proxy. See
+  [docs/VERIFICATION.md](docs/VERIFICATION.md) for the checklist a live run must
+  satisfy. All three platforms are free and self-hostable (a small container-compose lab
+  with traefik + caddy + haproxy/dataplaneapi is a one-evening setup), and
+  `proxy-aiops doctor` — a health/info probe per platform — is the fastest live check.
 - **Routing note**: this tool operates reverse proxies / load balancers. Do NOT
   use it for firewall rules — use firewall-aiops.
 - **Missing a capability?** Open an issue or PR at

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

@@ -1,6 +1,6 @@
 <!-- mcp-name: io.github.AIops-tools/proxy-aiops -->
 
-# Proxy AIops (preview)
+# Proxy AIops
 
 Governed, audited AI-ops for **Traefik**, **Caddy** and **HAProxy** reverse proxies / load balancers — for AI agents (via MCP) and humans (via CLI).
 
@@ -41,7 +41,47 @@ risk-tier approval, undo-token recording, and output sanitisation.
   restores the prior value) — all with `dry_run` previews; delete/load are
   **risk=high** behind an approver gate.
 
-## Tool inventory (26 tools)
+## 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 PROXY_READ_ONLY=1
+```
+
+With that set, the **6 write tools are never registered**. An MCP client
+lists **22 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
+`~/.proxy-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/proxy-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.
+
+## Tool inventory (28 tools)
 
 | Domain | Tools | # | Kind |
 |--------|-------|:-:|------|
@@ -55,6 +95,7 @@ risk-tier approval, undo-token recording, and output sanitisation.
 | **Writes (caddy)** | `set_config_value` | 1 | write (**med**) |
 | **Writes (caddy)** | `delete_config_path`, `load_config` | 2 | write (**high**) |
 | **Writes (haproxy)** | `set_server_state`, `set_server_weight` | 2 | write (**med**) |
+| **Undo** | `undo_list`, `undo_apply` | 2 | read / write |
 
 Reversible writes record an inverse **undo descriptor** built from the real fetched
 before-state (`set_config_value` restores the prior subtree; `delete_config_path`
@@ -175,17 +216,20 @@ Every MCP tool is wrapped by `@governed_tool`:
 - **Sanitisation** — all proxy-returned text is bounded + control-character
   sanitised before it reaches the agent.
 
-## Preview status
+## Platform support & verification status
 
 - **Platforms**: Traefik (API + /metrics), Caddy (admin API), HAProxy (Data Plane
   API v2).
-- **Preview — mock-validated only. Not run against a live proxy.** All behaviour is
-  validated against mocked JSON/metrics responses; the concrete REST paths are
-  modelled from each project's public API and need live verification. All three
-  platforms are free and self-hostable (a small container-compose lab with
-  traefik + caddy + haproxy/dataplaneapi is a one-evening setup), so
-  `proxy-aiops doctor` — a health/info probe per platform — is the fastest
-  live check.
+- **Test coverage**: behaviour is validated against mocked JSON/metrics responses —
+  every module imports, every MCP tool carries the governance marker, the four flagship
+  analyses are unit-tested against synthetic telemetry, the support matrix is asserted
+  to raise teaching errors (never a silent no-op), and reversible writes are asserted to
+  record the correct inverse undo descriptor. The concrete REST paths are modelled from
+  each project's public API and have not yet been exercised against a live proxy. See
+  [docs/VERIFICATION.md](docs/VERIFICATION.md) for the checklist a live run must
+  satisfy. All three platforms are free and self-hostable (a small container-compose lab
+  with traefik + caddy + haproxy/dataplaneapi is a one-evening setup), and
+  `proxy-aiops doctor` — a health/info probe per platform — is the fastest live check.
 - **Routing note**: this tool operates reverse proxies / load balancers. Do NOT
   use it for firewall rules — use firewall-aiops.
 - **Missing a capability?** Open an issue or PR at

proxy_aiops-0.2.0/RELEASE_NOTES.md

@@ -0,0 +1,48 @@
+# Release notes — proxy-aiops 0.2.0
+
+Previous release: 0.1.0.
+
+## Headline: read-only mode
+
+```bash
+export PROXY_READ_ONLY=1
+```
+
+With this set the **6 write tools are never registered** — an MCP
+client lists **22 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/proxy-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.

proxy_aiops-0.2.0/docs/VERIFICATION.md

@@ -0,0 +1,191 @@
+# Live verification — Traefik / Caddy / HAProxy
+
+`proxy-aiops` is exercised by a **mock-only** test suite (`uv run pytest`, no real
+proxy). It has **not** yet been validated end-to-end against a live Traefik, Caddy, or
+HAProxy instance. 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 proxy.
+
+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 (`backend_health_rca`, `cert_expiry_sweep`,
+  `error_rate_rca`, `route_conflict_analysis`) are unit-tested against synthetic
+  telemetry: the health-check failure classes (connection refused / L4 timeout / TLS /
+  L7 / DNS / maint) each map to the right cause, the dominant-status-code mapping
+  (502/503/504/500) fires correctly, expiry bucketing respects the warn/critical
+  thresholds, and shadowed / dead / looping routes are each detected with the covering
+  route or missing service named.
+- The **platform registry** resolves each tool to the correct Traefik (`/api/...` plus
+  the `/metrics` text format), Caddy (admin API), and HAProxy (Data Plane API v2
+  `/v2/...`, HTTP Basic) request shape.
+- The **support matrix** is asserted to raise a *teaching error* — never a silent no-op —
+  for operations a platform cannot perform (Traefik writes → edit its providers; Caddy
+  error counters → access logs; HAProxy certs → the `.pem` pipeline).
+- Reversible writes record a faithful **inverse** undo descriptor built from a fetched
+  before-state (`set_config_value` restores the prior subtree, or deletes a path it
+  created; `delete_config_path` re-creates the captured subtree; `set_server_state` /
+  `set_server_weight` restore the prior admin state / weight), and the descriptor's
+  params replay against the tool's own signature.
+- 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 REST paths, JSON field names, and the
+Traefik `/metrics` text format match a real build of each proxy. Those are modelled from
+each project's public API documentation and are the **largest verification debt in this
+repo** — the metrics-text parsing in particular is brittle against format changes.
+
+## Prerequisites for a live run
+
+All three proxies are free and self-hostable; a single compose file gets you the whole
+matrix in an evening:
+
+- **Traefik** — expose the API (`--api=true`, a router on `api@internal`) **and**
+  metrics (`--metrics.prometheus=true`), since `traffic_stats` / `error_counters` read
+  the metrics endpoint, not the API.
+- **Caddy** — the admin API on `localhost:2019` (its default). This is the target that
+  carries the config write surface, so it is where sections 4–6 actually run.
+- **HAProxy** — plus the **Data Plane API v2** (`dataplaneapi`), with a Basic-auth user.
+  This is the target that carries the runtime server writes.
+
+Behind each proxy, put **at least two throwaway backends** so you can drain one, and a
+deliberately broken one (a closed port, and a TLS-mismatched one) so the health RCA has
+real failures to classify. Use a **lab edge** — the checklist drains servers and rewrites
+config, and `load_config` replaces a Caddy instance's *entire* configuration.
+
+```bash
+uv tool install proxy-aiops
+proxy-aiops init      # wizard: pick platform, optional encrypted secret
+```
+
+Record the exact versions tested (e.g. "Traefik 3.2, Caddy 2.8, HAProxy 3.0 +
+dataplaneapi 3.0") — 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)
+- [ ] `proxy-aiops doctor` → green on each target: config parsed, secret store unlocks
+      (HAProxy), and a real health/info probe returns.
+- [ ] `proxy-aiops doctor --skip-auth` → passes offline (config/secret checks only).
+- [ ] One config spanning **all three** platforms works with `--target` switching — this
+      mixed-edge case is the reason the platform registry exists.
+
+### 2. Reads return real, well-shaped data
+- [ ] `proxy-aiops overview` → real platform/version, route and service counts, and
+      upstream up/down totals matching each proxy's own dashboard.
+- [ ] `proxy-aiops routes list` → the real routers/routes/frontends with correct hosts,
+      paths, priority, and TLS flags.
+- [ ] `proxy-aiops routes show <name>` → one route's full detail.
+- [ ] `proxy-aiops routes find <host> --path /api` → returns the route that **actually**
+      serves that request. Verify by curling the host and comparing which backend
+      answers — this is the single most valuable correctness check in the file.
+- [ ] `proxy-aiops services list` / `services show <name>` / `services upstreams <name>`
+      → real servers with correct address, status (up/down/maint/drain), check info, and
+      weight.
+- [ ] MCP `list_middlewares` → real Traefik middlewares; a **teaching error** on Caddy
+      and HAProxy rather than an empty list.
+- [ ] MCP `traffic_stats` / `error_counters` → numbers that move when you generate load,
+      and that agree with the proxy's own stats page. On Traefik confirm the
+      **`/metrics` text parsing** survives the real format; on Caddy confirm the
+      teaching error (counters come from access logs there).
+- [ ] `proxy-aiops config snapshot` / `config search <needle>` / `config get <path>` →
+      the real Caddy config tree; teaching errors on Traefik/HAProxy.
+- [ ] `proxy-aiops certs` → the real TLS domain inventory; teaching note on HAProxy.
+
+### 3. The analyses are right, not just non-crashing
+- [ ] Stop one backend; `proxy-aiops analyze health` names that server and classifies the
+      failure as connection-refused (not a generic "down").
+- [ ] Point a backend at a TLS-mismatched endpoint; the class comes back TLS, not L4.
+- [ ] Drive real 503s (all servers of one service down) and real 504s (a backend that
+      sleeps past the timeout); `proxy-aiops analyze errors --rate 5 --min-requests 100`
+      flags the right service and maps each **dominant code to the correct cause**.
+- [ ] Confirm `--min-requests` actually suppresses a low-traffic service with a single
+      failure.
+- [ ] `proxy-aiops certs --sweep --warn-days 30 --critical-days 7` → live-probed expiry
+      dates match `openssl s_client` for the same domain, and bucketing is correct
+      either side of both thresholds. Repeat with `--port` on a non-443 listener.
+- [ ] Create a genuinely shadowed route (a broad higher-priority route above a specific
+      one) and a dead route (pointing at a nonexistent service);
+      `proxy-aiops analyze conflicts` names the covering route and the missing service.
+
+### 4. A reversible write + its undo — Caddy config
+- [ ] `proxy-aiops config set <path> '<json>' --dry-run` → prints the write, changes
+      nothing (confirm with `config get <path>`).
+- [ ] `proxy-aiops config set <path> '<json>'` → the config actually changes, the result
+      carries an `_undo_id`, and a row lands in `~/.proxy-aiops/audit.db`.
+- [ ] `proxy-aiops undo list` shows it; `undo apply <id>` restores the **prior subtree
+      byte-for-byte** (compare against the `config snapshot` you took first).
+- [ ] `config set` on a path that did **not** previously exist, then `undo apply` → the
+      created path is *deleted*, not reset to a guessed value. This asymmetric case is
+      where a naive undo silently leaves debris.
+- [ ] MCP `delete_config_path` then `undo apply` → the deleted subtree is re-created
+      intact.
+
+### 5. A reversible write + its undo — HAProxy runtime
+- [ ] `proxy-aiops server state <backend> <server> drain --dry-run` → nothing changes.
+- [ ] `proxy-aiops server state <backend> <server> drain` → the server actually drains
+      (confirm in the HAProxy stats page), in-flight connections finish, and an
+      `_undo_id` is returned.
+- [ ] `undo apply <id>` restores the **prior** state — verify starting from a server that
+      was already in `maint`, where a naive undo would wrongly set `ready`.
+- [ ] `proxy-aiops server weight <backend> <server> 50` then `undo apply` → the prior
+      weight returns, not a default.
+- [ ] The same commands against a Traefik or Caddy target raise a **teaching error**
+      naming the right mechanism.
+
+### 6. Governance actually gates
+- [ ] With no `~/.proxy-aiops/rules.yaml`, `delete_config_path` and `load_config` are
+      **refused** unless `PROXY_AUDIT_APPROVED_BY` is set (secure-by-default); with it
+      plus `PROXY_AUDIT_RATIONALE`, both appear in the audit row.
+- [ ] `load_config` on a lab Caddy replaces the whole config, and `undo apply` restores
+      the snapshotted original — then confirm traffic actually flows again, since a
+      restored-but-not-reloaded config would still be an outage.
+- [ ] A tight poll loop trips the runaway budget guard rather than hammering the API.
+- [ ] A failed call (nonexistent route name) is audited `status=error` with no undo.
+
+### 7. Cleanup
+- [ ] Return every drained server to its prior state, restore every weight, and undo
+      every config edit.
+- [ ] `proxy-aiops overview` and `proxy-aiops config snapshot` match the baseline you
+      captured before starting.
+- [ ] Skim `~/.proxy-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 **all three** platforms, with the exact builds
+   recorded (e.g. "Traefik 3.2 + Caddy 2.8 + HAProxy 3.0/dataplaneapi 3.0").
+2. Every REST-path, field-shape, or metrics-format mismatch found is **fixed and covered
+   by a regression test**, so the mock suite would now catch it.
+3. Sections 4 and 5 passed, including the asymmetric cases (creating a config path then
+   undoing it; undoing a drain on a server that started in `maint`). Recording an undo
+   descriptor is not the same as the undo working, and this product line has shipped
+   broken undo pairs before.
+4. Every support-matrix teaching error was confirmed **live** — a real unsupported call
+   must teach, not silently succeed or silently do nothing.
+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
+
+- `proxy-aiops doctor` is the single fastest live entry point; start there.
+- Weight the run toward **Traefik `/metrics` text parsing** and the **Caddy config-path
+  semantics** — those are the two places the mocks are least able to model, and both
+  change between releases.
+- Managed cloud load balancers are explicitly out of scope; do not infer support for them
+  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.

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

@@ -77,7 +77,7 @@ def tool_errors(shape: str = "dict") -> Callable:
 mcp = FastMCP(
     "proxy-aiops",
     instructions=(
-        "Reverse-proxy / load-balancer operations (preview) over Traefik, Caddy "
+        "Reverse-proxy / load-balancer operations over Traefik, Caddy "
         "and HAProxy: version/entrypoints, routes (routers / caddy routes / "
         "frontends), services and server-level upstream health, middlewares, "
         "TLS certificate inventory, traffic/error counters, and config "

proxy_aiops-0.2.0/mcp_server/server.py

@@ -0,0 +1,78 @@
+"""MCP server wrapping proxy-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``proxy_aiops`` ops package and is wrapped with the
+proxy-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed reverse-proxy operations over Traefik,
+Caddy and HAProxy: status/routes/services/upstreams/certs/traffic/config
+reads, four flagship analyses, and governed writes (caddy config set/delete/
+load, haproxy server state/weight).
+
+Source: https://github.com/AIops-tools/Proxy-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,
+    certs,
+    configread,
+    routes,
+    services,
+    status,
+    traffic,
+    undo,
+    writes,
+)
+from proxy_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")

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/mcp_server/tools/configread.py

@@ -31,6 +31,10 @@ def search_config(query: str, target: Optional[str] = None) -> dict:
     Args:
         query: Case-insensitive substring to find in keys and values.
         target: Proxy target name from config; omit for the default.
+
+    Returns an envelope: {"matches": [...], "returned": N, "limit": L,
+    "truncated": bool}. When "truncated" is true there is more than was
+    returned — narrow the query rather than treating these as every match.
     """
     return ops.search_config(_get_connection(target), query)
 

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/mcp_server/tools/traffic.py

@@ -17,7 +17,12 @@ def traffic_stats(target: Optional[str] = None) -> dict:
 
     Args:
         target: Proxy target name from config; omit for the default.
+
+    Returns an envelope: {"services": [...], "returned": N, "limit": L,
+    "truncated": bool, "total": T}. When "truncated" is true this proxy serves
+    more services than were returned.
     """
+
     return ops.traffic_stats(_get_connection(target))
 
 
@@ -32,5 +37,10 @@ def error_counters(target: Optional[str] = None) -> dict:
 
     Args:
         target: Proxy target name from config; omit for the default.
+
+    Returns an envelope: {"services": [...], "returned": N, "limit": L,
+    "truncated": bool, "total": T}. When "truncated" is true this proxy serves
+    more services than were returned (only the busiest services are returned).
     """
+
     return ops.error_counters(_get_connection(target))

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/mcp_server/tools/undo.py

@@ -36,13 +36,24 @@ def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
     Each entry names the original tool, the inverse tool that ``undo_apply``
     would run, and a human note. Use the ``undoId`` with ``undo_apply``.
 
+    Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}.
+    ``truncated`` is *measured* (one extra row is fetched), not guessed from a
+    length coincidence: when it is true there are MORE tokens than shown, so
+    re-run with a higher ``limit`` rather than reporting the list as complete.
+
     Args:
-        limit: Max rows to return (default 50).
+        limit: Max rows to return (default 50, capped at 500).
         target: Unused (undo state is host-local); accepted for CLI uniformity.
     """
-    rows = get_undo_store().list(status="recorded", limit=max(1, min(limit, 500)))
+    requested = max(1, min(limit, 500))
+    raw = get_undo_store().list(status="recorded", limit=requested + 1)
+    truncated = len(raw) > requested
+    rows = raw[:requested]
     return {
         "count": len(rows),
+        "returned": len(rows),
+        "limit": requested,
+        "truncated": truncated,
         "undos": [
             {
                 "undoId": r["undo_id"],

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/proxy_aiops/cli/configcmd.py

@@ -50,7 +50,13 @@ def config_search(
     from proxy_aiops.ops import configread as ops
 
     conn, _ = get_connection(target)
-    console.print_json(json.dumps(ops.search_config(conn, query)))
+    result = ops.search_config(conn, query)
+    console.print_json(json.dumps(result))
+    if result.get("truncated"):
+        console.print(
+            f"[yellow]… truncated at {result.get('limit')} matches — "
+            f"narrow the query to see the rest.[/yellow]"
+        )
 
 
 @config_app.command("get")

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/proxy_aiops/governance/__init__.py

@@ -18,12 +18,16 @@ from proxy_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_bud
 from proxy_aiops.governance.decorators import PolicyDenied, governed_tool
 from proxy_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
 from proxy_aiops.governance.policy import TierDecision, get_policy_engine
-from proxy_aiops.governance.sanitize import sanitize
+from proxy_aiops.governance.readonly import READ_ONLY_ENV, is_read_only
+from proxy_aiops.governance.sanitize import opt_str, sanitize
 from proxy_aiops.governance.undo import UndoStore, get_undo_store
 
 __all__ = [
     "governed_tool",
     "sanitize",
+    "opt_str",
+    "is_read_only",
+    "READ_ONLY_ENV",
     "PolicyDenied",
     "get_engine",
     "AuditEngine",

{proxy_aiops-0.1.0 → proxy_aiops-0.2.0}/proxy_aiops/governance/decorators.py

@@ -36,6 +36,7 @@ from proxy_aiops.governance.audit import detect_agent, get_engine
 from proxy_aiops.governance.budget import BudgetExceeded, get_budget
 from proxy_aiops.governance.patterns import PatternMatch, get_pattern_engine
 from proxy_aiops.governance.policy import PolicyResult, get_policy_engine
+from proxy_aiops.governance.readonly import is_read_only, read_only_denial
 from proxy_aiops.governance.sanitize import sanitize
 
 _log = logging.getLogger("proxy-aiops.decorators")
@@ -233,6 +234,17 @@ def _pre_check(state: _CallState) -> None:
     never block the call (fail-open by design — a broken pattern file must
     not take down every MCP tool).
     """
+    # Read-only mode is a hard switch, checked before policy so that no write
+    # reaches an API regardless of entry point (MCP, CLI, or in-process) and
+    # regardless of what rules.yaml says. risk_level 'low' == a read.
+    if state.risk_level != "low" and is_read_only():
+        reason = read_only_denial(state.tool_name)
+        denial = PolicyResult(allowed=False, rule="read_only", reason=reason)
+        state.policy_result = denial
+        state.status = "denied"
+        state.result = {"error": reason, "rule": denial.rule}
+        raise PolicyDenied(denial)
+
     state.policy_result = state.policy.check_allowed(
         state.tool_name,
         env=state.env,