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.
Python ai-toolsai-watchanthropicclaudecybersecuritydashboardgeofencinggeopoliticalgeospatialintelligencemarketsmcpmigrationmilitarymodel-context-protocolnuclearosintreal-timespace-weatherthreat-intelligence
"""AI-powered situational analysis for world-intel-mcp.
Generates a real-time intelligence brief from all dashboard data
using a local Ollama LLM. Falls back to a structured metrics summary
when the LLM is unavailable.
Every brief carries a numbered ``sources`` list built from the same
overview data it summarizes, and a ``cited`` flag that is only true when
the returned text actually contains at least one ``[n]`` reference to a
real entry in that list. A metric with no traceable upstream item is
reported without a citation rather than pointing at something that
isn't really there.
"""
import asyncio
import logging
import os
import re
from datetime import datetime, timezone
import httpx
logger = logging.getLogger("world-intel-mcp.analysis.situation")
_CITATION_RE = re.compile(r"\[(\d+)\]")
# Overview key -> short citable domain label. Kept distinct from the
# dict key so labels stay stable even when the underlying key varies
# (conflict data comes from whichever of acled/conflict_zones/ucdp is
# actually populated).
_CONFLICT_FEED_LABELS = {
"acled_events": "ACLED",
"conflict_zones": "hotspot fallback",
"ucdp_events": "UCDP",
}
def _utc_now_iso() -> str:
return datetime.now(timezone.utc).isoformat()
def _add_source(
sources: list[dict],
domain: str,
description: str,
url: str | None = None,
timestamp: str | None = None,
) -> int:
"""Append a numbered, traceable source and return its citation number."""
n = len(sources) + 1
entry: dict = {"n": n, "domain": domain, "description": description}
if url:
entry["url"] = url
if timestamp:
entry["timestamp"] = timestamp
sources.append(entry)
return n
def _cite(citations: dict[str, list[int]], key: str, n: int) -> None:
citations.setdefault(key, []).append(n)
def _citation_suffix(citations: dict[str, list[int]], *keys: str) -> str:
"""Format the trailing ``[n][n]`` markers for a fallback-brief line
from the metric keys it reports on. Empty when none of those keys
produced a source: an uncited line is the honest outcome, not a
bug, for a metric with nothing traceable behind it."""
ns: list[int] = []
for key in keys:
for n in citations.get(key, []):
if n not in ns:
ns.append(n)
ns.sort()
return "".join(f"[{n}]" for n in ns)
def _has_valid_citation(text: str, source_count: int) -> bool:
"""True only if `text` contains at least one [n] whose n is a real
source number. A hallucinated or out-of-range [n] does not count:
that is the model ignoring the citation instruction, not honoring it."""
if source_count <= 0:
return False
for match in _CITATION_RE.finditer(text):
n = int(match.group(1))
if 1 <= n <= source_count:
return True
return False
def _extract_metrics(data: dict) -> tuple[dict, list[dict], dict[str, list[int]]]:
"""Pull key numbers from the full overview data.
Alongside the metrics dict, builds a numbered `sources` list and a
`citations` map (metric key -> source numbers) covering every metric
that has an identifiable upstream item behind it. Metrics computed
from missing, errored, or empty domain data get no source entry and
no citation.
"""
sources: list[dict] = []
citations: dict[str, list[int]] = {}
eq = data.get("earthquakes", {})
quakes = eq.get("count", 0) if isinstance(eq, dict) else 0
# fetch_earthquakes() returns the event list under "earthquakes", not
# "events": the latter key was never populated, so max_magnitude (and,
# without this fix, every earthquake citation) was silently dead code.
eq_events = eq.get("earthquakes", []) if isinstance(eq, dict) else []
max_mag = (
max((e.get("magnitude", 0) for e in eq_events), default=0) if eq_events else 0
)
if eq_events:
top_quake = max(eq_events, key=lambda e: e.get("magnitude") or 0)
n = _add_source(
sources,
"earthquakes",
f"M{top_quake.get('magnitude')} earthquake, {top_quake.get('place') or 'unknown location'}",
url=top_quake.get("url"),
timestamp=top_quake.get("time"),
)
_cite(citations, "earthquakes", n)
mil = data.get("military_flights", {})
mil_count = mil.get("count", 0) if isinstance(mil, dict) else 0
if isinstance(mil, dict) and mil and not mil.get("error"):
n = _add_source(
sources,
"military",
f"{mil_count} military aircraft currently tracked",
timestamp=mil.get("timestamp"),
)
_cite(citations, "military_aircraft", n)
conflict_domain = None
for key in ("acled_events", "conflict_zones", "ucdp_events"):
if data.get(key):
conflict_domain = key
break
conflict_src = data.get(conflict_domain, {}) if conflict_domain else {}
conflict_count = (
conflict_src.get("count", 0) if isinstance(conflict_src, dict) else 0
)
if (
conflict_domain
and isinstance(conflict_src, dict)
and not conflict_src.get("error")
):
conflict_events = conflict_src.get("events", [])
feed_label = _CONFLICT_FEED_LABELS.get(conflict_domain, conflict_domain)
if conflict_events:
top_event = conflict_events[0]
loc = (
top_event.get("location")
or top_event.get("admin1")
or top_event.get("country")
or "unspecified location"
)
event_type = top_event.get("event_type") or "conflict event"
n = _add_source(
sources,
"conflict",
f"{event_type}, {loc} ({feed_label})",
timestamp=top_event.get("event_date"),
)
_cite(citations, "conflicts", n)
elif conflict_count:
n = _add_source(
sources,
"conflict",
f"{conflict_count} conflict events tracked ({feed_label})",
)
_cite(citations, "conflicts", n)
fires = data.get("wildfires", {})
fire_regions = fires.get("fires_by_region", {}) if isinstance(fires, dict) else {}
fire_clusters = sum(
len(r.get("top_clusters", []))
for r in fire_regions.values()
if isinstance(r, dict)
)
if fire_regions:
top_region, top_count = max(
(
(name, len(r.get("top_clusters", [])) if isinstance(r, dict) else 0)
for name, r in fire_regions.items()
),
key=lambda pair: pair[1],
default=(None, 0),
)
if top_region and top_count:
n = _add_source(
sources,
"wildfires",
f"{top_count} active fire clusters in {top_region}",
)
_cite(citations, "fire_clusters", n)
cyber = data.get("cyber_threats", {})
cyber_threats_list = cyber.get("threats", []) if isinstance(cyber, dict) else []
cyber_count = len(cyber_threats_list)
if cyber_threats_list:
top_threat = cyber_threats_list[0]
threat_label = (
top_threat.get("threat") or top_threat.get("type") or "cyber threat"
)
indicator = top_threat.get("indicator") or ""
severity = top_threat.get("severity") or "unknown"
label = f"{threat_label}, {indicator}" if indicator else threat_label
desc = f"{label} ({severity} severity)"
n = _add_source(
sources,
"cyber",
desc,
timestamp=top_threat.get("first_seen") or None,
)
_cite(citations, "cyber_threats", n)
posture = data.get("strategic_posture", {})
posture_score = (
posture.get("composite_score", 0) if isinstance(posture, dict) else 0
)
risk_level = (
posture.get("risk_level", "unknown") if isinstance(posture, dict) else "unknown"
)
if isinstance(posture, dict) and posture and not posture.get("error"):
n = _add_source(
sources,
"posture",
f"Composite risk score {posture_score}/100 ({risk_level})",
timestamp=posture.get("timestamp"),
)
_cite(citations, "posture", n)
alerts = data.get("alert_digest", {})
alert_count = alerts.get("alert_count", 0) if isinstance(alerts, dict) else 0
if isinstance(alerts, dict) and alerts and not alerts.get("error"):
alert_items = alerts.get("alerts") or []
if alert_items:
top_alert = alert_items[0]
desc = top_alert.get("message") or f"{alert_count} active alerts"
n = _add_source(sources, "alerts", desc, timestamp=alerts.get("timestamp"))
_cite(citations, "alerts", n)
elif alert_count:
n = _add_source(
sources,
"alerts",
f"{alert_count} active alerts across monitored domains",
timestamp=alerts.get("timestamp"),
)
_cite(citations, "alerts", n)
space = data.get("space_weather", {})
# No Kp reading (SWPC down or breaker open) stays None: it is unknown,
# not quiet, and rendering it must not raise.
kp = space.get("current_kp") if isinstance(space, dict) else None
if kp is not None:
n = _add_source(
sources,
"space_weather",
f"Kp index {round(kp, 1)}",
timestamp=space.get("timestamp"),
)
_cite(citations, "kp_index", n)
health = data.get("disease_outbreaks", {})
outbreaks = health.get("high_concern_count", 0) if isinstance(health, dict) else 0
if isinstance(health, dict) and health and not health.get("error"):
high_concern_items = [
item
for item in (health.get("items") or [])
if isinstance(item, dict) and item.get("is_high_concern")
]
if high_concern_items:
top = high_concern_items[0]
n = _add_source(
sources,
"health",
top.get("title") or "disease outbreak alert",
url=top.get("link"),
timestamp=top.get("published"),
)
_cite(citations, "outbreaks", n)
news = data.get("news_feed", {})
headlines = []
if isinstance(news, dict):
for item in (news.get("items") or news.get("articles") or [])[:5]:
if isinstance(item, dict):
title = item.get("title", "")
headlines.append(title)
if title:
n = _add_source(
sources,
"news",
title,
url=item.get("link") or item.get("url"),
timestamp=item.get("published"),
)
_cite(citations, "headlines", n)
domestic = data.get("domestic_flights", {})
total_aircraft = (
domestic.get("total_aircraft", 0) if isinstance(domestic, dict) else 0
)
if isinstance(domestic, dict) and domestic and not domestic.get("error"):
n = _add_source(
sources,
"aviation",
f"{total_aircraft} aircraft airborne globally",
timestamp=domestic.get("timestamp"),
)
_cite(citations, "total_aircraft", n)
traffic = data.get("traffic_flow", {})
avg_congestion = (
traffic.get("global_avg_congestion", 0) if isinstance(traffic, dict) else 0
)
if isinstance(traffic, dict) and traffic and not traffic.get("error"):
n = _add_source(
sources,
"traffic",
f"{avg_congestion}% average city congestion",
timestamp=traffic.get("timestamp"),
)
_cite(citations, "avg_congestion", n)
metrics = {
"earthquakes": quakes,
"max_magnitude": round(max_mag, 1),
"military_aircraft": mil_count,
"conflicts": conflict_count,
"fire_clusters": fire_clusters,
"cyber_threats": cyber_count,
"posture_score": round(posture_score),
"risk_level": risk_level,
"alerts": alert_count,
"kp_index": round(kp, 1) if kp is not None else None,
"outbreaks": outbreaks,
"total_aircraft": total_aircraft,
"avg_congestion": avg_congestion,
"top_headlines": headlines,
}
return metrics, sources, citations
def _kp_text(m: dict) -> str:
"""The Kp reading as text; a missing reading says so instead of "None"."""
if m["kp_index"] is None:
return "Kp unavailable (no reading)"
return f"Kp {m['kp_index']}"
def _build_prompt(m: dict, sources: list[dict]) -> str:
"""Build an LLM prompt from extracted metrics and the source list."""
headline_block = (
"\n".join(f" - {h}" for h in m["top_headlines"])
if m["top_headlines"]
else " (no headlines available)"
)
source_block = (
"\n".join(f" [{s['n']}] ({s['domain']}) {s['description']}" for s in sources)
if sources
else " (no numbered sources available, do not invent citation numbers)"
)
return f"""You are a senior intelligence analyst. Generate a concise 3-paragraph situational awareness brief based on these real-time metrics:
THREAT POSTURE: Score {m["posture_score"]}/100 ({m["risk_level"]}), {m["alerts"]} active alerts
MILITARY: {m["military_aircraft"]} tracked aircraft
CONFLICT: {m["conflicts"]} active events
SEISMIC: {m["earthquakes"]} earthquakes (max M{m["max_magnitude"]})
FIRES: {m["fire_clusters"]} active fire clusters
CYBER: {m["cyber_threats"]} tracked IOCs
SPACE WEATHER: {_kp_text(m)}
HEALTH: {m["outbreaks"]} high-concern outbreaks
AIR TRAFFIC: {m["total_aircraft"]} aircraft airborne
TRAFFIC: {m["avg_congestion"]}% avg city congestion
TOP HEADLINES:
{headline_block}
NUMBERED SOURCES (cite claims inline as [n], using ONLY the numbers below; never invent a source or cite a number that is not listed here):
{source_block}
Write exactly 3 paragraphs:
1. Overall threat assessment and most significant developments
2. Regional hotspots and emerging patterns
3. Recommended watch items for the next 12 hours
Be specific, cite numbers. Cite every factual claim inline as [n] referencing the source list above. No preamble."""
def _fallback_brief(m: dict, citations: dict[str, list[int]]) -> str:
"""Generate a structured summary without LLM, cited mechanically:
each line is assembled per-metric, so it carries exactly the
citations backing the numbers on that line, no more and no less."""
lines = [
f"THREAT POSTURE: {m['risk_level'].upper()} (score {m['posture_score']}/100) with {m['alerts']} active alerts."
f"{_citation_suffix(citations, 'posture', 'alerts')}",
f"MILITARY: {m['military_aircraft']} aircraft tracked. CONFLICT: {m['conflicts']} active events."
f"{_citation_suffix(citations, 'military_aircraft', 'conflicts')}",
f"SEISMIC: {m['earthquakes']} earthquakes (max M{m['max_magnitude']}). FIRES: {m['fire_clusters']} clusters."
f"{_citation_suffix(citations, 'earthquakes', 'fire_clusters')}",
f"CYBER: {m['cyber_threats']} IOCs. HEALTH: {m['outbreaks']} high-concern outbreaks."
f"{_citation_suffix(citations, 'cyber_threats', 'outbreaks')}",
f"SPACE: {_kp_text(m)}. AIR TRAFFIC: {m['total_aircraft']} airborne. CONGESTION: {m['avg_congestion']}%."
f"{_citation_suffix(citations, 'kp_index', 'total_aircraft', 'avg_congestion')}",
]
return "\n".join(lines)
async def fetch_situation_brief(overview_data: dict) -> dict:
"""Generate an AI situational analysis brief from dashboard data.
Uses local Ollama LLM to synthesize all intelligence domains into
an actionable 3-paragraph brief. Falls back to structured metrics
summary when Ollama is unavailable.
Args:
overview_data: Full dashboard overview dict from _fetch_overview().
Returns:
Dict with brief text, generation metadata, key metrics, a numbered
`sources` list traceable back to overview_data, and a `cited` flag
that is true only when the brief text actually references one of
those sources.
"""
metrics, sources, citations = _extract_metrics(overview_data)
prompt = _build_prompt(metrics, sources)
ollama_url = os.environ.get("OLLAMA_API_URL", "http://localhost:11434")
model = os.environ.get("OLLAMA_MODEL", "llama3.2")
brief_text = ""
ai_generated = False
used_model = "fallback"
try:
async with httpx.AsyncClient(timeout=30) as client:
resp = await client.post(
f"{ollama_url}/api/generate",
json={
"model": model,
"prompt": prompt,
"stream": False,
"options": {"temperature": 0.3, "num_predict": 500},
},
)
resp.raise_for_status()
result = resp.json()
brief_text = result.get("response", "").strip()
if brief_text:
ai_generated = True
used_model = model
except Exception as exc:
logger.debug("Ollama unavailable for situation brief: %s", exc)
if not brief_text:
brief_text = _fallback_brief(metrics, citations)
cited = _has_valid_citation(brief_text, len(sources))
return {
"brief": brief_text,
"ai_generated": ai_generated,
"model": used_model,
"metrics_snapshot": metrics,
"sources": sources,
"cited": cited,
"source": "situation-brief",
"timestamp": _utc_now_iso(),
}
# ---------------------------------------------------------------------------
# intel_situation_brief (MCP tool): bounded server-side overview
# ---------------------------------------------------------------------------
# The domains this tool gathers itself, matched against _extract_metrics'
# keys. A bounded subset of the dashboard's full 47-source fan-out (issue
# #18): the domains that carry the most weight in the brief (threat
# posture, military, conflict, seismic/fire/cyber/health current events,
# space weather, headlines), reusing existing analysis functions unchanged
# rather than reimplementing their fan-out.
_COMPACT_OVERVIEW_DOMAINS = {
"earthquakes": "Earthquakes",
"military_flights": "Military flights",
"acled_events": "Conflict events",
"wildfires": "Wildfires",
"cyber_threats": "Cyber threats",
"disease_outbreaks": "Disease outbreaks",
"news_feed": "News",
"space_weather": "Space weather",
"strategic_posture": "Strategic posture",
"alert_digest": "Alert digest",
}
async def _safe_fetch(coro, label: str) -> dict:
try:
result = await coro
return result if isinstance(result, dict) else {}
except Exception as exc:
logger.warning("Situation brief overview: %s failed: %s", label, exc)
return {"error": str(exc)}
async def _gather_compact_overview(fetcher) -> dict:
"""Fetch a bounded set of domains server-side, shaped like
`_fetch_overview()`'s output (for `_extract_metrics()` reuse), without
importing the dashboard's Starlette app or its full 47-source fan-out.
"""
from ..sources import (
cyber,
health,
military,
news,
seismology,
space_weather,
wildfire,
)
from ..sources import conflict as conflict_src
from .alerts import fetch_alert_digest
from .posture import fetch_strategic_posture
(
earthquakes,
military_flights,
acled_events,
wildfires,
cyber_threats,
disease_outbreaks,
news_feed,
space_weather_data,
strategic_posture,
alert_digest,
) = await asyncio.gather(
_safe_fetch(seismology.fetch_earthquakes(fetcher), "earthquakes"),
_safe_fetch(military.fetch_military_flights(fetcher), "military_flights"),
_safe_fetch(conflict_src.fetch_acled_events(fetcher), "acled_events"),
_safe_fetch(wildfire.fetch_wildfires(fetcher), "wildfires"),
_safe_fetch(cyber.fetch_cyber_threats(fetcher), "cyber_threats"),
_safe_fetch(health.fetch_disease_outbreaks(fetcher), "disease_outbreaks"),
_safe_fetch(news.fetch_news_feed(fetcher), "news_feed"),
_safe_fetch(space_weather.fetch_space_weather(fetcher), "space_weather"),
_safe_fetch(fetch_strategic_posture(fetcher), "strategic_posture"),
_safe_fetch(fetch_alert_digest(fetcher), "alert_digest"),
)
return {
"earthquakes": earthquakes,
"military_flights": military_flights,
"acled_events": acled_events,
"wildfires": wildfires,
"cyber_threats": cyber_threats,
"disease_outbreaks": disease_outbreaks,
"news_feed": news_feed,
"space_weather": space_weather_data,
"strategic_posture": strategic_posture,
"alert_digest": alert_digest,
}
async def fetch_live_situation_brief(fetcher) -> dict:
"""MCP-tool entry point for `intel_situation_brief` (issue #18).
Gathers a compact overview server-side (`_gather_compact_overview`,
~8-10 domains rather than the dashboard's full 47-source fan-out) and
delegates to `fetch_situation_brief()` unchanged for the AI-generated
brief or its mechanically-cited fallback. A domain that fails to fetch
simply carries no citation in the result (the same honesty guarantee
`_extract_metrics` already provides for every caller of
`fetch_situation_brief`); it does not fail the whole tool call.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
The unmodified `fetch_situation_brief()` result: `brief`,
`ai_generated`, `model`, `metrics_snapshot`, `sources`, `cited`,
`source`, `timestamp`.
"""
overview = await _gather_compact_overview(fetcher)
return await fetch_situation_brief(overview)