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
Implements #18: expose the cited situation brief as intel_situation_brief
Phoenix Agent (Marcs-Mac-Studio)0cce5f3d285a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 52a70d5..c7c22bb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -44,6 +44,16 @@store isn't available, the Trends and Timeline sections say so via`data_gaps` instead of rendering as an empty, falsely-quiet section(#15).+- `intel_situation_brief` (+1 = 120 tools). The cited situation brief+ (#15) was previously reachable only through the dashboard's SSE+ overview; MCP clients, the primary consumer this server exists for,+ couldn't call it at all. The new tool gathers a bounded server-side+ overview (earthquakes, military flights, ACLED conflict events,+ wildfires, cyber threats, disease outbreaks, news, space weather,+ strategic posture, and the alert digest, not the dashboard's full+ 47-source fan-out), then delegates to the existing, unmodified+ `fetch_situation_brief` for the AI-generated brief or its+ mechanically-cited fallback when Ollama is unreachable (#18).### Fixed- `_extract_metrics` (situation brief) read the earthquake event list underdiff --git a/CLAUDE.md b/CLAUDE.mdindex 7ae8c57..84c1e13 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co## What This Is-World Intelligence MCP Server: 119 tools across 30+ domains providing real-time global intelligence from free public APIs. Serves four interfaces: MCP stdio (for Claude Code/Cursor), a live Starlette dashboard with SSE, a Click CLI with Rich output, and a collector daemon for 24/7 vector store population. Python 3.11+, built with hatchling.+World Intelligence MCP Server: 120 tools across 30+ domains providing real-time global intelligence from free public APIs. Serves four interfaces: MCP stdio (for Claude Code/Cursor), a live Starlette dashboard with SSE, a Click CLI with Rich output, and a collector daemon for 24/7 vector store population. Python 3.11+, built with hatchling.## Commandsdiff --git a/README.md b/README.mdindex 38d5dbd..ca117c6 100644--- a/README.md+++ b/README.md@@ -6,7 +6,7 @@[](https://python.org)[](LICENSE)-Real-time global intelligence across **30+ domains** with **119 MCP tools**, a live ops-center dashboard, a CLI, and a **Qdrant vector store** for enterprise-grade semantic search across accumulated intelligence. All data comes from free, public APIs: no paid subscriptions required.+Real-time global intelligence across **30+ domains** with **120 MCP tools**, a live ops-center dashboard, a CLI, and a **Qdrant vector store** for enterprise-grade semantic search across accumulated intelligence. All data comes from free, public APIs: no paid subscriptions required.Built for AI agents that need world awareness: market conditions, geopolitical risk, military posture, supply chain disruptions, cyber threats, and more — all queryable via the Model Context Protocol. The vector store enables natural language queries like *"military activity near Taiwan"* or *"cyber threats targeting healthcare"* across all historical data.@@ -58,8 +58,9 @@ Built for AI agents that need world awareness: market conditions, geopolitical r| **Reports** | 1 | PDF/HTML multi-domain intelligence reports || **Daily Digest** | 1 | Cited markdown morning brief: top events, headlines, trends, and timeline || **AOI Geofences** | 5 | User-defined areas of interest: define/list/delete, a cited multi-domain brief, and hotspot escalation scoring for a user's own area |+| **Situation Brief** | 1 | Cited situational awareness brief over MCP: bounded server-side overview synthesized via local Ollama, with a mechanically-cited fallback |-**Total: 119 tools** across 30+ intelligence domains.+**Total: 120 tools** across 30+ intelligence domains.---@@ -436,13 +437,18 @@ collector.py (daemon) ─┘| `intel_aoi_brief` | Cited brief for an AOI: earthquakes, military flights, wildfires, conflict events, aviation, nearby infrastructure, and news mentions, all filtered to the AOI's radius || `intel_aoi_escalation` | Hotspot escalation scoring (same engine as the 22 built-in hotspots) applied to a user AOI |+### Situation Brief (1)+| Tool | Description |+|------|-------------|+| `intel_situation_brief` | Cited situational awareness brief, generated on demand over MCP: a bounded server-side overview (earthquakes, military flights, ACLED conflict events, wildfires, cyber threats, disease outbreaks, news, space weather, strategic posture, alert digest), synthesized via local Ollama or a mechanically-cited fallback when Ollama is unreachable |+---## Watching your own area (geofences/AOIs)Static infrastructure results (bases, ports, nuclear, cables, datacenters, spaceports) draw on this repo's curated strategic datasets, which are global and deliberately sparse, not exhaustive local registries. A quiet AOI brief means nothing from those curated sets is in range, not that your area has no infrastructure.-28 of the 119 tools take some geographic parameter, but before the AOI+28 of the 120 tools take some geographic parameter, but before the AOIfamily only `intel_signal_convergence` accepted a real point-plus-radius,`intel_military_flights` took a bbox, and hotspot escalation scoring wasrestricted to the 22 hardcoded `INTEL_HOTSPOTS`. The `intel_aoi_*` toolsdiff --git a/ROADMAP.md b/ROADMAP.mdindex a4618b1..1c59666 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -2,7 +2,7 @@**Benchmark**: [koala73/worldmonitor](https://github.com/koala73/worldmonitor)**Updated**: 2026-06-04-**Current tools**: 119 (118 intel + 1 status)+**Current tools**: 120 (119 intel + 1 status)---@@ -20,7 +20,7 @@| Area | Finding | Status | Action ||------|---------|--------|--------|-| MCP tool parity | 119 tools declared in `TOOLS`; 119 routed in `_dispatch()` | :white_check_mark: | Keep as an invariant |+| MCP tool parity | 120 tools declared in `TOOLS`; 120 routed in `_dispatch()` | :white_check_mark: | Keep as an invariant || Optional vector runtime | Missing `qdrant-client` / `fastembed` previously surfaced as runtime failures | :white_check_mark: Fixed | Vector features now degrade cleanly and report availability || Base-environment test run | `pytest -q` fails collection without dev extras because `respx` is not installed | :yellow_circle: | Run `pip install -e ".[dev]"` before full-suite validation || Core verification | 226 non-smoke tests pass with dev extras installed | :white_check_mark: | Full default `pytest` run |@@ -461,17 +461,30 @@ filtered to the AOI's radius, with `data_gaps` for domains that can't begeographically scoped. `intel_aoi_escalation` reuses the existing`score_hotspot` scoring engine unmodified for a user AOI (#16).+### Phase 21: Situation Brief over MCP (+1 = 120 tools)+`intel_situation_brief`++The cited situation brief (#15) was previously reachable only through the+dashboard's SSE overview; MCP clients, the primary consumer this server+exists for, couldn't call it. `intel_situation_brief` gathers a bounded+server-side overview (earthquakes, military flights, ACLED conflict+events, wildfires, cyber threats, disease outbreaks, news, space weather,+strategic posture, alert digest, not the dashboard's full 47-source+fan-out) and delegates to the existing, unmodified `fetch_situation_brief`+for the AI-generated brief or its mechanically-cited fallback when Ollama+is unreachable (#18).+---## Summary| Category | Current | Notes ||----------|---------|-------|-| Total MCP tools | 119 | 118 intelligence tools + `intel_status` |-| Tool parity | 119 / 119 | `TOOLS` and `_dispatch()` are aligned |+| Total MCP tools | 120 | 119 intelligence tools + `intel_status` |+| Tool parity | 120 / 120 | `TOOLS` and `_dispatch()` are aligned || Static datasets | 18 | Bases, ports, pipelines, nuclear, cables, datacenters, spaceports, minerals, exchanges, trade routes, cloud regions, financial centers || RSS feeds | 119 | 24 categories |-| Tests in repo | 321 | 303 non-smoke tests + 18 live smoke tests; full suite requires `.[dev]` |+| Tests in repo | 327 | 309 non-smoke tests + 18 live smoke tests; full suite requires `.[dev]` || Primary remaining gap | Architecture | `server.py` monolith remains the main refactor target |-**Bottom line**: 119 tools across 30+ domains, with the roadmap now aligned to the live MCP registry. The main remaining gaps are full-environment test bootstrapping (`.[dev]`) and continued modularization of the monolithic `server.py` tool registry/dispatcher.+**Bottom line**: 120 tools across 30+ domains, with the roadmap now aligned to the live MCP registry. The main remaining gaps are full-environment test bootstrapping (`.[dev]`) and continued modularization of the monolithic `server.py` tool registry/dispatcher.diff --git a/src/world_intel_mcp/analysis/situation.py b/src/world_intel_mcp/analysis/situation.pyindex 6a17975..eaea0c1 100644--- a/src/world_intel_mcp/analysis/situation.py+++ b/src/world_intel_mcp/analysis/situation.py@@ -12,6 +12,7 @@ reported without a citation rather than pointing at something thatisn't really there."""+import asyncioimport loggingimport osimport re@@ -460,3 +461,115 @@ async def fetch_situation_brief(overview_data: dict) -> dict:"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)diff --git a/src/world_intel_mcp/server.py b/src/world_intel_mcp/server.pyindex 77ff366..dd45acd 100644--- a/src/world_intel_mcp/server.py+++ b/src/world_intel_mcp/server.py@@ -45,6 +45,10 @@ Phase 21: AOI geofences (+5 = 119 tools). intel_aoi_define/list/delete persist ninfrastructure, and news mentions for a user's own area, with data_gaps fordomains that can't be scoped. intel_aoi_escalation reuses the existing hotspotscoring unmodified for a user AOI (#16).+Phase 22: intel_situation_brief (+1 = 120 tools). The cited situation brief (#15) is now+ reachable directly over MCP, not only through the dashboard: a bounded+ server-side gather of ~8-10 domains feeds the existing, unmodified+ fetch_situation_brief() (#18)."""import asyncio@@ -1818,6 +1822,12 @@ TOOLS: list[Tool] = ["required": ["name"],},),+ # --- Situation Brief (1 tool) ---+ Tool(+ name="intel_situation_brief",+ description="Cited situational awareness brief, generated on demand over MCP (previously reachable only through the dashboard). Gathers a bounded server-side overview (earthquakes, military flights, ACLED conflict events, wildfires, cyber threats, disease outbreaks, news headlines, space weather, strategic posture, alert digest; not the dashboard's full 47-source fan-out), then synthesizes a 3-paragraph brief via local Ollama, or a mechanically-cited fallback summary when Ollama is unreachable. Returns brief, ai_generated, model, metrics_snapshot, a numbered sources list, and a cited flag that is true only when the brief text references a real source number.",+ inputSchema={"type": "object", "properties": {}},+ ),# --- Reports (1 tool) ---Tool(name="intel_generate_report",@@ -2540,6 +2550,12 @@ async def _dispatch(name: str, arguments: dict[str, Any]) -> Any:fetcher, _aoi_store, name=arguments.get("name"))+ # Situation Brief+ case "intel_situation_brief":+ from .analysis.situation import fetch_live_situation_brief++ return await fetch_live_situation_brief(fetcher)+# System# Reportscase "intel_generate_report":diff --git a/src/world_intel_mcp/tests/test_situation.py b/src/world_intel_mcp/tests/test_situation.pyindex db75873..7857cec 100644--- a/src/world_intel_mcp/tests/test_situation.py+++ b/src/world_intel_mcp/tests/test_situation.py@@ -1,18 +1,40 @@-"""Tests for analysis/situation.py: cited situation briefs (issue #15).+"""Tests for analysis/situation.py: cited situation briefs (issue #15) and+the intel_situation_brief MCP tool (issue #18).Uses respx to mock the Ollama endpoint, matching the network-edge-mockingstyle used elsewhere in this suite (see test_sources.py, test_intelligence.py).+The tool-composition tests mock at the source-function boundary+(monkeypatch), matching the pattern test_daily_digest.py established for+this exact class of function: it composes existing sources/*.py and+analysis/*.py fetch functions rather than making HTTP calls itself."""import re+from pathlib import Pathimport httpximport pytestimport respx-from world_intel_mcp.analysis.situation import _extract_metrics, fetch_situation_brief+from world_intel_mcp.analysis import alerts, posture+from world_intel_mcp.analysis.situation import (+ _extract_metrics,+ fetch_live_situation_brief,+ fetch_situation_brief,+)+from world_intel_mcp.sources import conflict as conflict_src+from world_intel_mcp.sources import (+ cyber,+ health,+ military,+ news,+ seismology,+ space_weather,+)+from world_intel_mcp.sources import wildfire_OLLAMA_GENERATE = "http://localhost:11434/api/generate"+_SERVER_PY = Path(__file__).resolve().parents[1] / "server.py"def _synthetic_overview() -> dict:@@ -315,3 +337,214 @@ async def test_empty_overview_falls_back_uncited() -> None:assert result["sources"] == []assert result["cited"] is False+++# ---------------------------------------------------------------------------+# intel_situation_brief tool: fetch_live_situation_brief (issue #18)+# ---------------------------------------------------------------------------+++async def _fake_earthquakes(fetcher):+ return {+ "earthquakes": [+ {+ "id": "us1",+ "magnitude": 6.4,+ "place": "5km E of Nowhere",+ "time": "2026-08-16T01:00:00Z",+ "url": "https://earthquake.usgs.gov/us1",+ },+ ],+ "count": 1,+ "source": "usgs",+ }+++async def _fake_military(fetcher):+ return {+ "aircraft": [],+ "count": 4,+ "source": "adsb.lol",+ "timestamp": "2026-08-16T00:00:00Z",+ }+++async def _fake_acled(fetcher, **kwargs):+ return {+ "events": [+ {+ "event_type": "Battle",+ "location": "Somewhere",+ "event_date": "2026-08-15",+ },+ ],+ "count": 1,+ "source": "acled",+ }+++async def _fake_wildfires(fetcher):+ return {+ "fires_by_region": {"california": {"count": 3, "top_clusters": [{}, {}, {}]}},+ "total_fires": 3,+ }+++async def _fake_cyber(fetcher):+ return {+ "threats": [+ {+ "type": "c2_ip",+ "indicator": "1.2.3.4",+ "threat": "Emotet",+ "severity": "critical",+ "first_seen": "2026-08-15",+ },+ ],+ "count": 1,+ }+++async def _fake_health(fetcher):+ return {+ "items": [+ {+ "title": "Outbreak of Z",+ "link": "https://who.int/z",+ "published": "2026-08-15",+ "is_high_concern": True,+ },+ ],+ "high_concern_count": 1,+ }+++async def _fake_news(fetcher):+ return {+ "items": [+ {+ "title": "Big headline",+ "link": "https://news.example/a",+ "published": "2026-08-16T00:00:00Z",+ },+ ],+ }+++async def _fake_space_weather(fetcher):+ return {"current_kp": 5.3, "timestamp": "2026-08-16T00:00:00Z"}+++async def _fake_strategic_posture(fetcher):+ return {+ "composite_score": 55,+ "risk_level": "elevated",+ "timestamp": "2026-08-16T00:00:00Z",+ }+++async def _fake_alert_digest(fetcher):+ return {+ "alerts": [+ {+ "domain": "space",+ "priority": "high",+ "message": "Geomagnetic storm: Kp=6",+ },+ ],+ "alert_count": 1,+ "timestamp": "2026-08-16T00:00:00Z",+ }+++def _patch_all_compact_domains(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(seismology, "fetch_earthquakes", _fake_earthquakes)+ monkeypatch.setattr(military, "fetch_military_flights", _fake_military)+ monkeypatch.setattr(conflict_src, "fetch_acled_events", _fake_acled)+ monkeypatch.setattr(wildfire, "fetch_wildfires", _fake_wildfires)+ monkeypatch.setattr(cyber, "fetch_cyber_threats", _fake_cyber)+ monkeypatch.setattr(health, "fetch_disease_outbreaks", _fake_health)+ monkeypatch.setattr(news, "fetch_news_feed", _fake_news)+ monkeypatch.setattr(space_weather, "fetch_space_weather", _fake_space_weather)+ monkeypatch.setattr(posture, "fetch_strategic_posture", _fake_strategic_posture)+ monkeypatch.setattr(alerts, "fetch_alert_digest", _fake_alert_digest)+++async def test_situation_brief_tool_returns_sources_and_cited(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The compact server-side gather feeds fetch_situation_brief()+ unchanged: a real (mocked) Ollama response that cites a real source+ number must come back ai_generated + cited, with a populated sources+ list traceable to the mocked domains."""+ _patch_all_compact_domains(monkeypatch)+ respx.post(_OLLAMA_GENERATE).mock(+ return_value=httpx.Response(+ 200,+ json={"response": "Seismic activity ticked up [1] while alerts held [2]."},+ )+ )++ result = await fetch_live_situation_brief(fetcher=None)++ assert result["ai_generated"] is True+ assert result["cited"] is True+ assert result["sources"]+ domains = {s["domain"] for s in result["sources"]}+ assert domains == {+ "earthquakes",+ "military",+ "conflict",+ "wildfires",+ "cyber",+ "health",+ "news",+ "space_weather",+ "posture",+ "alerts",+ }+++async def test_situation_brief_tool_falls_back_when_ollama_unreachable(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Issue #18: the fallback must hold through the tool path, not just+ the already-tested fetch_situation_brief(overview) path. Blocks the+ Ollama URL with respx (ConnectError) exactly like+ test_fallback_brief_is_mechanically_cited does above."""+ _patch_all_compact_domains(monkeypatch)+ respx.post(_OLLAMA_GENERATE).mock(+ side_effect=httpx.ConnectError("no ollama in test env")+ )++ result = await fetch_live_situation_brief(fetcher=None)++ assert result["ai_generated"] is False+ assert result["model"] == "fallback"+ assert result["cited"] is True+ assert result["sources"]+ real_ns = {s["n"] for s in result["sources"]}+ found_ns = {int(n) for n in re.findall(r"\[(\d+)\]", result["brief"])}+ assert found_ns, "fallback brief carried no citations at all"+ assert found_ns <= real_ns+++def test_intel_situation_brief_registered_and_dispatched() -> None:+ """Structural parity check: the TOOLS/`_dispatch` 1:1 invariant this+ repo maintains (see ROADMAP.md 'MCP tool parity') must hold for the+ new tool. Reads server.py as text rather than importing the module,+ matching test_daily_digest.py's and test_aoi.py's pattern (importing+ world_intel_mcp.server opens a live Cache() at the default on-disk+ path, which no other test in this suite triggers)."""+ text = _SERVER_PY.read_text()++ assert 'name="intel_situation_brief"' in text++ dispatch_idx = text.index('case "intel_situation_brief":')+ assert dispatch_idx > 0+ dispatch_body = text[dispatch_idx : dispatch_idx + 300]+ assert "fetch_live_situation_brief" in dispatch_body