mcp-cache 0.2.0__tar.gz → 0.2.1__tar.gz

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/CHANGELOG.md

@@ -1,6 +1,40 @@
 # CHANGELOG
 
 
+## v0.2.1 (2026-07-06)
+
+### Bug Fixes
+
+- Add cache key/series listing methods ([#2](https://github.com/cmaurer/mcp-cache/pull/2),
+  [`140bc30`](https://github.com/cmaurer/mcp-cache/commit/140bc30044f78f6ba36a9ac359234cd0fbb345d6))
+
+* docs: add design spec for cache key/series listing methods
+
+* docs: add implementation plan for cache key/series listing
+
+* feat: add MCPCache.list_keys() to list TTL cache keys
+
+Implement list_keys() method with optional prefix filtering and expired entry handling. Includes
+  _ttl_list_keys() helper and _like_prefix() escaping utility.
+
+* feat: add MCPCache.list_series() to list time series IDs
+
+Implement list_series() method with optional prefix filtering: - Public async method using
+  asyncio.to_thread pattern - Private sync helper _ts_list_series with SQL LIKE filtering - Reuses
+  _like_prefix helper from Task 1 - Results sorted alphabetically - Added 4 comprehensive tests
+  covering empty cache, deduplication, and prefix filtering
+
+Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
+
+* feat: expose cache_list_keys and timeseries_list_series MCP tools
+
+* docs: add CLAUDE.md with architecture and command reference
+
+---------
+
+Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
+
+
 ## v0.2.0 (2026-06-05)
 
 ### Features

mcp_cache-0.2.1/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`mcp-cache` is a reusable, zero-dependency (stdlib-only) SQLite-backed cache library for MCP (Model Context Protocol) servers. It ships as both an importable library (`from mcp_cache import MCPCache`) and a standalone MCP server (`mcp-cache` console script) for use directly in Claude Desktop. Requires Python 3.10+.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"                      # install package + test deps
+pytest                                        # run full test suite
+pytest tests/test_cache.py -v                 # verbose
+pytest tests/test_cache.py -k test_name -v    # run a single test
+pytest tests/test_cache.py -k list_keys -v    # run tests matching a substring
+```
+
+There is no linter/formatter configured in this repo — don't add one unprompted.
+
+Tests use `pytest-asyncio` with `asyncio_mode = "auto"` (`pyproject.toml`), so async test functions need **no** `@pytest.mark.asyncio` decorator.
+
+## Architecture
+
+The library is two files under `src/mcp_cache/`:
+
+- **`cache.py`** — `MCPCache`, the core SQLite-backed cache. No MCP/network dependency; pure stdlib (`sqlite3`, `asyncio`, `json`).
+- **`server.py`** — a `FastMCP` server (`app = FastMCP("mcp-cache")`) that instantiates one module-level `MCPCache` and wraps each of its methods as an `@app.tool()`. This is what `pip install`'s `mcp-cache` console script runs.
+
+New cache capability should almost always be added to `cache.py` first, then optionally exposed as a tool in `server.py` — not the other way around.
+
+### Two caching strategies, one consistent pattern
+
+`MCPCache` implements two independent strategies against one SQLite file, each with parallel method families:
+
+- **TTL cache** (`ttl_cache` table) — arbitrary string keys → JSON blob + expiry. Methods: `get_or_fetch`, `get`, `set`, `invalidate`, `clear_expired`, `list_keys`.
+- **Time series cache** (`ts_observations` + `ts_ranges` tables) — date-keyed observations per `series_id`, with gap-tracking so repeated queries only fetch missing date ranges. Methods: `get_timeseries`, `invalidate_series`, `list_series`.
+
+Every public method follows the same shape: an `async def` method does `await asyncio.to_thread(self._sync_helper, ...)`, and a private sync helper (`_ttl_*` / `_ts_*` prefix) does the actual SQLite work via `self._connect()`. All SQLite connections go through `self._connect()`, which applies `busy_timeout`. Follow this pattern exactly when adding methods — don't call SQLite directly from an `async def`.
+
+Any `LIKE`-based prefix filtering (`list_keys`, `list_series`) must go through the shared `_like_prefix()` helper (bottom of `cache.py`, escapes `%`/`_`/`\`) and bind the pattern as a parameter — never string-interpolate SQL.
+
+### Time series gap detection
+
+`get_timeseries` is the most complex piece: `_ts_find_gaps` merges overlapping/adjacent cached ranges from `ts_ranges` and computes the subset of `[start_date, end_date]` not yet covered, then only calls `fetch_fn` for those gaps before merging and returning the full requested range (sorted newest-first). When touching this logic, read `_ts_find_gaps` and its date-arithmetic helpers (`_prev_day`/`_next_day`) together — the gap math is easy to get off-by-one on.
+
+### The `_MISSING` sentinel
+
+TTL cache reads distinguish "no cached value" from "cached value is `None`" using the module-level `_MISSING` sentinel object (not `None`) as the miss marker internally. `get()` translates `_MISSING` back to `None` for the public API. Preserve this distinction in any code touching `_ttl_get`/`get_or_fetch`.
+
+### Configuration
+
+`server.py` reads three env vars at import time to configure the module-level cache instance: `MCP_CACHE_DB` (db file path, default `~/.cache/mcp_cache.db`), `MCP_CACHE_DEFAULT_TTL` (default `300`), `MCP_CACHE_BUSY_TIMEOUT` (default `5000` ms).
+
+### Testing conventions
+
+- Tests live in `tests/test_cache.py` only (no test file for `server.py`).
+- Use the `tmp_path` fixture for a fresh SQLite file per test — never share a db across tests.
+- To simulate expired/stale entries, insert rows directly via `sqlite3.connect(cache._db_path)` rather than sleeping.
+- Use `unittest.mock.AsyncMock` for `fetch_fn`/`fetch` callables; assert with `.assert_awaited_once()` / `.await_count`.
+- Tests hit a real SQLite file end-to-end — don't mock `MCPCache` internals.
+
+### Release process
+
+Versioning and `CHANGELOG.md` are fully automated by `python-semantic-release` on every push to `main` (`.github/workflows/release.yml`), driven by Conventional Commit prefixes (`feat:`, `fix:`, etc.) in commit messages. Do not hand-edit `CHANGELOG.md` or bump the version in `pyproject.toml` manually.

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-cache
-Version: 0.2.0
+Version: 0.2.1
 Summary: Reusable SQLite-backed cache for MCP servers — TTL and incremental time series strategies
 Project-URL: Homepage, https://github.com/cmaurer/mcp-cache
 Project-URL: Issues, https://github.com/cmaurer/mcp-cache/issues
@@ -113,6 +113,13 @@ Remove a specific entry from the TTL cache. No-op if the key does not exist.
 
 Delete all expired TTL entries. Returns the number of entries removed.
 
+#### `await cache.list_keys(prefix=None, include_expired=False)`
+
+Return TTL cache keys as a sorted list of strings.
+
+- `prefix` — only return keys starting with this string; `None` (default) returns all keys
+- `include_expired` — include expired entries; defaults to `False` (fresh keys only)
+
 ---
 
 ### Time series methods
@@ -132,6 +139,12 @@ Returns a list of `{date_key: str, value_key: float | None}` dicts sorted **newe
 
 Remove all cached observations and range records for a series.
 
+#### `await cache.list_series(prefix=None)`
+
+Return distinct time series IDs as a sorted list of strings.
+
+- `prefix` — only return series IDs starting with this string; `None` (default) returns all series
+
 ---
 
 ### Diagnostics
@@ -193,9 +206,11 @@ Restart Claude Desktop. The following tools will be available:
 | `cache_set(key, value, ttl)` | Store a JSON value for `ttl` seconds (default 300) |
 | `cache_invalidate(key)` | Remove a specific entry |
 | `cache_clear_expired()` | Delete all expired entries |
+| `cache_list_keys(prefix, include_expired)` | List TTL cache keys, optionally filtered by prefix |
 | `timeseries_store(series_id, observations, range_start, range_end)` | Store date-keyed observations |
 | `timeseries_get(series_id, start_date, end_date)` | Query cached observations |
 | `timeseries_invalidate(series_id)` | Clear all data for a series |
+| `timeseries_list_series(prefix)` | List time series IDs, optionally filtered by prefix |
 | `cache_stats()` | Return entry counts and db path |
 
 The cache database is stored at `~/.cache/mcp_cache.db`.

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/README.md

@@ -98,6 +98,13 @@ Remove a specific entry from the TTL cache. No-op if the key does not exist.
 
 Delete all expired TTL entries. Returns the number of entries removed.
 
+#### `await cache.list_keys(prefix=None, include_expired=False)`
+
+Return TTL cache keys as a sorted list of strings.
+
+- `prefix` — only return keys starting with this string; `None` (default) returns all keys
+- `include_expired` — include expired entries; defaults to `False` (fresh keys only)
+
 ---
 
 ### Time series methods
@@ -117,6 +124,12 @@ Returns a list of `{date_key: str, value_key: float | None}` dicts sorted **newe
 
 Remove all cached observations and range records for a series.
 
+#### `await cache.list_series(prefix=None)`
+
+Return distinct time series IDs as a sorted list of strings.
+
+- `prefix` — only return series IDs starting with this string; `None` (default) returns all series
+
 ---
 
 ### Diagnostics
@@ -178,9 +191,11 @@ Restart Claude Desktop. The following tools will be available:
 | `cache_set(key, value, ttl)` | Store a JSON value for `ttl` seconds (default 300) |
 | `cache_invalidate(key)` | Remove a specific entry |
 | `cache_clear_expired()` | Delete all expired entries |
+| `cache_list_keys(prefix, include_expired)` | List TTL cache keys, optionally filtered by prefix |
 | `timeseries_store(series_id, observations, range_start, range_end)` | Store date-keyed observations |
 | `timeseries_get(series_id, start_date, end_date)` | Query cached observations |
 | `timeseries_invalidate(series_id)` | Clear all data for a series |
+| `timeseries_list_series(prefix)` | List time series IDs, optionally filtered by prefix |
 | `cache_stats()` | Return entry counts and db path |
 
 The cache database is stored at `~/.cache/mcp_cache.db`.

mcp_cache-0.2.1/docs/superpowers/plans/2026-07-05-list-cache-keys.md

@@ -0,0 +1,350 @@
+# List Cache Keys Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add the ability to list what's currently cached — TTL cache keys and time series IDs — with optional prefix filtering.
+
+**Architecture:** Two new async methods on `MCPCache` (`list_keys`, `list_series`), each following the existing sync-helper + `asyncio.to_thread` pattern already used by every other method in `cache.py`. Two new MCP tools in `server.py` expose them to Claude Desktop, mirroring the existing tool style. README gets matching API reference and tool table entries.
+
+**Tech Stack:** Python 3.10+, sqlite3 (stdlib), pytest + pytest-asyncio (`asyncio_mode = "auto"`, no decorator needed).
+
+## Global Constraints
+
+- Follow the existing `cache.py` pattern: a public `async def` method that does `await asyncio.to_thread(self._sync_helper, ...)`, plus a private sync helper that opens a connection via `self._connect()`.
+- `prefix` filtering uses a bound SQL parameter (`LIKE ? `), never string interpolation.
+- `list_keys` excludes expired entries by default; `include_expired=True` includes them.
+- Both methods return results sorted alphabetically.
+- Tests go in the existing `tests/test_cache.py`, using the same style as neighboring tests (`tmp_path` fixture, direct `sqlite3.connect` for pre-seeding rows, no custom fixtures/classes).
+
+---
+
+### Task 1: `MCPCache.list_keys()` — TTL cache key listing
+
+**Files:**
+- Modify: `src/mcp_cache/cache.py` (add method under the `# --- TTL cache ---` section, after `clear_expired`/`_ttl_clear_expired`, i.e. after line 153)
+- Test: `tests/test_cache.py` (add tests under the `# ── TTL cache` section, after `test_upsert_updates_on_re_store`, i.e. after line 167)
+
+**Interfaces:**
+- Produces: `async def list_keys(self, prefix: str | None = None, include_expired: bool = False) -> list[str]`
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_cache.py` after `test_upsert_updates_on_re_store` (line 167):
+
+```python
+async def test_list_keys_empty_cache(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    assert await cache.list_keys() == []
+
+
+async def test_list_keys_returns_fresh_keys_sorted(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("zebra", "v")
+    await cache.set("apple", "v")
+    assert await cache.list_keys() == ["apple", "zebra"]
+
+
+async def test_list_keys_excludes_expired_by_default(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    old = time.time() - 9999
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.executemany(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            [
+                ("stale", '"a"', old, 300),
+                ("fresh", '"b"', time.time(), 3600),
+            ],
+        )
+    assert await cache.list_keys() == ["fresh"]
+
+
+async def test_list_keys_include_expired_true(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    old = time.time() - 9999
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.executemany(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            [
+                ("stale", '"a"', old, 300),
+                ("fresh", '"b"', time.time(), 3600),
+            ],
+        )
+    assert await cache.list_keys(include_expired=True) == ["fresh", "stale"]
+
+
+async def test_list_keys_prefix_filter(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("fred:T10YIE", "v")
+    await cache.set("fred:DGS10", "v")
+    await cache.set("other:key", "v")
+    assert await cache.list_keys(prefix="fred:") == ["fred:DGS10", "fred:T10YIE"]
+
+
+async def test_list_keys_prefix_no_match(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("fred:T10YIE", "v")
+    assert await cache.list_keys(prefix="nomatch:") == []
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_cache.py -k list_keys -v`
+Expected: FAIL with `AttributeError: 'MCPCache' object has no attribute 'list_keys'`
+
+- [ ] **Step 3: Implement `list_keys` and `_ttl_list_keys`**
+
+In `src/mcp_cache/cache.py`, add after `_ttl_clear_expired` (after line 153, before the `# --- Time series cache ---` comment on line 155):
+
+```python
+    async def list_keys(self, prefix: str | None = None, include_expired: bool = False) -> list[str]:
+        """Return TTL cache keys, optionally filtered by prefix.
+
+        Excludes expired entries unless include_expired=True.
+        """
+        return await asyncio.to_thread(self._ttl_list_keys, prefix, include_expired)
+
+    def _ttl_list_keys(self, prefix: str | None, include_expired: bool) -> list[str]:
+        query = "SELECT key FROM ttl_cache"
+        conditions = []
+        params: list[Any] = []
+        if not include_expired:
+            conditions.append("(? - cached_at) <= ttl")
+            params.insert(0, time.time())
+        if prefix:
+            conditions.append("key LIKE ? ESCAPE '\\'")
+            params.append(_like_prefix(prefix))
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+        query += " ORDER BY key"
+        with self._connect() as conn:
+            rows = conn.execute(query, params).fetchall()
+        return [row[0] for row in rows]
+```
+
+Add the `_like_prefix` helper near the other module-level helpers (`_prev_day`/`_next_day` at the bottom of the file, after line 288):
+
+```python
+def _like_prefix(prefix: str) -> str:
+    escaped = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+    return escaped + "%"
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_cache.py -k list_keys -v`
+Expected: PASS (all 5 tests)
+
+- [ ] **Step 5: Run the full test suite**
+
+Run: `pytest tests/test_cache.py -v`
+Expected: PASS (all tests, no regressions)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/mcp_cache/cache.py tests/test_cache.py
+git commit -m "feat: add MCPCache.list_keys() to list TTL cache keys"
+```
+
+---
+
+### Task 2: `MCPCache.list_series()` — time series ID listing
+
+**Files:**
+- Modify: `src/mcp_cache/cache.py` (add method under `# --- Time series cache ---`, after `_ts_delete_series`, i.e. after what will now be line ~275 once Task 1's addition shifts line numbers — insert directly after the `_ts_delete_series` method and before the `# --- Diagnostics ---` comment)
+- Test: `tests/test_cache.py` (add tests under the `# ── time series` section, after `test_timeseries_empty_fetch_result`)
+
+**Interfaces:**
+- Consumes: none from Task 1 (independent method, same file)
+- Produces: `async def list_series(self, prefix: str | None = None) -> list[str]`
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_cache.py` after `test_timeseries_empty_fetch_result` (originally line 281, before the `# ── constructor parameters` section):
+
+```python
+async def test_list_series_empty_cache(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    assert await cache.list_series() == []
+
+
+async def test_list_series_returns_distinct_sorted(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    await cache.get_timeseries("zebra", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("apple", "2024-01-01", "2024-01-01", f2)
+    assert await cache.list_series() == ["apple", "zebra"]
+
+
+async def test_list_series_dedups_across_ranges(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-02-01"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("S1", "2024-02-01", "2024-02-01", f2)
+    assert await cache.list_series() == ["S1"]
+
+
+async def test_list_series_prefix_filter(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    await cache.get_timeseries("fred:T10YIE", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("other:S1", "2024-01-01", "2024-01-01", f2)
+    assert await cache.list_series(prefix="fred:") == ["fred:T10YIE"]
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_cache.py -k list_series -v`
+Expected: FAIL with `AttributeError: 'MCPCache' object has no attribute 'list_series'`
+
+- [ ] **Step 3: Implement `list_series` and `_ts_list_series`**
+
+In `src/mcp_cache/cache.py`, add after `_ts_delete_series` (right before the `# --- Diagnostics ---` comment):
+
+```python
+    async def list_series(self, prefix: str | None = None) -> list[str]:
+        """Return distinct time series IDs, optionally filtered by prefix."""
+        return await asyncio.to_thread(self._ts_list_series, prefix)
+
+    def _ts_list_series(self, prefix: str | None) -> list[str]:
+        query = "SELECT DISTINCT series_id FROM ts_observations"
+        params: list[Any] = []
+        if prefix:
+            query += " WHERE series_id LIKE ? ESCAPE '\\'"
+            params.append(_like_prefix(prefix))
+        query += " ORDER BY series_id"
+        with self._connect() as conn:
+            rows = conn.execute(query, params).fetchall()
+        return [row[0] for row in rows]
+```
+
+(`_like_prefix` was already added in Task 1 — reuse it, don't redefine it.)
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_cache.py -k list_series -v`
+Expected: PASS (all 4 tests)
+
+- [ ] **Step 5: Run the full test suite**
+
+Run: `pytest tests/test_cache.py -v`
+Expected: PASS (all tests, no regressions)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/mcp_cache/cache.py tests/test_cache.py
+git commit -m "feat: add MCPCache.list_series() to list time series IDs"
+```
+
+---
+
+### Task 3: Expose MCP tools and update README
+
+**Files:**
+- Modify: `src/mcp_cache/server.py` (add two `@app.tool()` functions after `cache_clear_expired`, i.e. after line 48, and after `timeseries_invalidate`, i.e. after line 95)
+- Modify: `README.md` (add API reference entries and tool table rows)
+
+**Interfaces:**
+- Consumes: `MCPCache.list_keys(prefix, include_expired)` from Task 1, `MCPCache.list_series(prefix)` from Task 2
+- Produces: MCP tools `cache_list_keys`, `timeseries_list_series` (no other task depends on these)
+
+- [ ] **Step 1: Add `cache_list_keys` tool**
+
+In `src/mcp_cache/server.py`, add after `cache_clear_expired` (after line 48, before the `timeseries_store` tool):
+
+```python
+@app.tool()
+async def cache_list_keys(prefix: str = "", include_expired: bool = False) -> str:
+    """List TTL cache keys, optionally filtered by prefix."""
+    keys = await _cache.list_keys(prefix or None, include_expired)
+    return json.dumps(keys)
+```
+
+- [ ] **Step 2: Add `timeseries_list_series` tool**
+
+In `src/mcp_cache/server.py`, add after `timeseries_invalidate` (after line 95, before the `cache_stats` tool):
+
+```python
+@app.tool()
+async def timeseries_list_series(prefix: str = "") -> str:
+    """List time series IDs, optionally filtered by prefix."""
+    series = await _cache.list_series(prefix or None)
+    return json.dumps(series)
+```
+
+- [ ] **Step 3: Verify the server imports and tools register**
+
+Run: `python -c "from mcp_cache.server import app; print(sorted(t for t in __import__('asyncio').run(app.list_tools())))" 2>&1 | tail -5`
+
+If that's awkward to run directly, instead run:
+
+Run: `python -c "import mcp_cache.server"`
+Expected: no import errors (exit code 0)
+
+- [ ] **Step 4: Update README API reference**
+
+In `README.md`, add after the `#### await cache.clear_expired()` section (after line 99, before the `---` on line 101):
+
+```markdown
+
+#### `await cache.list_keys(prefix=None, include_expired=False)`
+
+Return TTL cache keys as a sorted list of strings.
+
+- `prefix` — only return keys starting with this string; `None` (default) returns all keys
+- `include_expired` — include expired entries; defaults to `False` (fresh keys only)
+```
+
+Add after the `#### await cache.invalidate_series(series_id)` section (after line 118, before the `---` on line 120):
+
+```markdown
+
+#### `await cache.list_series(prefix=None)`
+
+Return distinct time series IDs as a sorted list of strings.
+
+- `prefix` — only return series IDs starting with this string; `None` (default) returns all series
+```
+
+- [ ] **Step 5: Update README MCP tool table**
+
+In `README.md`, update the tool table (around line 176-184) to add two rows — after `cache_clear_expired()` and after `timeseries_invalidate(series_id)`:
+
+```markdown
+| `cache_get(key)` | Return a cached value, or `null` if missing/expired |
+| `cache_set(key, value, ttl)` | Store a JSON value for `ttl` seconds (default 300) |
+| `cache_invalidate(key)` | Remove a specific entry |
+| `cache_clear_expired()` | Delete all expired entries |
+| `cache_list_keys(prefix, include_expired)` | List TTL cache keys, optionally filtered by prefix |
+| `timeseries_store(series_id, observations, range_start, range_end)` | Store date-keyed observations |
+| `timeseries_get(series_id, start_date, end_date)` | Query cached observations |
+| `timeseries_invalidate(series_id)` | Clear all data for a series |
+| `timeseries_list_series(prefix)` | List time series IDs, optionally filtered by prefix |
+| `cache_stats()` | Return entry counts and db path |
+```
+
+This replaces the existing 8-row table with the 10-row version above (same rows, two new ones inserted in place).
+
+- [ ] **Step 6: Run the full test suite**
+
+Run: `pytest -v`
+Expected: PASS (all tests, no regressions)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/mcp_cache/server.py README.md
+git commit -m "feat: expose cache_list_keys and timeseries_list_series MCP tools"
+```
+
+---
+
+## Self-Review Notes
+
+- **Spec coverage:** `list_keys` (Task 1) ✓, `list_series` (Task 2) ✓, prefix filtering both (Tasks 1 & 2) ✓, include_expired (Task 1) ✓, MCP tool exposure (Task 3) ✓, tests per spec's testing plan (Tasks 1 & 2) ✓. Spec's "out of scope" items (glob matching, pagination, combined method) are correctly omitted.
+- **Type consistency:** `list_keys(prefix: str | None, include_expired: bool) -> list[str]` and `list_series(prefix: str | None) -> list[str]` match between the spec, task interfaces, and implementation code in every task.
+- **Shared helper:** `_like_prefix` is defined once in Task 1 and reused (not redefined) in Task 2 — flagged explicitly in Task 2 to avoid a duplicate-definition mistake.

mcp_cache-0.2.1/docs/superpowers/specs/2026-07-05-list-cache-keys-design.md

@@ -0,0 +1,70 @@
+# List Cache Keys — Design
+
+## Problem
+
+`MCPCache` has no way to enumerate what's currently cached. Callers can `get`/`set` individual keys or `get_timeseries` individual series, but there's no introspection method to list what keys/series exist — useful for debugging, cache management tooling, and the MCP server's diagnostic surface (alongside `stats()`).
+
+## Approach
+
+Add two separate listing methods, one per existing store, following the codebase's existing convention of splitting TTL-cache methods from time-series methods (`get`/`set`/`invalidate`/`clear_expired` vs. `get_timeseries`/`invalidate_series`). A single overloaded method with a `store` selector was considered but rejected — it would need different parameters per store (`include_expired` only makes sense for TTL) and existing code doesn't unify these stores elsewhere.
+
+## API
+
+```python
+async def list_keys(self, prefix: str | None = None, include_expired: bool = False) -> list[str]:
+    """Return TTL cache keys, optionally filtered by prefix. Fresh only unless include_expired=True."""
+
+async def list_series(self, prefix: str | None = None) -> list[str]:
+    """Return distinct time series series_ids, optionally filtered by prefix."""
+```
+
+- `list_keys` queries `ttl_cache`, excluding expired rows (`(now - cached_at) > ttl`) unless `include_expired=True`.
+- `list_series` queries `SELECT DISTINCT series_id FROM ts_observations`.
+- Both accept `prefix`: when set, filter with a bound `LIKE 'prefix%'` parameter (plain prefix match, no glob/regex). `prefix=None` (or omitted) returns everything.
+- Both follow the existing sync-helper + `asyncio.to_thread` pattern used throughout `cache.py` (e.g. `_ttl_get`, `_ts_query`).
+- Results are returned sorted alphabetically for deterministic output.
+
+## Edge cases
+
+- Empty cache/store → return `[]`, not an error.
+- `prefix=""` is treated the same as `prefix=None` (no filtering) since `LIKE '%'` matches everything anyway — no special-casing needed.
+- Prefix is passed as a bound SQL parameter, not string-interpolated — no injection risk.
+
+## MCP server tool exposure
+
+Add two tools in `server.py`, mirroring the existing `cache_stats` tool:
+
+```python
+@app.tool()
+async def cache_list_keys(prefix: str = "", include_expired: bool = False) -> str:
+    """List TTL cache keys, optionally filtered by prefix."""
+    keys = await _cache.list_keys(prefix or None, include_expired)
+    return json.dumps(keys)
+
+@app.tool()
+async def timeseries_list_series(prefix: str = "") -> str:
+    """List time series IDs, optionally filtered by prefix."""
+    series = await _cache.list_series(prefix or None)
+    return json.dumps(series)
+```
+
+## Testing
+
+Add to `tests/test_cache.py`, following existing conventions (real SQLite via `MCPCache`, `pytest.mark.asyncio`):
+
+- `list_keys` returns `[]` on empty cache
+- `list_keys` returns all fresh keys, alphabetically sorted
+- `list_keys` excludes expired keys by default
+- `list_keys(include_expired=True)` includes expired keys
+- `list_keys(prefix=...)` filters correctly (matching and non-matching cases)
+- `list_series` returns `[]` when no series cached
+- `list_series` returns distinct series_ids (dedup across multiple date ranges for the same series)
+- `list_series(prefix=...)` filters correctly
+
+No test file exists for `server.py` currently, so no server-level tests are added — consistent with existing coverage.
+
+## Out of scope
+
+- Glob/regex pattern matching (prefix-only, per YAGNI)
+- Pagination (no evidence of large enough key counts to need it)
+- Combined "list everything" convenience method (caller can call both if needed)

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/mcp_cache/cache.py

@@ -152,6 +152,30 @@ class MCPCache:
             )
             return cur.rowcount
 
+    async def list_keys(self, prefix: str | None = None, include_expired: bool = False) -> list[str]:
+        """Return TTL cache keys, optionally filtered by prefix.
+
+        Excludes expired entries unless include_expired=True.
+        """
+        return await asyncio.to_thread(self._ttl_list_keys, prefix, include_expired)
+
+    def _ttl_list_keys(self, prefix: str | None, include_expired: bool) -> list[str]:
+        query = "SELECT key FROM ttl_cache"
+        conditions = []
+        params: list[Any] = []
+        if not include_expired:
+            conditions.append("(? - cached_at) <= ttl")
+            params.insert(0, time.time())
+        if prefix:
+            conditions.append("key LIKE ? ESCAPE '\\'")
+            params.append(_like_prefix(prefix))
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+        query += " ORDER BY key"
+        with self._connect() as conn:
+            rows = conn.execute(query, params).fetchall()
+        return [row[0] for row in rows]
+
     # --- Time series cache ---
 
     async def get_timeseries(
@@ -254,6 +278,21 @@ class MCPCache:
             conn.execute("DELETE FROM ts_observations WHERE series_id = ?", (series_id,))
             conn.execute("DELETE FROM ts_ranges WHERE series_id = ?", (series_id,))
 
+    async def list_series(self, prefix: str | None = None) -> list[str]:
+        """Return distinct time series IDs, optionally filtered by prefix."""
+        return await asyncio.to_thread(self._ts_list_series, prefix)
+
+    def _ts_list_series(self, prefix: str | None) -> list[str]:
+        query = "SELECT DISTINCT series_id FROM ts_observations"
+        params: list[Any] = []
+        if prefix:
+            query += " WHERE series_id LIKE ? ESCAPE '\\'"
+            params.append(_like_prefix(prefix))
+        query += " ORDER BY series_id"
+        with self._connect() as conn:
+            rows = conn.execute(query, params).fetchall()
+        return [row[0] for row in rows]
+
     # --- Diagnostics ---
 
     async def stats(self) -> dict:
@@ -285,3 +324,8 @@ def _prev_day(iso: str) -> str:
 
 def _next_day(iso: str) -> str:
     return (date.fromisoformat(iso) + timedelta(days=1)).isoformat()
+
+
+def _like_prefix(prefix: str) -> str:
+    escaped = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+    return escaped + "%"

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/mcp_cache/server.py

@@ -48,6 +48,13 @@ async def cache_clear_expired() -> str:
     return f"removed {count} expired entries"
 
 
+@app.tool()
+async def cache_list_keys(prefix: str = "", include_expired: bool = False) -> str:
+    """List TTL cache keys, optionally filtered by prefix."""
+    keys = await _cache.list_keys(prefix or None, include_expired)
+    return json.dumps(keys)
+
+
 @app.tool()
 async def timeseries_store(
     series_id: str,
@@ -95,6 +102,13 @@ async def timeseries_invalidate(series_id: str) -> str:
     return f"invalidated series '{series_id}'"
 
 
+@app.tool()
+async def timeseries_list_series(prefix: str = "") -> str:
+    """List time series IDs, optionally filtered by prefix."""
+    series = await _cache.list_series(prefix or None)
+    return json.dumps(series)
+
+
 @app.tool()
 async def cache_stats() -> str:
     """Return cache statistics (entry counts, series counts, db path) as JSON."""

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-cache"
-version = "0.2.0"
+version = "0.2.1"
 description = "Reusable SQLite-backed cache for MCP servers — TTL and incremental time series strategies"
 readme = "README.md"
 requires-python = ">=3.10"

{mcp_cache-0.2.0 → mcp_cache-0.2.1}/tests/test_cache.py

@@ -167,6 +167,60 @@ async def test_upsert_updates_on_re_store(tmp_path):
     assert result == "v2"
 
 
+async def test_list_keys_empty_cache(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    assert await cache.list_keys() == []
+
+
+async def test_list_keys_returns_fresh_keys_sorted(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("zebra", "v")
+    await cache.set("apple", "v")
+    assert await cache.list_keys() == ["apple", "zebra"]
+
+
+async def test_list_keys_excludes_expired_by_default(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    old = time.time() - 9999
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.executemany(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            [
+                ("stale", '"a"', old, 300),
+                ("fresh", '"b"', time.time(), 3600),
+            ],
+        )
+    assert await cache.list_keys() == ["fresh"]
+
+
+async def test_list_keys_include_expired_true(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    old = time.time() - 9999
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.executemany(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            [
+                ("stale", '"a"', old, 300),
+                ("fresh", '"b"', time.time(), 3600),
+            ],
+        )
+    assert await cache.list_keys(include_expired=True) == ["fresh", "stale"]
+
+
+async def test_list_keys_prefix_filter(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("fred:T10YIE", "v")
+    await cache.set("fred:DGS10", "v")
+    await cache.set("other:key", "v")
+    assert await cache.list_keys(prefix="fred:") == ["fred:DGS10", "fred:T10YIE"]
+
+
+async def test_list_keys_prefix_no_match(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("fred:T10YIE", "v")
+    assert await cache.list_keys(prefix="nomatch:") == []
+
+
 # ── time series ─────────────────────────────────────────────────────────────
 
 
@@ -281,6 +335,38 @@ async def test_timeseries_empty_fetch_result(tmp_path):
     fetch.assert_awaited_once()
 
 
+async def test_list_series_empty_cache(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    assert await cache.list_series() == []
+
+
+async def test_list_series_returns_distinct_sorted(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    await cache.get_timeseries("zebra", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("apple", "2024-01-01", "2024-01-01", f2)
+    assert await cache.list_series() == ["apple", "zebra"]
+
+
+async def test_list_series_dedups_across_ranges(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-02-01"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("S1", "2024-02-01", "2024-02-01", f2)
+    assert await cache.list_series() == ["S1"]
+
+
+async def test_list_series_prefix_filter(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    f2 = AsyncMock(return_value=_obs(["2024-01-01"]))
+    await cache.get_timeseries("fred:T10YIE", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("other:S1", "2024-01-01", "2024-01-01", f2)
+    assert await cache.list_series(prefix="fred:") == ["fred:T10YIE"]
+
+
 # ── constructor parameters ──────────────────────────────────────────────────