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.
Contributing
Thanks for taking a look at world-intel-mcp. This is a small project; the bar is "does it work and does it fit the existing patterns," not process.
Dev setup
git clone https://github.com/marc-shade/world-intel-mcp.git
cd world-intel-mcp
pip install -e ".[dev]"
[dev] pulls in pytest, pytest-asyncio, pytest-cov, and respx. If
you're touching the dashboard or the PDF report, also grab
.[dashboard] or .[pdf].
Running tests
pytest # full suite, live-network smoke tests deselected
pytest --cov=world_intel_mcp # with coverage
pytest src/world_intel_mcp/tests/test_forex.py -v # single module
pytest -m smoke # the live-network tests, opt-in only
Tests mock HTTP with respx, so nothing in the default run touches the
network. Fixtures in conftest.py (cache, fetcher) give you a clean
SQLite tmp-path cache and a fetcher with a fresh circuit breaker per test.
Adding a new data source
This is the most common kind of PR, so here's the full recipe:
- Create
sources/your_source.pywith:async def fetch_your_data(fetcher: Fetcher, **kwargs) -> dict: ... - Fetch through
fetcher.get_json(url, source="your-source", cache_key=..., cache_ttl=300)(orget_text/get_xml). Never construct your ownhttpxclient: this is what gives you caching, retries, circuit breaking, and rate limiting for free. - Wire it into
server.py: add aTool(...)entry toTOOLSand a matchingcasein_dispatch()(inline-import the source module there, following the existing cases). - Write a test with
respxmocking the HTTP call.tests/test_forex.pyis a clean example of the pattern (success, empty response, error, cache-hit cases). - Optional but appreciated: add the source to
dashboard/app.py's SSEsource_defsand tocli.pyas a Click command, so it shows up in the live dashboard and the CLI, not just the MCP tool list. - If your tool count or feed count changes anything documented in
README.md(the domain table, the tools reference, the architecture totals), update those numbers in the same PR. Stale counts are exactly what got filed as bugs before.
Before opening a PR
pytestpasses locally (the CI matrix runs 3.11 and 3.12; if you have only one installed, that's fine, CI will catch the other).- New source functions have a test.
- No new hardcoded personal paths, hostnames, or machine-specific defaults
(see
sources/*.pyfor the pattern: everything configurable comes from an env var with a sane public default). - Keep the PR scoped to one thing. Bundling an unrelated formatting pass with a feature change makes it hard to review either one.
There's no linter configured in this repo on purpose. Don't add one as a drive-by in an unrelated PR; that's its own decision.
Dependencies
pyproject.toml is the single source of dependency truth. There is no
requirements.txt; don't add one back as a "quick pin" without also
wiring it into CI, or it will drift again.