feat: cache-freshness controls — fresh arg + clear_cache tool (#282)

Fixes a footgun surfaced by a user report: re-running index/constraint
validation after an out-of-band foreign-key change returned the pre-change
answer, served stale from the TTL read cache. The cache is invalidated by
MCPg's own write/DDL tools but is blind to changes made outside MCPg until the
TTL (default 300s) expires.

Proportionate fix (no pg_catalog polling / event triggers):
- `_cached_call` gains `fresh: bool = False`, threaded onto the
  introspection/advisor reads used in change->verify loops (describe_table,
  list_indexes, list_constraints, list_foreign_keys, get_compact_schema,
  recommend_indexes, audit_database). fresh=true bypasses the read, re-queries
  live, and refreshes the entry; it is not part of the cache key.
- new `clear_cache` tool (full flush), gated to the WRITE surface so the
  read-only demo can't spam-flush; non-destructive; operations_and_health.

Tool surface 252 -> 253; both contract snapshots + doc tables regenerated;
current-state counts and anchors updated; user-guide caching section corrected
and fresh/clear_cache/MCPG_CACHE_ENABLED documented. New test_cache_freshness.py.
Full unit suite (2805) + contract + about green.

N/A — reactive correctness fix, not a planned roadmap item.

Author: devopam

CHANGELOG.md

@@ -6,6 +6,27 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **Cache-freshness controls for out-of-band schema changes.** MCPg's read
+  cache is invalidated automatically by MCPg's own write/DDL tools, but it
+  could serve stale introspection/advisor results for up to
+  `MCPG_CACHE_TTL_SECONDS` (default 300s) after a schema change made *outside*
+  MCPg (a direct `psql`/migration change, another connection, or a second
+  process) — e.g. re-running index/constraint validation after altering a
+  foreign key returned the pre-change answer. Two escape hatches:
+  - a per-call **`fresh: bool = False`** argument on the introspection/advisor
+    reads (`describe_table`, `list_indexes`, `list_constraints`,
+    `list_foreign_keys`, `get_compact_schema`, `recommend_indexes`,
+    `audit_database`) — bypasses the cache read, re-queries live, and refreshes
+    the entry;
+  - a new **`clear_cache`** tool — a full flush for a known out-of-band change,
+    gated to write-capable modes (not exposed on the read-only surface).
+
+  Tool surface **252 → 253**. `docs/user-guide.md` caching section corrected
+  (automatic invalidation covers through-MCPg mutations, not arbitrary
+  out-of-band DDL).
+
 ### Security
 
 - **Bumped `mcp` SDK ≥ 1.28.1** (from `≥ 1.25.0`) to clear three advisories in

CLAUDE.md

@@ -6,7 +6,7 @@ stays true; verify anything here against the code before relying on it.
 ## What MCPg is
 
 A production-grade PostgreSQL MCP server. Single-process, async
-(`asyncio`), Python 3.12–3.14. **252 MCP tools** (read-only mode exposes
+(`asyncio`), Python 3.12–3.14. **253 MCP tools** (read-only mode exposes
 a subset). Ships to PyPI (`mcpg`), GHCR, the MCP registry, Smithery, and
 a read-only HF Spaces demo.
 

README.md

@@ -4,7 +4,7 @@
 
 **A production-grade [Model Context Protocol](https://modelcontextprotocol.io)
 server for PostgreSQL.** Lets AI agents safely inspect, query, operate, and
-tune a Postgres database — 252 tools spanning catalog introspection,
+tune a Postgres database — 253 tools spanning catalog introspection,
 query intelligence, natural-language SQL, structural diffs, hybrid search,
 graph queries, data movement, live ops, and more.
 

docs/architecture.md

@@ -83,7 +83,7 @@ this table is the exhaustive index. Regenerate with
 | `mcpg.autovacuum` | Autovacuum priority advisor — `read_autovacuum_priority`. |
 | `mcpg.cache` | Thread-safe, async-safe caching manager for PostgreSQL introspections and summaries. |
 | `mcpg.composite` | Composite tools — agent UX wins built on top of existing primitives. |
-| `mcpg.config` | Env-driven, validated `Settings` (frozen dataclass); redacts secrets in `__repr__`. |
+| `mcpg.config` | Env-driven, typed configuration for the MCPg server. |
 | `mcpg.config_advisor` | Configuration & sizing advisors — pghero / pgtune coverage. |
 | `mcpg.context` | `AppContext` — per-server state (settings, DB, cursor/listen managers) shared with tool wrappers. |
 | `mcpg.cron` | pg_cron job-scheduling wrappers. |
@@ -147,7 +147,7 @@ this table is the exhaustive index. Regenerate with
 | `mcpg.replicas` | Read-replica routing — distribute read-only queries across replicas. |
 | `mcpg.resources` | MCP resources — preload-on-connect surface (`mcpg://…`). |
 | `mcpg.rls` | Row-Level Security tester — see what an RLS-bound role would read. |
-| `mcpg.schema_diff` | Structural schema diff powering `compare_schemas`. |
+| `mcpg.schema_diff` | Structural diff between two PostgreSQL schemas. |
 | `mcpg.schema_docs` | Schema documentation generator. |
 | `mcpg.secrets` | Pluggable secrets backend. |
 | `mcpg.server` | MCP server bootstrap for MCPg. |

docs/plans/bm25-integration.md

@@ -6,7 +6,7 @@
 > `pg_search_parse_query`, `hybrid_bm25_vector_search`,
 > `create_pg_search_index`, `reindex_pg_search_index`, plus the
 > observability/advisor tools — see the
-> [tool index](../tools.md#tool-index-252-tools). This doc is kept for
+> [tool index](../tools.md#tool-index-253-tools). This doc is kept for
 > its design rationale and the deferred-alternatives (`pg_textsearch`,
 > `vchord_bm25`) return conditions; it is no longer a live roadmap.
 > Current gaps live in [feature-shortlist.md](../feature-shortlist.md).

docs/plans/pg19-readiness.md

@@ -44,7 +44,7 @@ that accidentally deletes a tool fails CI.
 |---|---|---|
 | 1. CI matrix + compatibility surface | ✅ **Shipped** | PG 19 beta runs as an experimental (`continue-on-error`) matrix entry; pgvector built from source via `.github/ci-postgres-pg19.Dockerfile`. A WarehousePG (MPP) characterisation lane landed alongside. PostGIS still deferred until an apt package is published. |
 | 2. Feature audit | ✅ **Done** | The Beta 1 sweep below is complete — every domain triaged through the product-owner lens. |
-| 3. Incremental landing | ⏳ **Largely shipped** | Many tool families have landed: SQL/PGQ property graphs (`run_pgq`, `create_property_graph`, …), in-server `REPACK` (`repack_table`), skip-scan advisor (`recommend_skip_scan_indexes`), `WAIT FOR LSN` read-your-writes (`wait_for_lsn`), online data-checksum + on-demand logical-replication toggles, DDL introspection (`get_role_ddl` / `get_database_ddl` / `get_tablespace_ddl` / `validate_check_constraint`), partition `MERGE` / `SPLIT`, lock + recovery stats, and async-I/O coverage. See the [tool index](../tools.md#tool-index-252-tools) for the shipped surface and [feature-shortlist.md](../feature-shortlist.md) for the remaining items (tracked to GA). |
+| 3. Incremental landing | ⏳ **Largely shipped** | Many tool families have landed: SQL/PGQ property graphs (`run_pgq`, `create_property_graph`, …), in-server `REPACK` (`repack_table`), skip-scan advisor (`recommend_skip_scan_indexes`), `WAIT FOR LSN` read-your-writes (`wait_for_lsn`), online data-checksum + on-demand logical-replication toggles, DDL introspection (`get_role_ddl` / `get_database_ddl` / `get_tablespace_ddl` / `validate_check_constraint`), partition `MERGE` / `SPLIT`, lock + recovery stats, and async-I/O coverage. See the [tool index](../tools.md#tool-index-253-tools) for the shipped surface and [feature-shortlist.md](../feature-shortlist.md) for the remaining items (tracked to GA). |
 
 ## Phase 1 — what landed
 

docs/plans/pg_turboquant-integration.md

@@ -6,7 +6,7 @@
 > (`turboquant_approx_candidates`, `turboquant_rerank_candidates`,
 > `recommend_turboquant_query_knobs`), `maintain_turboquant_index`
 > (write), and `create_turboquant_index` / `reindex_turboquant_index`
-> (DDL) — see the [tool index](../tools.md#tool-index-252-tools). Kept
+> (DDL) — see the [tool index](../tools.md#tool-index-253-tools). Kept
 > for design rationale; no longer a live roadmap. Current gaps live in
 > [feature-shortlist.md](../feature-shortlist.md).
 

docs/plans/rag-efficiency-suite.md

@@ -6,7 +6,7 @@
 > `analyze_topk_stability`, `analyze_rerank_score_distribution`,
 > `analyze_rerank_ndcg`, `recommend_rerank_strategy`) plus the telemetry
 > capture/threshold tools — see the
-> [tool index](../tools.md#tool-index-252-tools). Kept for design
+> [tool index](../tools.md#tool-index-253-tools). Kept for design
 > rationale; no longer a live roadmap. Current gaps live in
 > [feature-shortlist.md](../feature-shortlist.md).
 

docs/token-efficiency.md

@@ -57,8 +57,10 @@ raw `EXPLAIN` JSON, which is mostly nested bookkeeping an agent must wade throug
 
 ## The break-even — the honest centerpiece
 
-MCPg's full surface is **252 tools**, and every tool definition costs context
-tokens on every turn. A "tokens saved" number that ignores that is dishonest,
+MCPg's full surface was **252 tools** at the time of this SF1 run (the committed
+JSON is that snapshot; the surface grows as tools are added), and every tool
+definition costs context tokens on every turn. A "tokens saved" number that
+ignores that is dishonest,
 and a reviewer would rightly pounce. So we measure it head-on — a bare
 `run_select` tool is **193** tokens, and MCPg's surface is far larger. With a
 mean per-call saving of ~2,750 tokens per database task, the surface is repaid

docs/tools.md

@@ -37,7 +37,7 @@ plumbing:
 | `MCPG_NL2SQL_PROVIDER` / `MCPG_NL2SQL_API_KEY` / `MCPG_NL2SQL_MODEL` / `MCPG_NL2SQL_BASE_URL` / `MCPG_NL2SQL_MAX_TOKENS` | `translate_nl_to_sql` provider config — 22 built-in providers + custom (`MCPG_NL2SQL_CUSTOM_PROVIDERS`). |
 
 <!-- BEGIN generated: tool-index (python tools/generate_doc_tables.py --tools) -->
-## Tool index (252 tools)
+## Tool index (253 tools)
 
 Grouped by feature area. The **Gate** column shows the capability
 each tool needs — plain `read` tools are available in every access
@@ -85,7 +85,7 @@ need `unrestricted` **plus** the matching `MCPG_ALLOW_*` opt-in (see
 | **PG 19 — stats status** | read | `get_pg19_stats_status` |
 | **WarehousePG (MPP)** | read | `get_warehousepg_status`, `list_distribution_policies`, `check_segment_health`, `describe_ao_table`, `list_resource_groups`, `analyze_mpp_query_plan`, `recommend_redistribute` |
 | **Logical replication pub/sub** | **DDL** | `create_publication`, `drop_publication`, `create_subscription`, `drop_subscription` |
-| **Write & DDL core** | **WRITE** / **DDL** | `run_write`, `run_maintenance`, `cancel_query`, `terminate_backend`, `run_ddl`, `enable_extension`, `dry_run_ddl` |
+| **Write & DDL core** | **WRITE** / **DDL** | `run_write`, `run_maintenance`, `clear_cache`, `cancel_query`, `terminate_backend`, `run_ddl`, `enable_extension`, `dry_run_ddl` |
 <!-- END generated: tool-index -->
 
 > The reference sections below describe the v0.4.0-era tools in