mcp-cache 0.1.1__tar.gz

mcp_cache-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

mcp_cache-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Semantic release + PyPI publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout (full history for semantic-release)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+          persist-credentials: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        if: steps.release.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: dist
+          skip-existing: true

mcp_cache-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.db

mcp_cache-0.1.1/CHANGELOG.md

@@ -0,0 +1,64 @@
+# CHANGELOG
+
+
+## v0.1.1 (2026-06-04)
+
+### Bug Fixes
+
+- Cache None values correctly in TTL cache
+  ([`885b19f`](https://github.com/cmaurer/mcp-cache/commit/885b19f7667755d5c103381dc69713d592a75164))
+
+get_or_fetch and get() both returned None for a missing key and for a legitimately cached None
+  value, causing a false cache miss on the second call. Introduced a _MISSING sentinel so the two
+  cases are distinguished.
+
+Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
+
+
+## v0.1.0 (2026-06-04)
+
+### Chores
+
+- Adding missed files
+  ([`85840c4`](https://github.com/cmaurer/mcp-cache/commit/85840c404426d3cbdbc1a86a2938d8f1ad6963ed))
+
+### Continuous Integration
+
+- Add PyPI publish workflow on GitHub release
+  ([`954a8f3`](https://github.com/cmaurer/mcp-cache/commit/954a8f3f50fb2c8c288ce2a3d63d87092a75d993))
+
+Uses OIDC trusted publishing — no API token secret required.
+
+Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
+
+- Replace publish.yml with semantic-release workflow
+  ([`6368f0f`](https://github.com/cmaurer/mcp-cache/commit/6368f0f2cd69531d6e79c86e70b34e5164150d98))
+
+- release.yml: runs python-semantic-release on every push to main, bumps version in pyproject.toml,
+  creates GitHub release, and publishes to PyPI (requires PYPI_API_TOKEN secret) - pyproject.toml:
+  add [tool.semantic_release] config pointing at project.version for automated version bumps -
+  remove publish.yml (release.yml now owns PyPI publishing)
+
+Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
+
+### Features
+
+- Add MCP server for Claude Desktop
+  ([`91f2fe6`](https://github.com/cmaurer/mcp-cache/commit/91f2fe6116762067f0d149a21a1eeddb3b42d5da))
+
+- server.py: FastMCP server exposing 8 tools (cache_get/set/invalidate, cache_clear_expired,
+  timeseries_store/get/invalidate, cache_stats) - MCPCache: add public get() and set() methods -
+  pyproject.toml: mcp>=1.0 dependency + mcp-cache console script - README: Claude Desktop config and
+  tool reference table - tests: 4 new tests for get/set public methods (33 total)
+
+Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
+
+- Add unit tests, README, and GitHub Actions CI
+  ([`64857e1`](https://github.com/cmaurer/mcp-cache/commit/64857e1bad8b2af67f604cafae3eedc459214cc9))
+
+- 29 pytest-asyncio tests covering TTL cache, time series gap detection, invalidation, diagnostics,
+  and edge cases - README with installation, quick-start, and full API reference - CI workflow: test
+  matrix across Python 3.10–3.13 + build artifact job - pyproject.toml: dev extras (pytest,
+  pytest-asyncio) and pytest config
+
+Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

mcp_cache-0.1.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: mcp-cache
+Version: 0.1.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
+License: MIT
+Keywords: cache,llm,mcp,sqlite,time-series
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-cache
+
+A reusable SQLite-backed cache for MCP (Model Context Protocol) servers. Zero dependencies — pure Python stdlib.
+
+Two caching strategies:
+
+- **TTL cache** — store any JSON-serializable value for N seconds
+- **Time series cache** — store date-keyed observations and automatically fetch only missing date ranges
+
+## Installation
+
+```bash
+pip install mcp-cache
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/cmaurer/mcp-cache
+cd mcp-cache
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+### TTL cache
+
+```python
+from mcp_cache import MCPCache
+
+cache = MCPCache("~/.cache/myserver.db", default_ttl=300)
+
+async def get_quote(symbol: str) -> dict:
+    return await cache.get_or_fetch(
+        key=f"quote:{symbol}",
+        fetch_fn=lambda: api.fetch_quote(symbol),
+        ttl=60,  # override default; omit to use default_ttl
+    )
+```
+
+`fetch_fn` is called only on a cache miss or after the TTL expires. The result is stored as JSON and returned on subsequent calls within the TTL window.
+
+### Time series cache
+
+```python
+observations = await cache.get_timeseries(
+    series_id="T10YIE",
+    start_date="2020-01-01",
+    end_date="2024-12-31",
+    fetch_fn=lambda s, e: fred_api.get_series("T10YIE", s, e),
+)
+# Returns list of {"date": "YYYY-MM-DD", "value": float} dicts, newest first
+```
+
+On the first call the full range is fetched. On subsequent calls only gaps are fetched — requesting a wider range re-uses the already-cached portion and fetches only the missing edges.
+
+Custom key names are supported for APIs that don't use `"date"` / `"value"`:
+
+```python
+observations = await cache.get_timeseries(
+    series_id="prices",
+    start_date="2024-01-01",
+    end_date="2024-06-30",
+    fetch_fn=my_fetch,
+    date_key="timestamp",
+    value_key="close",
+)
+```
+
+## API reference
+
+### `MCPCache(db_path, default_ttl)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `db_path` | `str \| Path` | `"mcp_cache.db"` | Path to SQLite file. `~` is expanded. Parent dirs are created automatically. |
+| `default_ttl` | `int` | `300` | Default TTL in seconds for `get_or_fetch`. |
+
+---
+
+### TTL cache methods
+
+#### `await cache.get_or_fetch(key, fetch_fn, ttl=None)`
+
+Return the cached value for `key` if it exists and is still fresh. Otherwise call `fetch_fn()`, store the result, and return it.
+
+- `key` — cache key string
+- `fetch_fn` — async callable that returns a JSON-serializable value
+- `ttl` — per-call TTL override in seconds; uses `default_ttl` if omitted
+
+#### `await cache.invalidate(key)`
+
+Remove a specific entry from the TTL cache. No-op if the key does not exist.
+
+#### `await cache.clear_expired()`
+
+Delete all expired TTL entries. Returns the number of entries removed.
+
+---
+
+### Time series methods
+
+#### `await cache.get_timeseries(series_id, start_date, end_date, fetch_fn, date_key="date", value_key="value")`
+
+Return cached observations for `series_id` in `[start_date, end_date]`.
+
+- `series_id` — identifier for the series
+- `start_date`, `end_date` — `date` objects or ISO strings (`"YYYY-MM-DD"`)
+- `fetch_fn(start, end)` — async callable receiving ISO date strings; must return a list of dicts containing `date_key` and optionally `value_key`
+- `date_key`, `value_key` — key names in the returned dicts (default `"date"`, `"value"`)
+
+Returns a list of `{date_key: str, value_key: float | None}` dicts sorted **newest first**. `None` values are preserved — they represent real data points (e.g. non-trading days).
+
+#### `await cache.invalidate_series(series_id)`
+
+Remove all cached observations and range records for a series.
+
+---
+
+### Diagnostics
+
+#### `await cache.stats()`
+
+Returns a dict with cache counts:
+
+```python
+{
+    "ttl_cache":  {"total": 12, "fresh": 10, "expired": 2},
+    "timeseries": {"series": 3, "observations": 1500, "fetched_ranges": 6},
+    "db_path":    "/home/user/.cache/myserver.db",
+}
+```
+
+## Using with an MCP server
+
+```python
+from mcp_cache import MCPCache
+
+_cache = MCPCache("~/.cache/myserver.db")
+
+@server.tool()
+async def get_price_history(symbol: str, start: str, end: str) -> list[dict]:
+    return await _cache.get_timeseries(
+        series_id=symbol,
+        start_date=start,
+        end_date=end,
+        fetch_fn=lambda s, e: data_provider.fetch(symbol, s, e),
+    )
+```
+
+## Using with Claude Desktop
+
+Install the package:
+
+```bash
+pip install mcp-cache
+```
+
+Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cache": {
+      "command": "mcp-cache"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The following tools will be available:
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+| `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 |
+| `cache_stats()` | Return entry counts and db path |
+
+The cache database is stored at `~/.cache/mcp_cache.db`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mcp_cache-0.1.1/README.md

@@ -0,0 +1,197 @@
+# mcp-cache
+
+A reusable SQLite-backed cache for MCP (Model Context Protocol) servers. Zero dependencies — pure Python stdlib.
+
+Two caching strategies:
+
+- **TTL cache** — store any JSON-serializable value for N seconds
+- **Time series cache** — store date-keyed observations and automatically fetch only missing date ranges
+
+## Installation
+
+```bash
+pip install mcp-cache
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/cmaurer/mcp-cache
+cd mcp-cache
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+### TTL cache
+
+```python
+from mcp_cache import MCPCache
+
+cache = MCPCache("~/.cache/myserver.db", default_ttl=300)
+
+async def get_quote(symbol: str) -> dict:
+    return await cache.get_or_fetch(
+        key=f"quote:{symbol}",
+        fetch_fn=lambda: api.fetch_quote(symbol),
+        ttl=60,  # override default; omit to use default_ttl
+    )
+```
+
+`fetch_fn` is called only on a cache miss or after the TTL expires. The result is stored as JSON and returned on subsequent calls within the TTL window.
+
+### Time series cache
+
+```python
+observations = await cache.get_timeseries(
+    series_id="T10YIE",
+    start_date="2020-01-01",
+    end_date="2024-12-31",
+    fetch_fn=lambda s, e: fred_api.get_series("T10YIE", s, e),
+)
+# Returns list of {"date": "YYYY-MM-DD", "value": float} dicts, newest first
+```
+
+On the first call the full range is fetched. On subsequent calls only gaps are fetched — requesting a wider range re-uses the already-cached portion and fetches only the missing edges.
+
+Custom key names are supported for APIs that don't use `"date"` / `"value"`:
+
+```python
+observations = await cache.get_timeseries(
+    series_id="prices",
+    start_date="2024-01-01",
+    end_date="2024-06-30",
+    fetch_fn=my_fetch,
+    date_key="timestamp",
+    value_key="close",
+)
+```
+
+## API reference
+
+### `MCPCache(db_path, default_ttl)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `db_path` | `str \| Path` | `"mcp_cache.db"` | Path to SQLite file. `~` is expanded. Parent dirs are created automatically. |
+| `default_ttl` | `int` | `300` | Default TTL in seconds for `get_or_fetch`. |
+
+---
+
+### TTL cache methods
+
+#### `await cache.get_or_fetch(key, fetch_fn, ttl=None)`
+
+Return the cached value for `key` if it exists and is still fresh. Otherwise call `fetch_fn()`, store the result, and return it.
+
+- `key` — cache key string
+- `fetch_fn` — async callable that returns a JSON-serializable value
+- `ttl` — per-call TTL override in seconds; uses `default_ttl` if omitted
+
+#### `await cache.invalidate(key)`
+
+Remove a specific entry from the TTL cache. No-op if the key does not exist.
+
+#### `await cache.clear_expired()`
+
+Delete all expired TTL entries. Returns the number of entries removed.
+
+---
+
+### Time series methods
+
+#### `await cache.get_timeseries(series_id, start_date, end_date, fetch_fn, date_key="date", value_key="value")`
+
+Return cached observations for `series_id` in `[start_date, end_date]`.
+
+- `series_id` — identifier for the series
+- `start_date`, `end_date` — `date` objects or ISO strings (`"YYYY-MM-DD"`)
+- `fetch_fn(start, end)` — async callable receiving ISO date strings; must return a list of dicts containing `date_key` and optionally `value_key`
+- `date_key`, `value_key` — key names in the returned dicts (default `"date"`, `"value"`)
+
+Returns a list of `{date_key: str, value_key: float | None}` dicts sorted **newest first**. `None` values are preserved — they represent real data points (e.g. non-trading days).
+
+#### `await cache.invalidate_series(series_id)`
+
+Remove all cached observations and range records for a series.
+
+---
+
+### Diagnostics
+
+#### `await cache.stats()`
+
+Returns a dict with cache counts:
+
+```python
+{
+    "ttl_cache":  {"total": 12, "fresh": 10, "expired": 2},
+    "timeseries": {"series": 3, "observations": 1500, "fetched_ranges": 6},
+    "db_path":    "/home/user/.cache/myserver.db",
+}
+```
+
+## Using with an MCP server
+
+```python
+from mcp_cache import MCPCache
+
+_cache = MCPCache("~/.cache/myserver.db")
+
+@server.tool()
+async def get_price_history(symbol: str, start: str, end: str) -> list[dict]:
+    return await _cache.get_timeseries(
+        series_id=symbol,
+        start_date=start,
+        end_date=end,
+        fetch_fn=lambda s, e: data_provider.fetch(symbol, s, e),
+    )
+```
+
+## Using with Claude Desktop
+
+Install the package:
+
+```bash
+pip install mcp-cache
+```
+
+Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cache": {
+      "command": "mcp-cache"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The following tools will be available:
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+| `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 |
+| `cache_stats()` | Return entry counts and db path |
+
+The cache database is stored at `~/.cache/mcp_cache.db`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mcp_cache-0.1.1/mcp_cache/__init__.py

@@ -0,0 +1,11 @@
+"""
+mcp_cache — reusable SQLite-backed cache for MCP servers.
+
+Two strategies:
+  - TTL cache    : cache any JSON-serializable value for N seconds
+  - Time series  : store date-keyed observations and fetch only missing ranges
+"""
+
+from .cache import MCPCache
+
+__all__ = ["MCPCache"]

mcp_cache-0.1.1/mcp_cache/cache.py

@@ -0,0 +1,277 @@
+"""SQLite-backed cache with TTL and time series strategies."""
+
+import asyncio
+import json
+import sqlite3
+import time
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+
+_MISSING = object()  # sentinel distinguishing a cached None from a cache miss
+
+
+def _to_date_str(d: date | str) -> str:
+    if isinstance(d, str):
+        return d
+    return d.isoformat()
+
+
+class MCPCache:
+    """
+    Persistent SQLite cache for MCP server API responses.
+
+    Usage — TTL cache (any API response):
+        cache = MCPCache("~/.cache/myserver.db")
+        data = await cache.get_or_fetch("fred:T10YIE", fetch_fn, ttl=3600)
+
+    Usage — time series (date-keyed observations):
+        observations = await cache.get_timeseries(
+            series_id="T10YIE",
+            start_date="2020-01-01",
+            end_date="2024-12-31",
+            fetch_fn=lambda s, e: api.get_series("T10YIE", s, e),
+        )
+    """
+
+    def __init__(self, db_path: str | Path = "mcp_cache.db", default_ttl: int = 300):
+        self._db_path = str(Path(db_path).expanduser().resolve())
+        self._default_ttl = default_ttl
+        self._lock = asyncio.Lock()
+        self._init_db()
+
+    def _init_db(self) -> None:
+        Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS ttl_cache (
+                    key        TEXT PRIMARY KEY,
+                    value_json TEXT NOT NULL,
+                    cached_at  REAL NOT NULL,
+                    ttl        INTEGER NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS ts_observations (
+                    series_id TEXT NOT NULL,
+                    obs_date  TEXT NOT NULL,
+                    value     REAL,
+                    PRIMARY KEY (series_id, obs_date)
+                );
+
+                CREATE TABLE IF NOT EXISTS ts_ranges (
+                    series_id  TEXT NOT NULL,
+                    start_date TEXT NOT NULL,
+                    end_date   TEXT NOT NULL,
+                    fetched_at REAL NOT NULL
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_ts_ranges_series
+                    ON ts_ranges (series_id, start_date, end_date);
+            """)
+
+    # --- TTL cache ---
+
+    async def get_or_fetch(
+        self,
+        key: str,
+        fetch_fn: Callable[[], Awaitable[Any]],
+        ttl: int | None = None,
+    ) -> Any:
+        """Return cached value if fresh; otherwise call fetch_fn, cache, and return."""
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        cached = await asyncio.to_thread(self._ttl_get, key)
+        if cached is not _MISSING:
+            return cached
+        value = await fetch_fn()
+        await asyncio.to_thread(self._ttl_set, key, value, effective_ttl)
+        return value
+
+    def _ttl_get(self, key: str) -> Any:
+        with sqlite3.connect(self._db_path) as conn:
+            row = conn.execute(
+                "SELECT value_json, cached_at, ttl FROM ttl_cache WHERE key = ?", (key,)
+            ).fetchone()
+        if row is None:
+            return _MISSING
+        value_json, cached_at, ttl = row
+        if time.time() - cached_at > ttl:
+            return _MISSING
+        return json.loads(value_json)
+
+    def _ttl_set(self, key: str, value: Any, ttl: int) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute(
+                """
+                INSERT INTO ttl_cache (key, value_json, cached_at, ttl)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    value_json = excluded.value_json,
+                    cached_at  = excluded.cached_at,
+                    ttl        = excluded.ttl
+                """,
+                (key, json.dumps(value), time.time(), ttl),
+            )
+
+    async def get(self, key: str) -> Any | None:
+        """Return the cached value for key, or None if missing or expired."""
+        result = await asyncio.to_thread(self._ttl_get, key)
+        return None if result is _MISSING else result
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """Store value under key. Uses default_ttl if ttl is not specified."""
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        await asyncio.to_thread(self._ttl_set, key, value, effective_ttl)
+
+    async def invalidate(self, key: str) -> None:
+        """Remove a specific TTL cache entry."""
+        await asyncio.to_thread(self._ttl_delete, key)
+
+    def _ttl_delete(self, key: str) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute("DELETE FROM ttl_cache WHERE key = ?", (key,))
+
+    async def clear_expired(self) -> int:
+        """Delete all expired TTL entries. Returns the number removed."""
+        return await asyncio.to_thread(self._ttl_clear_expired)
+
+    def _ttl_clear_expired(self) -> int:
+        with sqlite3.connect(self._db_path) as conn:
+            cur = conn.execute(
+                "DELETE FROM ttl_cache WHERE (? - cached_at) > ttl", (time.time(),)
+            )
+            return cur.rowcount
+
+    # --- Time series cache ---
+
+    async def get_timeseries(
+        self,
+        series_id: str,
+        start_date: date | str,
+        end_date: date | str,
+        fetch_fn: Callable[[str, str], Awaitable[list[dict]]],
+        date_key: str = "date",
+        value_key: str = "value",
+    ) -> list[dict]:
+        """
+        Return observations for series_id in [start_date, end_date].
+
+        Computes which sub-ranges are not yet cached, calls fetch_fn(start, end)
+        for each gap (ISO date strings), stores new observations, and returns
+        the merged result sorted descending by date (newest first).
+
+        fetch_fn must return a list of dicts with date_key and value_key.
+        Null/None values are stored — they represent real data points.
+        """
+        start = _to_date_str(start_date)
+        end = _to_date_str(end_date)
+        gaps = await asyncio.to_thread(self._ts_find_gaps, series_id, start, end)
+        for gap_start, gap_end in gaps:
+            new_obs = await fetch_fn(gap_start, gap_end)
+            await asyncio.to_thread(
+                self._ts_store, series_id, new_obs, gap_start, gap_end, date_key, value_key
+            )
+        return await asyncio.to_thread(self._ts_query, series_id, start, end, date_key, value_key)
+
+    def _ts_find_gaps(self, series_id: str, start: str, end: str) -> list[tuple[str, str]]:
+        with sqlite3.connect(self._db_path) as conn:
+            rows = conn.execute(
+                """
+                SELECT start_date, end_date FROM ts_ranges
+                WHERE series_id = ? AND start_date <= ? AND end_date >= ?
+                ORDER BY start_date
+                """,
+                (series_id, end, start),
+            ).fetchall()
+
+        if not rows:
+            return [(start, end)]
+
+        merged: list[tuple[str, str]] = []
+        for r_start, r_end in rows:
+            if merged and r_start <= merged[-1][1]:
+                merged[-1] = (merged[-1][0], max(merged[-1][1], r_end))
+            else:
+                merged.append((r_start, r_end))
+
+        gaps: list[tuple[str, str]] = []
+        cursor = start
+        for covered_start, covered_end in merged:
+            if cursor < covered_start:
+                gaps.append((cursor, _prev_day(covered_start)))
+            cursor = max(cursor, _next_day(covered_end))
+        if cursor <= end:
+            gaps.append((cursor, end))
+        return gaps
+
+    def _ts_store(self, series_id, observations, range_start, range_end, date_key, value_key):
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executemany(
+                """
+                INSERT INTO ts_observations (series_id, obs_date, value)
+                VALUES (?, ?, ?)
+                ON CONFLICT(series_id, obs_date) DO UPDATE SET value = excluded.value
+                """,
+                [
+                    (series_id, str(obs[date_key]), obs.get(value_key))
+                    for obs in observations
+                    if date_key in obs
+                ],
+            )
+            conn.execute(
+                "INSERT INTO ts_ranges (series_id, start_date, end_date, fetched_at) VALUES (?, ?, ?, ?)",
+                (series_id, range_start, range_end, time.time()),
+            )
+
+    def _ts_query(self, series_id, start, end, date_key, value_key):
+        with sqlite3.connect(self._db_path) as conn:
+            rows = conn.execute(
+                """
+                SELECT obs_date, value FROM ts_observations
+                WHERE series_id = ? AND obs_date >= ? AND obs_date <= ?
+                ORDER BY obs_date DESC
+                """,
+                (series_id, start, end),
+            ).fetchall()
+        return [{date_key: row[0], value_key: row[1]} for row in rows]
+
+    async def invalidate_series(self, series_id: str) -> None:
+        """Remove all cached observations and range records for a series."""
+        await asyncio.to_thread(self._ts_delete_series, series_id)
+
+    def _ts_delete_series(self, series_id: str) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.execute("DELETE FROM ts_observations WHERE series_id = ?", (series_id,))
+            conn.execute("DELETE FROM ts_ranges WHERE series_id = ?", (series_id,))
+
+    # --- Diagnostics ---
+
+    async def stats(self) -> dict:
+        """Return counts and basic info about the cache contents."""
+        return await asyncio.to_thread(self._stats)
+
+    def _stats(self) -> dict:
+        now = time.time()
+        with sqlite3.connect(self._db_path) as conn:
+            ttl_total = conn.execute("SELECT COUNT(*) FROM ttl_cache").fetchone()[0]
+            ttl_fresh = conn.execute(
+                "SELECT COUNT(*) FROM ttl_cache WHERE (? - cached_at) <= ttl", (now,)
+            ).fetchone()[0]
+            ts_series = conn.execute(
+                "SELECT COUNT(DISTINCT series_id) FROM ts_observations"
+            ).fetchone()[0]
+            ts_obs = conn.execute("SELECT COUNT(*) FROM ts_observations").fetchone()[0]
+            ts_ranges = conn.execute("SELECT COUNT(*) FROM ts_ranges").fetchone()[0]
+        return {
+            "ttl_cache": {"total": ttl_total, "fresh": ttl_fresh, "expired": ttl_total - ttl_fresh},
+            "timeseries": {"series": ts_series, "observations": ts_obs, "fetched_ranges": ts_ranges},
+            "db_path": self._db_path,
+        }
+
+
+def _prev_day(iso: str) -> str:
+    return (date.fromisoformat(iso) - timedelta(days=1)).isoformat()
+
+
+def _next_day(iso: str) -> str:
+    return (date.fromisoformat(iso) + timedelta(days=1)).isoformat()

mcp_cache-0.1.1/mcp_cache/server.py

@@ -0,0 +1,105 @@
+"""Standalone MCP server exposing MCPCache as tools for Claude Desktop."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from .cache import MCPCache
+
+_DEFAULT_DB = Path.home() / ".cache" / "mcp_cache.db"
+
+app = FastMCP("mcp-cache")
+_cache = MCPCache(_DEFAULT_DB)
+
+
+@app.tool()
+async def cache_get(key: str) -> str:
+    """Return the cached JSON value for key, or null if missing or expired."""
+    value = await _cache.get(key)
+    return json.dumps(value)
+
+
+@app.tool()
+async def cache_set(key: str, value: str, ttl: int = 300) -> str:
+    """Store value (a JSON string) under key for ttl seconds."""
+    await _cache.set(key, json.loads(value), ttl)
+    return f"cached '{key}' for {ttl}s"
+
+
+@app.tool()
+async def cache_invalidate(key: str) -> str:
+    """Remove a specific TTL cache entry."""
+    await _cache.invalidate(key)
+    return f"invalidated '{key}'"
+
+
+@app.tool()
+async def cache_clear_expired() -> str:
+    """Delete all expired TTL entries and return the count removed."""
+    count = await _cache.clear_expired()
+    return f"removed {count} expired entries"
+
+
+@app.tool()
+async def timeseries_store(
+    series_id: str,
+    observations: str,
+    range_start: str,
+    range_end: str,
+    date_key: str = "date",
+    value_key: str = "value",
+) -> str:
+    """Store time series observations.
+
+    observations — JSON array of objects each containing date_key and value_key.
+    range_start / range_end — YYYY-MM-DD boundaries that were fetched (used for gap tracking).
+    """
+    obs = json.loads(observations)
+    await asyncio.to_thread(
+        _cache._ts_store, series_id, obs, range_start, range_end, date_key, value_key
+    )
+    return f"stored {len(obs)} observations for '{series_id}' [{range_start} – {range_end}]"
+
+
+@app.tool()
+async def timeseries_get(
+    series_id: str,
+    start_date: str,
+    end_date: str,
+    date_key: str = "date",
+    value_key: str = "value",
+) -> str:
+    """Return cached observations for series_id between start_date and end_date (YYYY-MM-DD).
+
+    Only returns already-cached data — does not call any external fetch.
+    Results are sorted newest-first.
+    """
+    rows = await asyncio.to_thread(
+        _cache._ts_query, series_id, start_date, end_date, date_key, value_key
+    )
+    return json.dumps(rows)
+
+
+@app.tool()
+async def timeseries_invalidate(series_id: str) -> str:
+    """Remove all cached observations and range records for series_id."""
+    await _cache.invalidate_series(series_id)
+    return f"invalidated series '{series_id}'"
+
+
+@app.tool()
+async def cache_stats() -> str:
+    """Return cache statistics (entry counts, series counts, db path) as JSON."""
+    return json.dumps(await _cache.stats(), indent=2)
+
+
+def main() -> None:
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_cache-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-cache"
+version = "0.1.1"
+description = "Reusable SQLite-backed cache for MCP servers — TTL and incremental time series strategies"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+keywords = ["mcp", "cache", "sqlite", "time-series", "llm"]
+dependencies = [
+    "mcp>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cmaurer/mcp-cache"
+Issues = "https://github.com/cmaurer/mcp-cache/issues"
+
+[project.scripts]
+mcp-cache = "mcp_cache.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+build_command = "pip install build && python -m build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_cache"]
+
+[tool.hatch.build]
+sources = ["src"]

mcp_cache-0.1.1/tests/test_cache.py

@@ -0,0 +1,325 @@
+"""Unit tests for MCPCache — TTL cache, time series, and diagnostics."""
+
+import sqlite3
+import time
+from datetime import date
+from unittest.mock import AsyncMock
+
+import pytest
+
+from mcp_cache import MCPCache
+from mcp_cache.cache import _next_day, _prev_day, _to_date_str
+
+
+# ── helper functions ────────────────────────────────────────────────────────
+
+
+def test_to_date_str_passthrough():
+    assert _to_date_str("2024-06-01") == "2024-06-01"
+
+
+def test_to_date_str_from_date_object():
+    assert _to_date_str(date(2024, 6, 1)) == "2024-06-01"
+
+
+def test_prev_day_mid_month():
+    assert _prev_day("2024-06-15") == "2024-06-14"
+
+
+def test_prev_day_month_boundary():
+    assert _prev_day("2024-06-01") == "2024-05-31"
+
+
+def test_next_day_mid_month():
+    assert _next_day("2024-06-15") == "2024-06-16"
+
+
+def test_next_day_year_boundary():
+    assert _next_day("2024-12-31") == "2025-01-01"
+
+
+# ── TTL cache ───────────────────────────────────────────────────────────────
+
+
+async def test_cache_miss_calls_fetch(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value={"v": 1})
+    result = await cache.get_or_fetch("k", fetch)
+    assert result == {"v": 1}
+    fetch.assert_awaited_once()
+
+
+async def test_cache_hit_skips_fetch(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value={"v": 1})
+    await cache.get_or_fetch("k", fetch)
+    result = await cache.get_or_fetch("k", fetch)
+    assert result == {"v": 1}
+    fetch.assert_awaited_once()
+
+
+async def test_cache_expired_entry_refetches(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    # Insert a stale entry directly so we don't need to sleep
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.execute(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            ("k", '"old"', time.time() - 9999, 300),
+        )
+    fetch = AsyncMock(return_value="fresh")
+    result = await cache.get_or_fetch("k", fetch)
+    assert result == "fresh"
+    fetch.assert_awaited_once()
+
+
+async def test_per_call_ttl_overrides_default(tmp_path):
+    cache = MCPCache(tmp_path / "test.db", default_ttl=3600)
+    # Insert an entry that is stale under ttl=1 but fresh under default 3600
+    with sqlite3.connect(cache._db_path) as conn:
+        conn.execute(
+            "INSERT INTO ttl_cache (key, value_json, cached_at, ttl) VALUES (?, ?, ?, ?)",
+            ("k", '"old"', time.time() - 5, 1),
+        )
+    fetch = AsyncMock(return_value="new")
+    result = await cache.get_or_fetch("k", fetch, ttl=1)
+    assert result == "new"
+    fetch.assert_awaited_once()
+
+
+async def test_invalidate_removes_entry(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value="data")
+    await cache.get_or_fetch("k", fetch)
+    await cache.invalidate("k")
+    await cache.get_or_fetch("k", fetch)
+    assert fetch.await_count == 2
+
+
+async def test_invalidate_nonexistent_key_is_noop(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.invalidate("no-such-key")  # must not raise
+
+
+async def test_clear_expired_removes_stale_entries(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 (?, ?, ?, ?)",
+            [
+                ("stale1", '"a"', old, 300),
+                ("stale2", '"b"', old, 300),
+                ("fresh", '"c"', time.time(), 3600),
+            ],
+        )
+    removed = await cache.clear_expired()
+    assert removed == 2
+
+
+async def test_ttl_cache_stores_various_json_types(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    cases = [("s", "hello"), ("i", 42), ("f", 3.14), ("l", [1, 2]), ("d", {"a": 1}), ("b", True)]
+    for key, value in cases:
+        result = await cache.get_or_fetch(key, AsyncMock(return_value=value))
+        assert result == value
+
+
+async def test_cached_none_is_not_treated_as_miss(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=None)
+    await cache.get_or_fetch("k", fetch)
+    await cache.get_or_fetch("k", fetch)
+    fetch.assert_awaited_once()  # second call must hit cache, not re-fetch
+
+
+async def test_get_returns_none_on_miss(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    assert await cache.get("missing") is None
+
+
+async def test_set_then_get_roundtrip(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.set("k", {"x": 1})
+    assert await cache.get("k") == {"x": 1}
+
+
+async def test_set_uses_default_ttl(tmp_path):
+    cache = MCPCache(tmp_path / "test.db", default_ttl=3600)
+    await cache.set("k", "v")
+    with sqlite3.connect(cache._db_path) as conn:
+        ttl = conn.execute("SELECT ttl FROM ttl_cache WHERE key = 'k'").fetchone()[0]
+    assert ttl == 3600
+
+
+async def test_set_explicit_ttl_overrides_default(tmp_path):
+    cache = MCPCache(tmp_path / "test.db", default_ttl=3600)
+    await cache.set("k", "v", ttl=60)
+    with sqlite3.connect(cache._db_path) as conn:
+        ttl = conn.execute("SELECT ttl FROM ttl_cache WHERE key = 'k'").fetchone()[0]
+    assert ttl == 60
+
+
+async def test_upsert_updates_on_re_store(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.get_or_fetch("k", AsyncMock(return_value="v1"))
+    await cache.invalidate("k")
+    result = await cache.get_or_fetch("k", AsyncMock(return_value="v2"))
+    assert result == "v2"
+
+
+# ── time series ─────────────────────────────────────────────────────────────
+
+
+def _obs(dates, value=1.0):
+    return [{"date": d, "value": value} for d in dates]
+
+
+async def test_timeseries_full_miss_calls_fetch(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02", "2024-01-03"]))
+    result = await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    fetch.assert_awaited_once_with("2024-01-01", "2024-01-03")
+    assert len(result) == 3
+
+
+async def test_timeseries_full_hit_skips_fetch(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02", "2024-01-03"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    fetch.assert_awaited_once()
+
+
+async def test_timeseries_partial_gap_fetches_only_missing(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02", "2024-01-03"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", f1)
+
+    f2 = AsyncMock(return_value=_obs(["2024-01-04", "2024-01-05"]))
+    result = await cache.get_timeseries("S1", "2024-01-01", "2024-01-05", f2)
+    f2.assert_awaited_once_with("2024-01-04", "2024-01-05")
+    assert len(result) == 5
+
+
+async def test_timeseries_gap_in_middle(tmp_path):
+    """Cached [Jan1-3] and [Jan7-9]; requesting [Jan1-9] should only fetch [Jan4-6]."""
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02", "2024-01-03"]))
+    f2 = AsyncMock(return_value=_obs(["2024-01-07", "2024-01-08", "2024-01-09"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", f1)
+    await cache.get_timeseries("S1", "2024-01-07", "2024-01-09", f2)
+
+    f3 = AsyncMock(return_value=_obs(["2024-01-04", "2024-01-05", "2024-01-06"]))
+    result = await cache.get_timeseries("S1", "2024-01-01", "2024-01-09", f3)
+    f3.assert_awaited_once_with("2024-01-04", "2024-01-06")
+    assert len(result) == 9
+
+
+async def test_timeseries_result_sorted_descending(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02", "2024-01-03"]))
+    result = await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    dates = [r["date"] for r in result]
+    assert dates == sorted(dates, reverse=True)
+
+
+async def test_timeseries_accepts_date_objects(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=_obs(["2024-06-01"]))
+    result = await cache.get_timeseries("S1", date(2024, 6, 1), date(2024, 6, 1), fetch)
+    assert len(result) == 1
+
+
+async def test_timeseries_custom_date_value_keys(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    obs = [{"t": "2024-01-01", "price": 99.5}]
+    fetch = AsyncMock(return_value=obs)
+    result = await cache.get_timeseries(
+        "S1", "2024-01-01", "2024-01-01", fetch, date_key="t", value_key="price"
+    )
+    assert result == [{"t": "2024-01-01", "price": 99.5}]
+
+
+async def test_timeseries_null_values_stored(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    obs = [{"date": "2024-01-01", "value": None}]
+    fetch = AsyncMock(return_value=obs)
+    result = await cache.get_timeseries("S1", "2024-01-01", "2024-01-01", fetch)
+    assert result[0]["value"] is None
+
+
+async def test_invalidate_series_clears_all_data(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    f1 = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-02", f1)
+    await cache.invalidate_series("S1")
+
+    f2 = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-02", f2)
+    f2.assert_awaited_once()
+
+
+async def test_invalidate_series_does_not_affect_other_series(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("S1", "2024-01-01", "2024-01-01", f1)
+    await cache.get_timeseries("S2", "2024-01-01", "2024-01-01", f2)
+    await cache.invalidate_series("S1")
+
+    f2_again = AsyncMock(return_value=_obs(["2024-01-01"]))
+    await cache.get_timeseries("S2", "2024-01-01", "2024-01-01", f2_again)
+    f2_again.assert_not_awaited()
+
+
+async def test_timeseries_empty_fetch_result(tmp_path):
+    """fetch_fn returning [] should store the range so it isn't re-fetched."""
+    cache = MCPCache(tmp_path / "test.db")
+    fetch = AsyncMock(return_value=[])
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-03", fetch)
+    fetch.assert_awaited_once()
+
+
+# ── stats ───────────────────────────────────────────────────────────────────
+
+
+async def test_stats_empty_cache(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    s = await cache.stats()
+    assert s["ttl_cache"] == {"total": 0, "fresh": 0, "expired": 0}
+    assert s["timeseries"] == {"series": 0, "observations": 0, "fetched_ranges": 0}
+    assert s["db_path"] == cache._db_path
+
+
+async def test_stats_reflects_cache_state(tmp_path):
+    cache = MCPCache(tmp_path / "test.db")
+    await cache.get_or_fetch("k1", AsyncMock(return_value=1))
+    await cache.get_or_fetch("k2", AsyncMock(return_value=2))
+    fetch = AsyncMock(return_value=_obs(["2024-01-01", "2024-01-02"]))
+    await cache.get_timeseries("S1", "2024-01-01", "2024-01-02", fetch)
+
+    s = await cache.stats()
+    assert s["ttl_cache"]["total"] == 2
+    assert s["ttl_cache"]["fresh"] == 2
+    assert s["ttl_cache"]["expired"] == 0
+    assert s["timeseries"]["observations"] == 2
+    assert s["timeseries"]["series"] == 1
+    assert s["timeseries"]["fetched_ranges"] == 1
+
+
+async def test_stats_counts_expired_correctly(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", '"x"', old, 300),
+                ("fresh", '"y"', time.time(), 3600),
+            ],
+        )
+    s = await cache.stats()
+    assert s["ttl_cache"]["total"] == 2
+    assert s["ttl_cache"]["fresh"] == 1
+    assert s["ttl_cache"]["expired"] == 1