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.

Source health: name every source whose last call failed

Phoenix Agent (mac-studio)5dee5fc6df7c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a8c815e..64cec29 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -316,6 +316,14 @@ source here, and no proxy is substituted for any of these measures.
null, `index_is_lower_bound` marks a total that counts missing parts as
zero, and with nothing measured the index is null and the risk level
`unknown`. `ucdp_floor_basis` says the floor comes from a static table.
+- The source-health verdict counted only open or half-open circuit
+ breakers, and a breaker opens after three failures in a row, so after
+ one or two failed calls it read "0 with an open or half-open circuit
+ breaker" while the source was down. New `failing_sources` lists every
+ source whose last call failed, the verdict reads "N sources called by
+ this process, M whose last call failed, K with an open or half-open
+ circuit breaker" (plus how many served a stale copy), and the scope
+ notes explain `failures`, `total_successes` and `total_failures`.
- `intel_internet_outages` returned an empty list with no marker when
neither Cloudflare Radar nor IODA answered; it now carries `error`,
`degraded` and reason `outages_unavailable`.
diff --git a/README.md b/README.md
index 109489b..9491118 100644
--- a/README.md
+++ b/README.md
@@ -193,7 +193,7 @@ cannot support, before it calls anything.
| Resource | Type | What it holds |
|----------|------|---------------|
| `intel://guide` | Markdown | How to ask a strong question (name the period, the comparison, the measure and the place), what an answer contains, what this server will not do, the worked prompts, and every tool grouped by domain. Built from the live tool registry on each read, so it always matches `tools/list`. |
-| `intel://guide/source-health` | JSON | Open circuit breakers, stale serves, cache freshness per source prefix, and which keyed sources have their variables set (names only, never values). Reading it starts no fetch. Breaker state covers this server process only; the collector keeps its own. A `verdict` line says when there is nothing to go on yet (no requests made and an empty cache). A cache that cannot be read is reported as `cache.available: false` with the error, next to the rest of the snapshot, and `cache.requested_path` and `cache.fell_back` show when the configured database could not be opened and a temporary one is in use. |
+| `intel://guide/source-health` | JSON | Open circuit breakers, stale serves, cache freshness per source prefix, and which keyed sources have their variables set (names only, never values). Reading it starts no fetch. Breaker state covers this server process only; the collector keeps its own. `failing_sources` names every source whose last call failed, before or after its breaker opens. A `verdict` line says when there is nothing to go on yet (no requests made and an empty cache). A cache that cannot be read is reported as `cache.available: false` with the error, next to the rest of the snapshot, and `cache.requested_path` and `cache.fell_back` show when the configured database could not be opened and a temporary one is in use. |
| `intel://guide/measures` | Markdown | Amount outstanding versus flow, growth versus acceleration, percentage points, seasonal adjustment, observation versus publication versus collection dates, revisions, correlation and timing offsets, composite scores, and why missing data is not zero. |
**29 prompts**, each a worked research question that names the tools to
diff --git a/src/world_intel_mcp/guide.py b/src/world_intel_mcp/guide.py
index e0a634d..11874a3 100644
--- a/src/world_intel_mcp/guide.py
+++ b/src/world_intel_mcp/guide.py
@@ -417,6 +417,12 @@ _HEALTH_SCOPE = (
"circuit_breakers covers requests made by this server process since it "
"started; the collector, dashboard and CLI keep their own. An empty map "
"means no requests yet, not that every source is healthy.",
+ "failing_sources lists every source whose last call from this process "
+ "failed, whether or not its breaker has opened. In circuit_breakers, "
+ "failures is the count of failed calls since the last success (0 after "
+ "a success), and a breaker opens only after several failures in a row; "
+ "total_successes and total_failures count every call since the process "
+ "started.",
"stale_serves counts, per source, the stale cached copies this process "
"served when a live fetch failed, whatever the payload type.",
"cache_freshness reads the cache database: the newest entry per key "
@@ -453,6 +459,16 @@ def _read_cache(cache: Any) -> tuple[dict[str, Any], dict[str, Any] | None]:
return {"available": True, **stats, **paths}, by_prefix
+def _failing_sources(breakers: dict[str, Any]) -> list[str]:
+ """Sources whose last call failed (failures resets to 0 on a success),
+ or whose breaker is open or half-open."""
+ return sorted(
+ name
+ for name, info in breakers.items()
+ if (info.get("failures") or 0) > 0 or info.get("status") != "closed"
+ )
+
+
def _verdict(breakers: dict[str, Any], cache_info: dict[str, Any]) -> str:
entries = cache_info.get("total_entries") or 0
if not breakers and not entries:
@@ -468,12 +484,19 @@ def _verdict(breakers: dict[str, Any], cache_info: dict[str, Any]) -> str:
"cache_freshness shows what any process sharing the cache fetched last"
)
else:
+ # A breaker opens only after several failures in a row, so a closed
+ # breaker can still mean the last call failed: count both.
+ failing = len(_failing_sources(breakers))
unavailable = sum(1 for info in breakers.values() if info.get("status") != "closed")
+ stale = sum(1 for info in breakers.values() if info.get("total_stale_serves"))
noun = "source" if len(breakers) == 1 else "sources"
verdict = (
- f"{len(breakers)} {noun} called by this process, {unavailable} "
- "with an open or half-open circuit breaker"
+ f"{len(breakers)} {noun} called by this process, {failing} whose "
+ f"last call failed, {unavailable} with an open or half-open circuit "
+ "breaker"
)
+ if stale:
+ verdict += f"; {stale} served a stale cached copy"
if cache_info["fell_back"]:
verdict += (
"; the configured cache could not be opened, so this process uses "
@@ -509,6 +532,7 @@ def source_health(
"generated_at": generated.isoformat(),
"verdict": _verdict(breakers, cache_info),
"scope": list(_HEALTH_SCOPE),
+ "failing_sources": _failing_sources(breakers),
"open_breakers": sorted(
name for name, info in breakers.items() if info.get("status") != "closed"
),
diff --git a/src/world_intel_mcp/guide_prompts.py b/src/world_intel_mcp/guide_prompts.py
index 2fbac99..392235a 100644
--- a/src/world_intel_mcp/guide_prompts.py
+++ b/src/world_intel_mcp/guide_prompts.py
@@ -933,8 +933,10 @@ PROMPTS: tuple[ResearchPrompt, ...] = (
limits=(
"An empty outage list, an all-clear corridor reading or zero "
"cable warnings can each be a failed fetch: when the warning feed "
- "is down every corridor reads clear. Check "
- "intel://guide/source-health before calling {country} connected.",
+ "is down every corridor reads clear. Check failing_sources in "
+ "intel://guide/source-health before calling {country} connected: "
+ "it lists every source whose last call failed, even before its "
+ "circuit breaker opens.",
"Cascade analysis is a simulation over curated cable "
"dependencies, not a measurement of a real outage.",
"BGP status checks one ASN or prefix at a time; it is not a "
diff --git a/src/world_intel_mcp/tests/test_guide.py b/src/world_intel_mcp/tests/test_guide.py
index 2242330..e16efcd 100644
--- a/src/world_intel_mcp/tests/test_guide.py
+++ b/src/world_intel_mcp/tests/test_guide.py
@@ -1527,3 +1527,73 @@ async def test_stale_serves_count_dict_payloads_end_to_end(tmp_path) -> None:
assert (as_dict["_stale"], as_dict["rates"]) == (True, [1.0])
assert as_list == [1, 2]
assert health["stale_serves"] == {"probe-dict": 1, "probe-list": 1}
+
+
+# ---------------------------------------------------------------------------
+# Source health: a failing source is named before its breaker opens (R1)
+# ---------------------------------------------------------------------------
+
+
+def _health(tmp_path, breaker: CircuitBreaker) -> dict:
+ cache = Cache(db_path=tmp_path / "health.db")
+ try:
+ return guide.source_health(breaker, cache, environ={}, now=0)
+ finally:
+ cache.close()
+
+
+def test_source_health_names_sources_whose_last_call_failed(tmp_path) -> None:
+ """One research prompt rarely calls a source three times, so a failed
+ source usually still has a closed breaker; it must be named anyway."""
+ breaker = CircuitBreaker()
+ breaker.record_failure("ioda")
+ breaker.record_success("usgs")
+ breaker.record_failure("nga-msi")
+ breaker.record_failure("nga-msi")
+ health = _health(tmp_path, breaker)
+ assert health["failing_sources"] == ["ioda", "nga-msi"]
+ assert health["open_breakers"] == []
+ assert health["verdict"] == (
+ "3 sources called by this process, 2 whose last call failed, "
+ "0 with an open or half-open circuit breaker"
+ )
+
+
+def test_source_health_counts_a_half_open_breaker(tmp_path) -> None:
+ breaker = CircuitBreaker(failure_threshold=1, cooldown_seconds=0)
+ breaker.record_failure("gdelt")
+ health = _health(tmp_path, breaker)
+ assert health["circuit_breakers"]["gdelt"]["status"] == "half-open"
+ assert health["open_breakers"] == health["failing_sources"] == ["gdelt"]
+ assert health["verdict"] == (
+ "1 source called by this process, 1 whose last call failed, "
+ "1 with an open or half-open circuit breaker"
+ )
+
+
+def test_source_health_drops_a_source_that_recovered(tmp_path) -> None:
+ breaker = CircuitBreaker()
+ breaker.record_failure("ioda")
+ breaker.record_success("ioda")
+ health = _health(tmp_path, breaker)
+ assert health["failing_sources"] == []
+ assert health["verdict"].startswith("1 source called by this process, 0 whose last call failed")
+
+
+def test_source_health_verdict_counts_stale_serves(tmp_path) -> None:
+ breaker = CircuitBreaker()
+ breaker.record_failure("aaa")
+ breaker.record_stale_serve("aaa")
+ breaker.record_success("usgs")
+ health = _health(tmp_path, breaker)
+ assert health["verdict"].endswith("; 1 served a stale cached copy")
+ plain = CircuitBreaker()
+ plain.record_success("usgs")
+ assert "stale" not in _health(tmp_path, plain)["verdict"]
+
+
+def test_source_health_scope_explains_the_breaker_counters() -> None:
+ scope = " ".join(guide._HEALTH_SCOPE)
+ for term in ("failing_sources", "failures is the count of failed calls since the last success",
+ "total_successes", "total_failures"):
+ assert term in scope, term