Skip to content

160-tool MCP server for real-time global intelligence from free public APIs: markets, liquidity, prediction markets, SEC filings, conflict, military, aircraft-cohort early warning, migration and border flows, cyber, climate, news and more. Dated observation history, 29 research prompts, cited briefs, geofences, SSE dashboard. MIT, no paid API keys.

Fix #4: fetcher stale-cache fallback now sets the documented _stale marker

Phoenix Agent (Marcs-Mac-Studio)f9cd7e333dbe
diff --git a/src/world_intel_mcp/cache.py b/src/world_intel_mcp/cache.py
index d465280..2ff9e90 100644
--- a/src/world_intel_mcp/cache.py
+++ b/src/world_intel_mcp/cache.py
@@ -60,7 +60,9 @@ class Cache:
created_at REAL NOT NULL
)
""")
- conn.execute("CREATE INDEX IF NOT EXISTS idx_cache_expires ON cache(expires_at)")
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_cache_expires ON cache(expires_at)"
+ )
conn.commit()
def _get_conn(self) -> sqlite3.Connection:
@@ -86,13 +88,26 @@ class Cache:
def get_stale(self, key: str) -> Any | None:
"""Get cached value even if expired (last-known-good fallback)."""
+ meta = self.get_stale_meta(key)
+ return meta[0] if meta is not None else None
+
+ def get_stale_meta(self, key: str) -> tuple[Any, float] | None:
+ """Get cached value even if expired, plus when it was originally written.
+
+ Returns ``(value, created_at)`` (``created_at`` is a Unix timestamp)
+ or ``None`` if the key doesn't exist at all. Callers that need to
+ report how old a stale fallback is — or preserve the original
+ fetch time instead of restamping "now" — use this instead of
+ ``get_stale()``.
+ """
conn = self._get_conn()
row = conn.execute(
- "SELECT value FROM cache WHERE key = ?", (key,)
+ "SELECT value, created_at FROM cache WHERE key = ?", (key,)
).fetchone()
if row is None:
return None
- return json.loads(row[0])
+ value, created_at = row
+ return json.loads(value), created_at
def set(self, key: str, value: Any, ttl_seconds: int) -> None:
"""Store a value with TTL in seconds.
@@ -121,7 +136,9 @@ class Cache:
"""Remove all expired entries. Returns count removed."""
try:
conn = self._get_conn()
- cursor = conn.execute("DELETE FROM cache WHERE expires_at < ?", (time.time(),))
+ cursor = conn.execute(
+ "DELETE FROM cache WHERE expires_at < ?", (time.time(),)
+ )
conn.commit()
return cursor.rowcount
except sqlite3.OperationalError as exc:
diff --git a/src/world_intel_mcp/fetcher.py b/src/world_intel_mcp/fetcher.py
index 2a1f869..6e22d24 100644
--- a/src/world_intel_mcp/fetcher.py
+++ b/src/world_intel_mcp/fetcher.py
@@ -151,7 +151,7 @@ class Fetcher:
except (httpx.HTTPStatusError, httpx.RequestError, Exception) as exc:
last_error = exc
if attempt < self.max_retries:
- wait = min(2 ** attempt, 30)
+ wait = min(2**attempt, 30)
logger.debug(
"Retry %d/%d for %s (%s), waiting %.1fs",
attempt + 1,
@@ -207,7 +207,7 @@ class Fetcher:
except (httpx.HTTPStatusError, httpx.RequestError, Exception) as exc:
last_error = exc
if attempt < self.max_retries:
- await asyncio.sleep(min(2 ** attempt, 30))
+ await asyncio.sleep(min(2**attempt, 30))
self.breaker.record_failure(source)
logger.warning("Text fetch failed for %s: %s", source, last_error)
@@ -225,11 +225,33 @@ class Fetcher:
return await self.get_text(url, source, cache_key, cache_ttl, timeout=timeout)
def _stale_fallback(self, cache_key: str, source: str) -> Any | None:
- """Return stale (expired) cached data as last-known-good fallback."""
- stale = self.cache.get_stale(cache_key)
- if stale is not None:
- logger.info("Serving stale cache for %s (key=%s)", source, cache_key)
- return stale
+ """Return stale (expired) cached data as last-known-good fallback.
+
+ Per the module docstring's promise, dict responses are marked with
+ ``_stale=True`` and ``_stale_age_seconds`` so a caller (dashboard,
+ MCP tool consumer) can tell arbitrarily old data from a fresh
+ response instead of receiving it silently. Non-dict responses
+ (raw text/XML, lists) can't carry an inline marker the same way,
+ so the circuit breaker's per-source stale-serve count is the
+ signal there.
+ """
+ meta = self.cache.get_stale_meta(cache_key)
+ if meta is None:
+ return None
+ value, created_at = meta
+ age_seconds = max(0.0, time.time() - created_at)
+ logger.info(
+ "Serving stale cache for %s (key=%s, age=%.0fs)",
+ source,
+ cache_key,
+ age_seconds,
+ )
+ if isinstance(value, dict):
+ value["_stale"] = True
+ value["_stale_age_seconds"] = round(age_seconds, 1)
+ else:
+ self.breaker.record_stale_serve(source)
+ return value
async def _source_throttle(self, source: str) -> None:
"""Enforce per-source rate limit from _SOURCE_RATE_LIMITS."""