Daedal Map MCP Server

DaedalMap

DaedalMap is a map-first geographic query engine. It lets people ask place-based questions in natural language and get usable map results across disasters, demographics, economics, climate, and related public data.

Public surfaces:

• App: https://app.daedalmap.com
• Website/docs: https://daedalmap.com

This repository is the open app/runtime. It is intended to be understandable and usable on its own: you can run it locally, point it at local or hosted data, and extend it with compatible datasets and pack-style workflows.

If you are using the public GitHub repo as a self-host/local runtime, the practical setup contract right now is:

• a local data location (DATA_ROOT, unless you use the default app-data path)
• an LLM API key (OPENAI_API_KEY or ANTHROPIC_API_KEY)

Supabase and hosted account wiring are optional for self-host use.

What It Does

DaedalMap is built around three ideas:

• ask in plain language instead of assembling GIS workflows first
• keep the map as the primary interface, not an afterthought
• separate runtime delivery from maintained data-pack delivery

Typical use cases:

• show earthquakes, floods, wildfires, storms, volcanoes, or tsunamis for a place and time window
• compare population, economic, and disaster context in the same workflow
• move between hosted demo use, account-linked runtime access, and local/self-hosted operation without changing the basic mental model

Data Coverage

The hosted runtime ships with 40+ curated sources across disasters, demographics, economics, and climate. Coverage below reflects the current maintained pack inventory.

Global Disasters

Disaster events include 22M+ geographic location relationships and 566K cross-disaster links (aftershocks, triggered events).

Global Indicators

Country-Specific Sources

Disaster Display

Disasters are displayed with animated, type-specific rendering:

• Point + radius: earthquakes, volcanoes, tornadoes
• Track/trail: hurricanes and cyclones
• Radial wave: tsunamis
• Polygon fill: wildfires, floods

Current Runtime Shape

DaedalMap now treats runtime behavior as a 2-axis matrix:

• INSTALL_MODE
  • local = local app/runtime install
  • cloud = hosted/server deployment
• RUNTIME_MODE
  • local = query local data
  • cloud = query managed cloud-backed data via local cache + DuckDB httpfs

Supported combinations:

• local install + local data
• local install + cloud data
• cloud install + cloud data

Not supported as a first-class runtime shape:

• cloud install + local data

The current hosted/runtime direction is:

• Railway for the public app runtime
• Cloudflare R2 for canonical runtime data storage
• Supabase for auth and the future entitlement/control plane

In RUNTIME_MODE=cloud, the runtime:

• eagerly syncs only small metadata files to local cache
• queries parquet directly from object storage via DuckDB httpfs
• does not sync the full parquet tree at startup
• should point at the released published/ namespace, not the mutable review lane

Admin/review surfaces may also read release markers from a separate control/ prefix so admin accounts can still see staging/review pack status even when the runtime catalog in published/ is empty.

That means the same codebase can be used in:

• full local-data mode
• hosted-style cloud-data mode

Guest And Logged-In Behavior

Guest users can open the app and try the public workflow without logging in.

Logged-in users currently get:

• authenticated session identity
• user-scoped frontend persistence
• user-scoped backend session cache
• account-owned settings and login on daedalmap.com

The public app no longer owns the account/settings UI. app.daedalmap.com stays focused on the runtime and map engine, while .com owns login, account, billing, and admin/runtime control-plane views.

Quick Start

1. Install dependencies

cd county-map
pip install -r requirements.txt

2. Add environment variables

Create a .env file for local development. The minimum useful local setup is:

ANTHROPIC_API_KEY=your_key_here
DATA_ROOT=C:/path/to/your/local/data

You can use OPENAI_API_KEY instead of ANTHROPIC_API_KEY if that is your preferred provider. If you leave DATA_ROOT blank, DaedalMap uses the default local app-data path and expects your data to live there.

If you want to test the hosted-style setup locally, also configure:

INSTALL_MODE=local
RUNTIME_MODE=cloud
S3_BUCKET=global-map-data
S3_PREFIX=published
S3_CONTROL_PREFIX=control
S3_ENDPOINT_URL=https://<account>.r2.cloudflarestorage.com
API_ANALYTICS_IP_SALT=<stable-random-secret>
ORDER_TAKER_SOURCE_MODE=live
HOSTED_PACK_REF_ALLOWED_HOSTS=<exact-download-hosts>
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=auto

For local testing against the review lane before publish, use:

INSTALL_MODE=local
RUNTIME_MODE=cloud
S3_BUCKET=global-map-data
S3_PREFIX=staging
S3_CONTROL_PREFIX=control
S3_ENDPOINT_URL=https://<account>.r2.cloudflarestorage.com
API_ANALYTICS_IP_SALT=<stable-random-secret>
ORDER_TAKER_SOURCE_MODE=live
HOSTED_PACK_REF_ALLOWED_HOSTS=<exact-download-hosts>
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=auto

Most local users should leave these blank unless they intentionally want overrides:

DATA_ROOT=
APP_URL=
SITE_URL=
CLOUD_CACHE_ROOT=

What they mean:

• DATA_ROOT only used in RUNTIME_MODE=local; leave blank to use the default local app-data folder
• APP_URL optional advertised app URL; leave blank for normal local runs
• SITE_URL optional website/docs/account URL override; leave blank for normal local runs
• CLOUD_CACHE_ROOT optional local cache folder for cloud metadata/support files; leave blank unless you want a custom cache location

If you are configuring a hosted deployment, set:

INSTALL_MODE=cloud
RUNTIME_MODE=cloud
PORT=7000

If you want optional hosted-style auth locally:

SUPABASE_URL=...
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_KEY=...

3. Run the app

python app.py

Open:

• http://localhost:7000

Agent and MCP Integration

DaedalMap exposes a discovery and query API intended for agent and LLM use. The same endpoints are accessible via MCP for direct integration with Claude and other MCP-compatible clients.

Discovery endpoints are free. Data query endpoints use per-call micropayment via x402.

The MCP surface exposes:

• catalog discovery (list available packs)
• pack inspection (schema, coverage, metrics for a given pack)
• dataset query (paid, returns structured data for an agent to reason over)

For MCP setup details, see docs/LOCAL_AND_HOSTED.md.

API First Steps

If you are approaching this repo like a new developer, the current API entry path is:

1. read the free guide at GET /api/v1/guide
2. list packs at GET /api/v1/catalog
3. inspect one pack at GET /api/v1/packs/{pack_id}
4. make a paid data call with POST /api/v1/query/dataset

The free exploration surface is:

• GET /api/v1/guide
• GET /api/v1/catalog
• GET /api/v1/packs/{pack_id}

The first paid execution surface is:

• POST /api/v1/query/dataset

Important current behavior:

• the free discovery endpoints are readable without payment
• POST /api/v1/query/dataset is a paid lane
• the current live agent/API discovery rollout includes currency and earthquakes
• local or self-host runs return commercial_access_unavailable for that paid lane unless a commercial verifier is explicitly enabled
• the hosted x402 test client lives at docs/X402_TEST_CLIENT.md

Current live pricing model for POST /api/v1/query/dataset:

• base price: $0.01
• rows included in base price: 100
• per-row fee above 100 rows: $0.0001
• max single-call price: $0.50

How to think about it:

• the free discovery endpoints stay free
• the first paid lane computes price from the requested limit
• the x402 payment-required challenge confirms the computed amount before you pay
• use a small limit for the first paid test so you can confirm the flow cheaply

Worked examples:

• limit = 30 -> $0.01
• limit = 100 -> $0.01
• limit = 365 -> $0.0365
• limit = 500 -> $0.05

Quick live exploration examples:

Invoke-WebRequest -UseBasicParsing 'https://app.daedalmap.com/api/v1/guide'
Invoke-WebRequest -UseBasicParsing 'https://app.daedalmap.com/api/v1/catalog'
Invoke-WebRequest -UseBasicParsing 'https://app.daedalmap.com/api/v1/packs/currency'
Invoke-WebRequest -UseBasicParsing 'https://app.daedalmap.com/api/v1/packs/earthquakes'

Current live expectation:

• GET /api/v1/catalog returns two packs: currency and earthquakes
• GET /api/v1/packs/currency returns 200
• GET /api/v1/packs/earthquakes returns 200

Current live pair:

• currency: normalized FX metrics with pack-level routing by time.granularity
• earthquakes: event-source pack with hierarchy-aware region_ids and backend-aggregated event_count

Data Resolution

The runtime resolves behavior from two explicit modes:

1. INSTALL_MODE controls deployment defaults like writable directories and default URLs
2. RUNTIME_MODE controls the data plane

Data mode behavior:

1. RUNTIME_MODE=local uses DATA_ROOT
2. RUNTIME_MODE=cloud uses the hydrated local cloud cache as DATA_ROOT

Default local writable folders on Windows:

• CONFIG_DIR=%LOCALAPPDATA%\DaedalMap\config
• STATE_DIR=%LOCALAPPDATA%\DaedalMap\state
• CACHE_DIR=%LOCALAPPDATA%\DaedalMap\cache
• LOG_DIR=%LOCALAPPDATA%\DaedalMap\logs
• PACKS_ROOT=%LOCALAPPDATA%\DaedalMap\packs
• DATA_ROOT=%LOCALAPPDATA%\DaedalMap\data

In hosted/cloud mode:

• metadata is cached locally
• parquet is queried remotely from object storage

That makes local cloud-mode testing useful for reproducing hosted-runtime behavior before deploy.

Important note:

• the current public repo does not include a bundled data/ demo tree
• a source checkout therefore needs either DATA_ROOT in local mode, or RUNTIME_MODE=cloud with cloud storage configured
• for a usable chat experience, you should also set OPENAI_API_KEY or ANTHROPIC_API_KEY

Data And Pack Direction

The old “demo data folder plus converters” framing is no longer the whole story.

The current direction is:

• the engine stays open
• maintained data is packaged as packs
• packs are validated and promoted with explicit release gates
• runtime catalogs eventually depend on pack availability, installation, and entitlement state

Key concepts:

• available packs
• installed packs
• entitled packs
• active runtime catalog

These are intentionally distinct.

Settings Page

/settings now behaves differently depending on mode:

• hosted/account-aware mode: redirects to the paired account surface
• self-host/local mode: shows local runtime setup guidance

For self-host users, /settings is the in-app reminder page for:

• required LLM key setup
• current runtime/data/config paths
• the current state of local data vs future pack install flow

Useful Paths In This Repo

Important files and folders:

• app.py - FastAPI app entrypoint
• mapmover/ - runtime logic, routes, path helpers, DuckDB helpers
• static/ - frontend app modules and styles
• templates/ - app HTML shell
• supabase_client.py - auth/control-plane integration
• docs/ - local documentation for schemas, runtime notes, and reference material

Documentation In This Repo

Current docs in docs/:

• docs/LOCAL_AND_HOSTED.md - start here for runtime mode selection and self-host basics
• docs/APP_OVERVIEW.md - current runtime/app overview
• docs/DATA_SCHEMAS.md - schema and loc_id conventions
• docs/public reference.md - source/licensing reference notes

Suggested reading order:

1. README.md
2. docs/LOCAL_AND_HOSTED.md
3. docs/APP_OVERVIEW.md
4. docs/DATA_SCHEMAS.md

Local Development Modes

Useful local modes:

1. Full local-data mode

• points at your local DATA_ROOT
• best current self-host mode for GitHub users

1. Hosted-style S3 mode

• local server, but object-storage-backed data path
• best for reproducing hosted runtime behavior before deploy

1. Installed/runtime-pack mode

• planned product direction beyond raw source checkout
• engine/runtime installed separately from data packs
• pack selection and updates handled outside the repo clone flow

Contact

Questions, feedback, or self-host issues: support@daedalmap.com

License

MIT

---

Agent/API access: https://daedalmap.com/llms.txt