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.

ACLED: a failed sign-in is not "credentials not configured"

Phoenix Agent (mac-studio)18ec112af22e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cb637cb..e9ece2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -293,6 +293,10 @@ source here, and no proxy is substituted for any of these measures.
`ucdp_partial`, `pages_failed`, `pages_total` and a `data_gaps` entry
saying count and fatalities are lower bounds, and the conflict-trend
prompt tells the model to report the list as incomplete.
+- With `ACLED_EMAIL` and `ACLED_PASSWORD` set but the ACLED sign-in
+ request refused or unreachable, every ACLED tool said the credentials
+ were not configured. That case now has its own reason,
+ `acled_auth_failed`, and the error says the sign-in failed.
### Added: tropical cyclone forecast tracks
- `intel_cyclones` and `intel_jtwc_cyclones` take `include_forecast`
diff --git a/src/world_intel_mcp/guide.py b/src/world_intel_mcp/guide.py
index 439f791..39fc157 100644
--- a/src/world_intel_mcp/guide.py
+++ b/src/world_intel_mcp/guide.py
@@ -108,7 +108,9 @@ KEYED_SOURCES: tuple[KeyedSource, ...] = (
KeyedSource(
"ACLED",
("ACLED_EMAIL", "ACLED_PASSWORD"),
- "ACLED event, unrest and risk tools return an error naming the missing credentials.",
+ "ACLED event, unrest and risk tools return an error naming the missing "
+ "credentials. When both are set but the sign-in request fails, the "
+ "error says ACLED sign-in failed instead (reason acled_auth_failed).",
needed_by=("intel_acled_events", "intel_unrest_events", "intel_risk_scores"),
),
KeyedSource(
diff --git a/src/world_intel_mcp/sources/conflict.py b/src/world_intel_mcp/sources/conflict.py
index c66708f..05f5719 100644
--- a/src/world_intel_mcp/sources/conflict.py
+++ b/src/world_intel_mcp/sources/conflict.py
@@ -111,12 +111,35 @@ async def acled_query(
)
+_ACLED_FAILURE_MESSAGES = {
+ "acled_unconfigured": "ACLED credentials not configured (ACLED_EMAIL + ACLED_PASSWORD)",
+ "acled_auth_failed": (
+ "ACLED sign-in failed: ACLED_EMAIL and ACLED_PASSWORD are set, but the "
+ "token request was refused or did not complete"
+ ),
+ "acled_fetch_failed": "ACLED fetch failed (rate limited, API error, or malformed response)",
+}
+
+
+def acled_failure_message(reason: str | None) -> str:
+ """The error text for an ``acled_failure_reason()`` value."""
+ return _ACLED_FAILURE_MESSAGES.get(reason or "", _ACLED_FAILURE_MESSAGES["acled_fetch_failed"])
+
+
+def _acled_credentials_set() -> bool:
+ return bool(
+ (os.environ.get("ACLED_EMAIL") and os.environ.get("ACLED_PASSWORD"))
+ or _acled_refresh_token
+ )
+
+
async def acled_failure_reason(data: dict | list | None) -> str | None:
"""Classify why an ``acled_query()``/``fetch_acled_events()`` call returned no data.
- ``acled_query`` returns ``None`` for two structurally different reasons that
+ ``acled_query`` returns ``None`` for structurally different reasons that
callers must not conflate: missing credentials (a config problem, not an
- outage) versus a live fetch that failed after credentials were fine (a
+ outage), credentials that are set but whose token request failed (refused
+ or unreachable sign-in), and a live fetch that failed after sign-in (a
transient outage). Callers use this to pick an honest message/marker
instead of guessing.
@@ -125,12 +148,15 @@ async def acled_failure_reason(data: dict | list | None) -> str | None:
Returns:
``None`` if *data* is present (no failure). Otherwise
- ``"acled_unconfigured"`` (no ``ACLED_EMAIL``/``ACLED_PASSWORD``) or
- ``"acled_fetch_failed"`` (credentials fine, the request itself failed).
+ ``"acled_unconfigured"`` (no ``ACLED_EMAIL``/``ACLED_PASSWORD``),
+ ``"acled_auth_failed"`` (both set, but no token could be obtained) or
+ ``"acled_fetch_failed"`` (signed in, the request itself failed).
"""
if data is not None:
return None
if not await _acled_get_token():
+ if _acled_credentials_set():
+ return "acled_auth_failed"
return "acled_unconfigured"
return "acled_fetch_failed"
@@ -181,7 +207,7 @@ async def fetch_acled_events(
reason = await acled_failure_reason(data)
if reason == "acled_unconfigured":
return {
- "error": "ACLED credentials not configured (ACLED_EMAIL + ACLED_PASSWORD)",
+ "error": acled_failure_message(reason),
"note": "Free access at acleddata.com",
"reason": reason,
}
@@ -193,9 +219,9 @@ async def fetch_acled_events(
# peace. Surface it explicitly instead; keep events/count in their
# normal shape so existing callers that don't check "error" or
# "reason" still iterate an empty list rather than crashing.
- logger.warning("ACLED API returned no data (post-auth fetch failure)")
+ logger.warning("ACLED API returned no data (%s)", reason)
return {
- "error": "ACLED fetch failed (rate limited, API error, or malformed response)",
+ "error": acled_failure_message(reason),
"degraded": True,
"reason": reason,
"events": [],
diff --git a/src/world_intel_mcp/sources/intelligence.py b/src/world_intel_mcp/sources/intelligence.py
index f885f41..6fc7b45 100644
--- a/src/world_intel_mcp/sources/intelligence.py
+++ b/src/world_intel_mcp/sources/intelligence.py
@@ -17,7 +17,7 @@ from datetime import datetime, timezone, timedelta
import httpx
from ..fetcher import Fetcher
-from .conflict import acled_query, acled_failure_reason
+from .conflict import acled_query, acled_failure_message, acled_failure_reason
from ..analysis.focal_points import detect_focal_points
from ..analysis.signals import aggregate_country_signals
from ..analysis.temporal import TemporalBaseline
@@ -351,12 +351,12 @@ async def fetch_risk_scores(
"source": "risk-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
- # Credentials are fine; the live fetch failed. Previously this
+ # Credentials are set; sign-in or the live fetch failed. Previously this
# branch was unreachable in practice for a configured deployment
# under outage — it fell through to the same "not configured"
# message, misdiagnosing a transient failure as a config error.
return {
- "error": "ACLED fetch failed (rate limited, API error, or malformed response)",
+ "error": acled_failure_message(reason),
"degraded": True,
"source": "risk-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
@@ -628,7 +628,7 @@ async def _instability_multi(fetcher: Fetcher, now: datetime) -> dict:
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
return {
- "error": "ACLED fetch failed (rate limited, API error, or malformed response)",
+ "error": acled_failure_message(reason),
"degraded": True,
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
@@ -1255,7 +1255,7 @@ async def fetch_unrest_events(
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
return {
- "error": "ACLED fetch failed (rate limited, API error, or malformed response)",
+ "error": acled_failure_message(reason),
"degraded": True,
"source": "acled-unrest",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
diff --git a/src/world_intel_mcp/tests/test_sources.py b/src/world_intel_mcp/tests/test_sources.py
index e2291e5..1f4e249 100644
--- a/src/world_intel_mcp/tests/test_sources.py
+++ b/src/world_intel_mcp/tests/test_sources.py
@@ -896,6 +896,69 @@ async def test_unrest_events_cache_does_not_answer_a_larger_limit(
assert sent == [2, 1000]
+def acled_signed_out(monkeypatch: pytest.MonkeyPatch):
+ """No cached ACLED token, so every call goes through sign-in."""
+ from world_intel_mcp.sources import conflict
+
+ monkeypatch.setattr(conflict, "_acled_token", None)
+ monkeypatch.setattr(conflict, "_acled_token_expires", 0.0)
+ monkeypatch.setattr(conflict, "_acled_refresh_token", None)
+ return conflict
+
+
+async def test_acled_refused_sign_in_is_not_reported_as_unconfigured(
+ fetcher: Fetcher, monkeypatch: pytest.MonkeyPatch, acled_signed_out
+) -> None:
+ """Both variables set, token request refused: the operator has to fix
+ the account or wait out the sign-in outage, not set variables that are
+ already set."""
+ from world_intel_mcp.sources import intelligence
+
+ conflict = acled_signed_out
+ monkeypatch.setenv("ACLED_EMAIL", "[email protected]")
+ monkeypatch.setenv("ACLED_PASSWORD", "offline-fake-value")
+ with respx.mock(assert_all_called=False) as router:
+ sign_in_route = router.post(conflict._ACLED_TOKEN_URL).mock(
+ return_value=httpx.Response(401, json={"error": "invalid_grant"})
+ )
+ read = router.get(conflict._ACLED_API_URL).mock(
+ return_value=httpx.Response(200, json={"data": []})
+ )
+ events = await conflict.fetch_acled_events(fetcher, country="Sudan", days=7)
+ risk = await intelligence.fetch_risk_scores(fetcher)
+ unrest = await intelligence.fetch_unrest_events(fetcher, country="Sudan")
+
+ assert sign_in_route.call_count >= 1
+ assert read.call_count == 0
+ assert events["reason"] == "acled_auth_failed"
+ assert events["degraded"] is True
+ assert events["error"].startswith("ACLED sign-in failed")
+ for result in (events, risk, unrest):
+ assert "not configured" not in result["error"]
+ assert "sign-in failed" in result["error"]
+ assert result["degraded"] is True
+
+
+async def test_acled_unset_variables_are_still_reported_as_unconfigured(
+ fetcher: Fetcher, monkeypatch: pytest.MonkeyPatch, acled_signed_out
+) -> None:
+ conflict = acled_signed_out
+ monkeypatch.delenv("ACLED_EMAIL", raising=False)
+ monkeypatch.delenv("ACLED_PASSWORD", raising=False)
+ with respx.mock(assert_all_called=False) as router:
+ sign_in_route = router.post(conflict._ACLED_TOKEN_URL).mock(
+ return_value=httpx.Response(401)
+ )
+ result = await conflict.fetch_acled_events(fetcher, country="Sudan", days=7)
+
+ assert sign_in_route.call_count == 0
+ assert result["reason"] == "acled_unconfigured"
+ assert "ACLED credentials not configured" in result["error"]
+
+
# ---------------------------------------------------------------------------
# News (GDELT search)
# ---------------------------------------------------------------------------