From b01a77721b92ffb21e3272cc365d1240c54e526f Mon Sep 17 00:00:00 2001 From: Marc Shade Date: Sun, 8 Mar 2026 08:24:45 -0400 Subject: [PATCH] docs(world-intel): update README and CLAUDE.md for 101 tools --- CLAUDE.md | 2 +- README.md | 481 +++++++++++++++++++++++------------------------------- 2 files changed, 202 insertions(+), 281 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f965822..3f67844 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 — 89 tools across 30+ domains providing real-time global intelligence from free public APIs. Serves three interfaces: MCP stdio (for Claude Code/Cursor), a live Starlette dashboard with SSE, and a Click CLI with Rich output. Python 3.11+, built with hatchling. +World Intelligence MCP Server — 101 tools across 30+ domains providing real-time global intelligence from free public APIs. Serves three interfaces: MCP stdio (for Claude Code/Cursor), a live Starlette dashboard with SSE, and a Click CLI with Rich output. Python 3.11+, built with hatchling. ## Commands diff --git a/README.md b/README.md index 66dfef0..387c723 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-green)](https://python.org) [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE) -Real-time global intelligence across **27 domains** with **68 MCP tools**, a live ops-center dashboard, CLI reports, and per-source circuit breakers. All data comes from free, public APIs — no paid subscriptions required. +Real-time global intelligence across **30+ domains** with **101 MCP tools**, a live ops-center dashboard, and a CLI. All data comes from free, public APIs — no paid subscriptions required. -> **Successor to threat-intel-mcp.** This project evolved from a focused threat intelligence server into a comprehensive world intelligence platform covering markets, geopolitics, climate, military, space weather, AI research, and more. +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. --- @@ -16,36 +16,44 @@ Real-time global intelligence across **27 domains** with **68 MCP tools**, a liv | Domain | Tools | Data Sources | |--------|-------|-------------| -| **Financial Markets** | 7 | Yahoo Finance, CoinGecko, Polymarket | +| **Financial Markets** | 7 | Yahoo Finance, CoinGecko, Alternative.me, Mempool | +| **Forex & Currency** | 3 | ECB/Frankfurter (8 major pairs, timeseries, cross rates) | +| **Bonds & Yields** | 2 | FRED, Yahoo Finance (yield curve, bond ETFs, spread analysis) | +| **Earnings** | 2 | Yahoo Finance (mega-cap calendar, surprise history) | +| **SEC Filings** | 3 | SEC EDGAR (full-text search, company filings, 8-K material events) | +| **Company Enrichment** | 1 | Yahoo Finance + GDELT + SEC + GitHub (composite profile) | +| **Macro Composite** | 1 | Weighted 6-signal market verdict (Fear&Greed, VIX, sectors, DXY, BTC, yields) | | **Economic Indicators** | 3 | EIA energy, FRED macro, World Bank | -| **Seismology** | 1 | USGS earthquake feeds | -| **Wildfires** | 1 | NASA FIRMS satellite hotspots | -| **Conflict & Security** | 4 | ACLED events, UCDP armed conflict, unrest detection | -| **Military & Defense** | 5 | adsb.lol, OpenSky Network, hexdb.io, surge detection | -| **Infrastructure** | 4 | Cloudflare Radar, submarine cables, cascade analysis, cloud service status | +| **Central Banks** | 1 | 8 central bank policy rates | +| **Natural Disasters** | 2 | USGS earthquakes, NASA FIRMS wildfires | +| **Environmental** | 2 | NASA EONET, GDACS disaster alerts | +| **Conflict & Security** | 4 | ACLED events, UCDP, unrest detection, humanitarian data | +| **Military & Defense** | 6 | adsb.lol, OpenSky, hexdb.io, surge detection, theater posture, aircraft batch | +| **Infrastructure** | 4 | Cloudflare Radar, submarine cables, cascade analysis, cloud status | | **Maritime** | 2 | NGA navigation warnings, vessel snapshots | -| **Geospatial Datasets** | 4 | 70 military bases, 40 ports, 24 pipelines, 24 nuclear facilities | | **Climate** | 1 | Open-Meteo climate anomalies | | **News & Media** | 3 | 80+ RSS feeds (4-tier), GDELT, trending keywords | -| **Intelligence Analysis** | 8 | Signal convergence, focal points, instability index, risk scores, escalation, surge detection | +| **Intelligence Analysis** | 8 | Signal convergence, focal points, instability index, risk scores, escalation | | **Prediction Markets** | 1 | Polymarket event contracts | | **Displacement** | 1 | UNHCR refugee/IDP data | -| **Aviation** | 1 | FAA airport delays | +| **Aviation** | 3 | FAA airport delays, domestic flight snapshot, aircraft batch lookup | | **Cyber Threats** | 1 | URLhaus, Feodotracker, CISA KEV, SANS | | **Space Weather** | 1 | NOAA SWPC (Kp index, solar flares, alerts) | -| **AI/AGI Watch** | 1 | arXiv cs.AI/LG/CL, HuggingFace, newsletters | +| **AI/AGI Watch** | 1 | arXiv cs.AI/LG/CL, HuggingFace, AI lab tracking | | **Health** | 1 | WHO DON, ProMED, CIDRAP disease outbreaks | | **Sanctions** | 1 | US Treasury OFAC SDN list | | **Elections** | 1 | Global election calendar with risk scoring | -| **Shipping** | 1 | Dry bulk ETFs, shipping stress index | +| **Shipping** | 1 | Dry bulk shipping stress index | | **Social** | 1 | Reddit geopolitical discussion velocity | -| **Nuclear** | 1 | USGS seismics near 5 nuclear test sites | -| **Reports** | 3 | Daily brief, country dossier, threat landscape | -| **Cross-Domain Analysis** | 2 | Alert digest, weekly trends | +| **Nuclear** | 1 | USGS seismic monitoring near nuclear test sites | +| **Tech** | 3 | Hacker News, GitHub trending repos, arXiv papers | +| **Government** | 1 | USAspending.gov federal contracts | +| **Geospatial** | 10 | Military bases, ports, pipelines, nuclear facilities, cables, datacenters, spaceports, minerals, exchanges, trade routes, cloud regions, financial centers | | **NLP Intelligence** | 4 | Entity extraction, event classification, news clustering, keyword spikes | | **Strategic Synthesis** | 4 | Strategic posture, world brief, fleet report, population exposure | +| **Cross-Domain** | 2 | Alert digest, weekly trends | -**Total: 68 tools** across 27 intelligence domains. +**Total: 101 tools** across 30+ intelligence domains. --- @@ -54,85 +62,50 @@ Real-time global intelligence across **27 domains** with **68 MCP tools**, a liv ### Install ```bash -# Clone git clone https://github.com/marc-shade/world-intel-mcp.git cd world-intel-mcp - -# Install (Python 3.11+) pip install -e . -# With dashboard support -pip install -e ".[dashboard]" - -# With dev/test tools -pip install -e ".[dev]" +# Optional extras +pip install -e ".[dashboard]" # Live ops-center dashboard +pip install -e ".[dev]" # pytest, respx, coverage ``` ### Run as MCP Server ```bash -# stdio mode (for Claude Code, Cursor, etc.) -world-intel-mcp +world-intel-mcp # stdio mode for Claude Code, Cursor, etc. ``` ### Claude Code Configuration -Add to your `~/.claude.json`: +Add to `~/.claude.json`: ```json { "mcpServers": { "world-intel-mcp": { - "command": "world-intel-mcp", - "env": {} + "command": "world-intel-mcp" } } } ``` -Or if installed in a virtualenv: - -```json -{ - "mcpServers": { - "world-intel-mcp": { - "command": "/path/to/venv/bin/world-intel-mcp", - "env": {} - } - } -} -``` - -### Run the Live Dashboard +### Dashboard ```bash -# Start the ops-center dashboard (default: http://localhost:8501) -intel-dashboard - -# Custom port -intel-dashboard --port 9000 +intel-dashboard # http://localhost:8501 +intel-dashboard --port 9000 # custom port ``` -The dashboard is a map-first ops center with: -- Full-viewport Leaflet map with 7 toggle-able layers (quakes, military, conflict, fires, convergence, nuclear, infrastructure) -- 35+ live data feeds streaming via SSE (30-second refresh) -- 12 expandable drawer sections (alerts, markets, security, intelligence, AI watch, health, elections, shipping, social, nuclear, trends, infrastructure) -- HUD bar with real-time pills (quakes, aircraft, conflict zones, cyber IOCs, fires, displaced persons, Kp index, AI papers, alerts, shipping stress, outbreaks, services) -- Modal detail system — all external links open in-app, all data items expand to rich detail views -- Glassmorphic floating panels with dark-mode styling -- Per-source circuit breaker health monitoring +Map-first ops center: Leaflet map with toggle-able layers (quakes, military, conflict, fires, convergence, nuclear, infrastructure), 35+ live SSE feeds, HUD bar, glassmorphic panels, per-source circuit breaker health. -### CLI Reports +### CLI ```bash -# Daily intelligence brief -intel daily-brief - -# Country dossier -intel country-dossier --country "Ukraine" - -# Threat landscape overview -intel threat-landscape +intel markets # stock indices +intel earthquakes --min-mag 5.0 +intel status # cache + circuit breaker health ``` --- @@ -140,253 +113,209 @@ intel threat-landscape ## Architecture ``` -src/world_intel_mcp/ - server.py # MCP server (stdio) — 64 tool definitions - fetcher.py # Async HTTP client with retries, stale-data fallback - cache.py # SQLite TTL cache with stale-data recovery - circuit_breaker.py # Per-source circuit breakers (3 failures -> 5min cooldown) - cli.py # Click CLI for reports - - sources/ # One module per intelligence domain (25 modules) - markets.py # Stock indices, crypto, stablecoins, ETFs, sectors, commodities - economic.py # Energy prices, FRED macro, World Bank indicators - seismology.py # USGS earthquakes - wildfire.py # NASA FIRMS satellite fire hotspots (9 global regions) - conflict.py # ACLED, UCDP armed conflict events - military.py # adsb.lol + OpenSky military flights, aircraft details - infrastructure.py # Internet outages, submarine cable health, cloud service status - maritime.py # NGA navigation warnings, vessel snapshots - climate.py # Open-Meteo climate anomalies by zone - news.py # 80+ RSS feeds with per-feed circuit breakers, 4-tier source ranking - intelligence.py # GDELT, country briefs, signal convergence, risk scores - prediction.py # Polymarket prediction markets - displacement.py # UNHCR refugee/IDP statistics - aviation.py # FAA airport delays - cyber.py # URLhaus, Feodotracker, CISA KEV, SANS - space_weather.py # NOAA SWPC: Kp index, solar flares, alerts - ai_watch.py # arXiv AI papers, HuggingFace, lab trending - health.py # WHO DON, ProMED, CIDRAP disease outbreaks - sanctions.py # US Treasury OFAC SDN list search - elections.py # Global election calendar with proximity risk scoring - shipping.py # Dry bulk shipping stress index (BDRY, SBLK, EGLE, ZIM) - social.py # Reddit geopolitical discussion velocity - nuclear.py # USGS seismic monitoring near 5 nuclear test sites - geospatial.py # Query wrappers for static geospatial datasets - service_status.py # Cloudflare, AWS, Azure, GCP service health - fleet.py # Naval fleet activity report - - analysis/ # Cross-domain analysis + NLP + strategic synthesis - signals.py # Signal convergence detection - instability.py # Country instability index (CII v2) - focal_points.py # Multi-signal focal point detection - temporal.py # Temporal anomaly detection with SQLite baselines - alerts.py # Cross-domain alert digest + weekly trends - escalation.py # Dynamic hotspot escalation scoring - surge.py # Military surge anomaly detection - cascade.py # Infrastructure cascade simulation - entities.py # Named entity extraction (countries, leaders, orgs, CVEs, APTs) - classifier.py # Keyword-based event threat classification (14 categories) - clustering.py # Jaccard similarity news topic clustering - spikes.py # Keyword spike detection with Welford's algorithm - posture.py # Strategic posture — composite 9-domain risk assessment - world_brief.py # Structured daily intelligence summary - exposure.py # Population exposure near active events - - config/ # Static configuration data - countries.py # 22 intel hotspots, election calendar, nuclear test sites - geospatial.py # 70 military bases, 40 ports, 24 pipelines, 24 nuclear facilities - entities.py # 28 leaders, 41 orgs, 25 companies, 36 APT groups - population.py # 105 major cities (pop >2M) for exposure analysis - - reports/ # Report generation - generator.py # Report orchestrator - markdown_report.py # Markdown output - html_report.py # HTML output (Jinja2 templates) - templates/ # HTML report templates - - dashboard/ # Live ops-center dashboard - app.py # Starlette app with SSE streaming (35+ feeds) - index.html # Map-first dashboard UI (14 map layers, 20+ drawer sections) - - tests/ # Test suite - conftest.py # Shared fixtures (mock fetcher, circuit breaker) - test_sources.py # Source module tests - test_cache.py # Cache TTL tests - test_analysis.py # Analysis engine tests +server.py (MCP stdio) ─┐ +cli.py (Click CLI) ├─> sources/*.py ─> Fetcher ─> CircuitBreaker ─> Cache (SQLite) +dashboard/app.py (SSE) ─┘ analysis/*.py │ + ~/.cache/world-intel-mcp/cache.db ``` -### Circuit Breakers - -Every external API call goes through a circuit breaker. After 3 consecutive failures, the source is "tripped" for 5 minutes, preventing cascading timeouts. Each RSS feed gets its own breaker (e.g., `rss:bbc_world`, `rss:ars_technica`), so a single broken feed doesn't kill all news. - -### Data Flow - -``` -External APIs -> Fetcher (httpx + retries) -> Circuit Breaker -> Cache (TTL) -> MCP Tool Response - -> Dashboard (SSE) - -> CLI Report -``` +- **Fetcher**: Centralized async HTTP client (httpx). Retries, per-source rate limiting, stale-data fallback. +- **CircuitBreaker**: Per-source tracking. 3 consecutive failures trips for 5 minutes. Each RSS feed gets its own breaker. +- **Cache**: SQLite WAL-mode TTL cache. `get()` returns live data, `get_stale()` returns expired data for fallback. +- **Sources** (`sources/*.py`): 30+ modules, each exports `async def fetch_*(fetcher, **kwargs) -> dict`. +- **Analysis** (`analysis/*.py`): Cross-domain synthesis — signal aggregation, instability indexing, NLP, company enrichment, macro composite. +- **Config** (`config/*.py`): Curated datasets — 22 hotspots, 70+ bases, 40 ports, 24 pipelines, 24 nuclear facilities, 34 cables, 48 datacenters, 27 spaceports, 82 exchanges. --- ## MCP Tools Reference -### Financial Markets (7 tools) +### Financial Markets (7) | Tool | Description | |------|-------------| | `intel_market_quotes` | Stock index quotes (S&P 500, Dow, Nasdaq, FTSE, Nikkei) | | `intel_crypto_quotes` | Top crypto prices and market caps from CoinGecko | | `intel_stablecoin_status` | Stablecoin peg health (USDT, USDC, DAI, FDUSD) | -| `intel_etf_flows` | Bitcoin spot ETF prices and volumes (IBIT, FBTC, GBTC, ARKB) | -| `intel_sector_heatmap` | US equity sector performance (11 SPDR sector ETFs) | -| `intel_macro_signals` | Macro indicators (Fear & Greed, VIX, DXY, gold, 10Y, BTC mempool) | -| `intel_commodity_quotes` | Commodity futures (gold, silver, crude oil, natural gas) | +| `intel_etf_flows` | Bitcoin spot ETF prices and volumes | +| `intel_sector_heatmap` | US equity sector performance (11 SPDR ETFs) | +| `intel_macro_signals` | 7 macro indicators (Fear & Greed, VIX, DXY, gold, 10Y, BTC) | +| `intel_commodity_quotes` | Commodity futures (gold, silver, crude, natgas, grains) | -### Economic (3 tools) +### Forex & Currency (3) +| Tool | Description | +|------|-------------| +| `intel_forex_rates` | Latest FX rates from ECB. Filter by base/target currencies | +| `intel_forex_timeseries` | Historical FX rate with trend analysis (configurable days) | +| `intel_major_crosses` | All 8 major pairs + cross rates + DXY proxy | + +### Bonds & Yields (2) +| Tool | Description | +|------|-------------| +| `intel_yield_curve` | US Treasury yield curve (2Y-30Y), 2s10s/3m10y spreads, inversion flag | +| `intel_bond_indices` | Bond ETFs: AGG, TLT, HYG, LQD, TIP with price/change | + +### Earnings (2) +| Tool | Description | +|------|-------------| +| `intel_earnings_calendar` | Upcoming earnings for 20 mega-cap stocks with EPS estimates | +| `intel_earnings_surprise` | Historical earnings surprise (actual vs estimate, trend) | + +### SEC Filings (3) +| Tool | Description | +|------|-------------| +| `intel_sec_filings` | Full-text search across all EDGAR filings | +| `intel_company_filings` | Company filings by ticker (10-K, 10-Q, 8-K) with CIK resolution | +| `intel_recent_8k` | Latest 8-K material events (M&A, exec changes, earnings) | + +### Company Enrichment (1) +| Tool | Description | +|------|-------------| +| `intel_company_profile` | Composite profile: stock quote + financials + news + SEC + GitHub | + +### Macro Composite (1) +| Tool | Description | +|------|-------------| +| `intel_macro_composite` | Weighted market score (0-100) with verdict: RISK_ON to STRONG_CAUTION | + +### Economic (3) | Tool | Description | |------|-------------| | `intel_energy_prices` | Brent/WTI crude oil and natural gas from EIA | -| `intel_fred_series` | FRED economic data series (GDP, CPI, unemployment, rates) | +| `intel_fred_series` | FRED economic data (GDP, CPI, unemployment, rates) | | `intel_world_bank_indicators` | World Bank development indicators by country | -### Natural Disasters (2 tools) +### Central Banks (1) | Tool | Description | |------|-------------| -| `intel_earthquakes` | Recent earthquakes from USGS (configurable magnitude/time) | +| `intel_central_bank_rates` | Policy rates for 8 major central banks | + +### BTC Technicals (1) +| Tool | Description | +|------|-------------| +| `intel_btc_technicals` | Bitcoin SMA 50/200, golden/death cross, Mayer Multiple | + +### Natural Disasters (2) +| Tool | Description | +|------|-------------| +| `intel_earthquakes` | USGS earthquakes (configurable magnitude/time/limit) | | `intel_wildfires` | NASA FIRMS satellite fire hotspots (9 global regions) | -### Security & Conflict (4 tools) +### Environmental (2) | Tool | Description | |------|-------------| -| `intel_acled_events` | Armed conflict events from ACLED | +| `intel_environmental_events` | NASA EONET natural events | +| `intel_disaster_alerts` | GDACS disaster alerts with severity scoring | + +### Conflict & Security (4) +| Tool | Description | +|------|-------------| +| `intel_acled_events` | ACLED armed conflict events | | `intel_ucdp_events` | Uppsala Conflict Data Program events | -| `intel_unrest_events` | Social unrest (protests + riots) with Haversine dedup | -| `intel_cyber_threats` | Aggregated cyber intel (URLhaus, Feodotracker, CISA KEV, SANS) | +| `intel_unrest_events` | Social unrest with Haversine dedup | +| `intel_humanitarian_summary` | HDX humanitarian crisis datasets | -### Military & Defense (5 tools) +### Military & Defense (6) | Tool | Description | |------|-------------| -| `intel_military_flights` | Military aircraft via adsb.lol (fallback: OpenSky) | -| `intel_theater_posture` | Military activity across 5 theaters (EU, Indo-Pacific, ME, Arctic, Korea) | -| `intel_aircraft_details` | Aircraft lookup by ICAO24 hex code (hexdb.io) | +| `intel_military_flights` | Military aircraft via adsb.lol (OpenSky fallback) | +| `intel_theater_posture` | Activity across 5 theaters (EU, Indo-Pacific, ME, Arctic, Korea) | +| `intel_aircraft_details` | Aircraft lookup by ICAO24 hex (hexdb.io) | +| `intel_aircraft_batch` | Batch aircraft lookup (multiple hex codes) | | `intel_military_surge` | Foreign aircraft concentration anomaly detection | -| `intel_military_bases` | Query 70 military bases from 9 operators (USA, RUS, CHN, GBR, FRA, NATO, IND, TUR, ISR) | +| `intel_usni_fleet` | USNI News naval fleet tracker | -### Infrastructure (4 tools) +### Infrastructure (4) | Tool | Description | |------|-------------| | `intel_internet_outages` | Cloudflare Radar internet disruptions | -| `intel_cable_health` | Submarine cable corridor health (6 corridors) | -| `intel_cascade_analysis` | Infrastructure cascade simulation ("what if corridor X fails?") | -| `intel_service_status` | Cloud platform health (Cloudflare, AWS, Azure, GCP) | +| `intel_cable_health` | Submarine cable corridor health | +| `intel_cascade_analysis` | Infrastructure cascade simulation | +| `intel_service_status` | Cloud platform health (AWS, Azure, GCP, Cloudflare, GitHub) | -### Maritime (2 tools) +### Maritime (2) | Tool | Description | |------|-------------| -| `intel_nav_warnings` | Maritime navigation warnings from NGA | +| `intel_nav_warnings` | NGA maritime navigation warnings | | `intel_vessel_snapshot` | Naval activity at 9 strategic waterways | -### Geospatial Datasets (4 tools) +### Geospatial Datasets (10) | Tool | Description | |------|-------------| -| `intel_military_bases` | 70 military bases from 9 operators — filter by operator, country, type, branch | -| `intel_strategic_ports` | 40 strategic ports across 6 types — filter by type, country | -| `intel_pipelines` | 24 oil/gas/hydrogen pipelines — filter by type, status | -| `intel_nuclear_facilities` | 24 nuclear power/enrichment/research facilities — filter by type, country, status | +| `intel_military_bases` | 70 military bases from 9 operators | +| `intel_strategic_ports` | 40 strategic ports across 6 types | +| `intel_pipelines` | 24 oil/gas/hydrogen pipelines | +| `intel_nuclear_facilities` | 24 nuclear power/enrichment/research facilities | +| `intel_undersea_cables` | 34 submarine communications cables | +| `intel_ai_datacenters` | 48 AI/HPC datacenters worldwide | +| `intel_spaceports` | 27 global spaceports | +| `intel_critical_minerals` | 27 strategic mineral deposits | +| `intel_stock_exchanges` | 82 stock exchanges worldwide | +| `intel_trade_routes` | Major trade routes and chokepoints | -### News & Media (3 tools) +### News & Media (3) | Tool | Description | |------|-------------| -| `intel_news_feed` | Aggregated news from 80+ global RSS feeds with 4-tier source ranking | +| `intel_news_feed` | 80+ global RSS feeds with 4-tier source ranking | | `intel_trending_keywords` | Trending terms with spike detection | -| `intel_gdelt_search` | GDELT 2.0 global news search and timelines | +| `intel_gdelt_search` | GDELT 2.0 global news search | -### Geopolitical (2 tools) -| Tool | Description | -|------|-------------| -| `intel_prediction_markets` | Polymarket prediction contract prices | -| `intel_election_calendar` | Global election calendar with proximity risk scoring | - -### Humanitarian (2 tools) -| Tool | Description | -|------|-------------| -| `intel_displacement_summary` | UNHCR refugee/IDP statistics by country | -| `intel_humanitarian_summary` | HDX humanitarian crisis datasets | - -### Environment & Space (2 tools) -| Tool | Description | -|------|-------------| -| `intel_climate_anomalies` | Temperature/precipitation anomalies (15 global zones) | -| `intel_space_weather` | Solar activity: Kp index, X-ray flux, SWPC alerts | - -### Health & Social (3 tools) -| Tool | Description | -|------|-------------| -| `intel_disease_outbreaks` | WHO DON, ProMED, CIDRAP outbreak alerts | -| `intel_social_signals` | Reddit geopolitical discussion velocity | -| `intel_sanctions_search` | US Treasury OFAC SDN list search | - -### AI/AGI Research (1 tool) -| Tool | Description | -|------|-------------| -| `intel_ai_releases` | arXiv AI papers, HuggingFace models, lab tracking | - -### Shipping & Transport (2 tools) -| Tool | Description | -|------|-------------| -| `intel_shipping_index` | Dry bulk shipping stress index (BDRY, SBLK, EGLE, ZIM) | -| `intel_airport_delays` | FAA airport delay status (20 major US airports) | - -### Nuclear (1 tool) -| Tool | Description | -|------|-------------| -| `intel_nuclear_monitor` | Seismic monitoring near 5 nuclear test sites | - -### Intelligence Analysis (8 tools) +### Intelligence Analysis (8) | Tool | Description | |------|-------------| | `intel_signal_convergence` | Geographic convergence of multi-domain signals | -| `intel_focal_points` | Multi-signal focal point detection on entities | -| `intel_signal_summary` | Country-level signal aggregation with convergence scoring | -| `intel_temporal_anomalies` | Activity deviations from historical baselines | -| `intel_instability_index` | Country Instability Index v2 (0-100, 4 weighted domains) | -| `intel_risk_scores` | ACLED-based conflict risk scoring vs baselines | -| `intel_hotspot_escalation` | Dynamic escalation scores for 22 intel hotspots | -| `intel_military_surge` | Foreign aircraft concentration anomaly detection | +| `intel_focal_points` | Multi-signal focal point detection | +| `intel_signal_summary` | Country-level signal aggregation | +| `intel_temporal_anomalies` | Activity deviations from baselines | +| `intel_instability_index` | Country Instability Index v2 (0-100) | +| `intel_risk_scores` | ACLED-based conflict risk scoring | +| `intel_hotspot_escalation` | Escalation scores for 22 intel hotspots | +| `intel_country_dossier` | Comprehensive country intelligence dossier | -### NLP Intelligence (4 tools) +### NLP Intelligence (4) | Tool | Description | |------|-------------| -| `intel_extract_entities` | Named entity extraction: countries, leaders, orgs, companies, CVEs, APT groups | -| `intel_classify_event` | Event classification into 14 threat categories with severity scoring (1-10) | -| `intel_news_clusters` | Topic clustering of news articles by Jaccard similarity with keyword extraction | -| `intel_keyword_spikes` | Keyword spike detection against baselines with CVE/APT mention extraction | +| `intel_extract_entities` | Named entity extraction (countries, leaders, orgs, CVEs, APTs) | +| `intel_classify_event` | Event classification into 14 threat categories | +| `intel_news_clusters` | Topic clustering by Jaccard similarity | +| `intel_keyword_spikes` | Keyword spike detection with Welford's algorithm | -### Strategic Synthesis (4 tools) +### Strategic Synthesis (4) | Tool | Description | |------|-------------| -| `intel_strategic_posture` | Composite global risk from 9 weighted domains (military, political, conflict, infrastructure, economic, cyber, health, climate, space) | -| `intel_world_brief` | Structured daily intelligence summary: risk overview, focal areas, top stories, anomalies, trending threats | -| `intel_fleet_report` | Naval fleet activity: theater posture, waterway status, surge detections, readiness scoring | -| `intel_population_exposure` | Population at risk near active earthquakes, wildfires, and conflict (105-city dataset, 1B pop coverage) | +| `intel_strategic_posture` | Composite global risk from 9 weighted domains | +| `intel_world_brief` | Structured daily intelligence summary | +| `intel_fleet_report` | Naval fleet activity report with readiness scoring | +| `intel_population_exposure` | Population at risk near active events (105-city dataset) | -### Cross-Domain Alerts (2 tools) +### Other Domains | Tool | Description | |------|-------------| -| `intel_alert_digest` | Aggregated alerts from 7 intelligence sources | -| `intel_weekly_trends` | Weekly trend analysis from temporal baselines | - -### Reports (3 tools) -| Tool | Description | -|------|-------------| -| `intel_daily_brief` | Daily intelligence briefing (HTML report) | -| `intel_country_dossier` | Comprehensive country intelligence report | -| `intel_threat_landscape` | Current threat landscape overview | - -### System (2 tools) -| Tool | Description | -|------|-------------| -| `intel_country_brief` | Quick country situation summary (Ollama LLM) | +| `intel_prediction_markets` | Polymarket prediction contracts | +| `intel_election_calendar` | Global election calendar with risk scoring | +| `intel_displacement_summary` | UNHCR refugee/IDP statistics | +| `intel_airport_delays` | FAA airport delay status | +| `intel_aviation_domestic` | Global air traffic snapshot from OpenSky | +| `intel_cyber_threats` | Aggregated cyber intel (URLhaus, CISA KEV, SANS) | +| `intel_space_weather` | Solar activity (Kp index, X-ray flux, SWPC alerts) | +| `intel_ai_releases` | arXiv AI papers, HuggingFace models | +| `intel_disease_outbreaks` | WHO DON, ProMED, CIDRAP outbreaks | +| `intel_social_signals` | Reddit geopolitical discussion velocity | +| `intel_sanctions_search` | OFAC SDN list search | +| `intel_shipping_index` | Dry bulk shipping stress index | +| `intel_nuclear_monitor` | Seismic monitoring near nuclear test sites | +| `intel_hacker_news` | Hacker News top stories | +| `intel_trending_repos` | GitHub trending repositories | +| `intel_arxiv_papers` | arXiv paper search | +| `intel_usa_spending` | USAspending.gov federal contracts | +| `intel_country_brief` | Quick country situation summary | +| `intel_country_stocks` | Stock exchanges and listings by country | +| `intel_cloud_regions` | Cloud provider regions worldwide | +| `intel_financial_centers` | Global financial centers ranking | +| `intel_alert_digest` | Cross-domain alert aggregation | +| `intel_weekly_trends` | Weekly trend analysis | +| `intel_traffic_flow` | Road traffic flow data | +| `intel_traffic_incidents` | Real-time traffic incidents | +| `intel_webcams` | Public webcam locations and live previews | | `intel_status` | Server health, cache stats, circuit breaker status | --- @@ -395,43 +324,35 @@ External APIs -> Fetcher (httpx + retries) -> Circuit Breaker -> Cache (TTL) -> | Variable | Required | Description | |----------|----------|-------------| -| `ACLED_ACCESS_TOKEN` | No | ACLED API token (enables conflict event data) | -| `NASA_FIRMS_API_KEY` | No | NASA FIRMS key (enables satellite wildfire data) | -| `EIA_API_KEY` | No | EIA key (enables energy price data) | -| `CLOUDFLARE_API_TOKEN` | No | Cloudflare Radar (enables internet outage data) | -| `FRED_API_KEY` | No | FRED key (enables macro economic data) | -| `OPENSKY_CLIENT_ID` | No | OpenSky Network credentials (military flight fallback) | -| `OPENSKY_CLIENT_SECRET` | No | OpenSky Network credentials (military flight fallback) | +| `ACLED_ACCESS_TOKEN` | No | ACLED conflict events | +| `NASA_FIRMS_API_KEY` | No | Satellite wildfire data | +| `EIA_API_KEY` | No | Energy price data | +| `CLOUDFLARE_API_TOKEN` | No | Internet outage data | +| `FRED_API_KEY` | No | Macro economic data (also used for yield curve) | +| `OPENSKY_CLIENT_ID` | No | Military flight fallback | +| `OPENSKY_CLIENT_SECRET` | No | Military flight fallback | | `WORLD_INTEL_LOG_LEVEL` | No | Logging level (default: INFO) | -All other data sources (CoinGecko, USGS, adsb.lol, UCDP, NGA, FAA, Polymarket, UNHCR, NOAA SWPC, arXiv, Reddit, hexdb.io, WHO, OFAC, etc.) use free, unauthenticated public APIs. +Everything else uses free, unauthenticated public APIs. --- ## Development ```bash -# Install dev dependencies pip install -e ".[dev]" - -# Run tests -pytest - -# Run with coverage -pytest --cov=world_intel_mcp - -# Type checking (if configured) -mypy src/ +pytest # 186 tests +pytest --cov=world_intel_mcp # with coverage +pytest tests/test_forex.py -v # single module ``` ### Adding a New Source -1. Create `src/world_intel_mcp/sources/your_source.py` -2. Implement `async def fetch_your_data(fetcher: Fetcher, **kwargs) -> dict` -3. Use `fetcher.get_json()` / `fetcher.get_xml()` for HTTP calls (includes caching + circuit breakers) -4. Import in `server.py`, add a `Tool` definition, and wire up the `call_tool` handler -5. Add to `dashboard/app.py` if you want it on the live dashboard -6. Add tests in `tests/` +1. Create `sources/your_source.py` with `async def fetch_your_data(fetcher: Fetcher, **kwargs) -> dict` +2. Use `fetcher.get_json(url, source="your-source", cache_key=..., cache_ttl=300)` — automatic caching, retries, circuit breaking, rate limiting +3. In `server.py`: add `Tool(...)` to `TOOLS`, add `case` to `_dispatch()` (use inline import) +4. Add tests using `respx` to mock HTTP (see `tests/test_forex.py` for pattern) +5. Optionally add to `dashboard/app.py` (SSE) and `cli.py` (Click) ---