{
  "markdown": "# DaedalMap\n\n## Use it as a hosted MCP server (no setup)\n\nMost callers do not need to run anything. DaedalMap is a live remote MCP server\nand HTTP API for making geographic references interoperable:\n\n- MCP endpoint: `https://app.daedalmap.com/mcp` (streamable HTTP)\n- Start with `help` for guided onboarding, then use the free geography tools to\n  identify reference systems, transform coordinates or boundaries, build\n  crosswalks, and assign stable `loc_id` values\n- Bring your own data, make its geography `loc_id` compatible, and join it to\n  other prepared data or DaedalMap's maintained data packs\n- Download geometry and work locally, call the hosted MCP, or self-host this\n  open runtime\n- Discover current data packs with `get_catalog` and current geometry coverage\n  with `read_geometry_catalog`; coverage can grow without changing the MCP entry\n  point or workflow\n- Some execution lanes are free and licensed commercial lanes challenge through\n  x402 before any charge\n- Agent docs: `https://daedalmap.com/docs/for-agents`\n\nThe rest of this README is the self-host / local-runtime path.\n\n---\n\nDaedalMap is a map-first geographic query engine. This repository is the open app/runtime for developers who want to run it locally, self-host it, point it at their own data, or extend it with compatible geographic datasets.\n\nPublic surfaces:\n- App: `https://app.daedalmap.com`\n- Website/docs: `https://daedalmap.com`\n\nThere are now two valid ways to approach DaedalMap locally:\n\n- `GitHub/self-host path`\n  - use this repo directly\n  - best for developers, custom data work, and users who want to control setup\n- `Downloadable launcher path`\n  - curated wrapper + engine artifact + pack install flow\n  - best for users who want the same runtime with less setup friction\n\nThese should stay the same product at the runtime/contract level, but they do\nnot need identical UI on every surface.\n\nIf you are using this public GitHub repo as a self-host/local runtime, the practical setup contract right now is:\n- a local data location (`DATA_ROOT`, unless you use the default app-data path)\n- optionally, an LLM API key for the built-in local chat UI\n\nHosted account wiring and private verifier endpoints are optional\nfor self-host use. Hosted collector scheduling and scheduled-jobs hosts such as\nthe private DigitalOcean nightly box are not part of this public repo.\n\n## What This Repo Is For\n\nUse this repo if you want to:\n- run the DaedalMap runtime on your own machine or server\n- point the runtime at local data or a cloud-backed data plane you control\n- inspect or extend the open runtime behavior\n- build compatible geographic datasets and pack-style workflows around the engine\n\nTypical use cases:\n- show earthquakes, floods, wildfires, storms, volcanoes, or tsunamis for a place and time window\n- compare population, economic, and disaster context in the same workflow\n- move between local development, self-hosted runtime operation, and hosted-style runtime behavior without changing the basic mental model\n\nDaedalMap itself is built around three ideas:\n- ask in plain language instead of assembling GIS workflows first\n- keep the map as the primary interface, not an afterthought\n- separate runtime delivery from maintained data-pack delivery\n\nThis repo is therefore best read as:\n\n- the open runtime engine\n- the self-host/developer entry point\n- the source of truth for the downloadable engine snapshot users install through\n  the launcher\n\nIt is not the hosted account, billing, or admin surface. Those product surfaces\nare separate from the public runtime and may evolve faster than the\ndownloadable runtime UI.\n\n## Choosing A Local Path\n\nIf you are deciding between this repo and the downloadable launcher, use this\nrule of thumb:\n\n- use the GitHub repo when you want:\n  - code access\n  - self-host setup\n  - custom data or custom pack work\n  - runtime-level experimentation\n- use the downloadable launcher when you want:\n  - a curated install/update path\n  - a local Research-oriented runtime with less setup work\n  - pack installs and local runtime management without treating Git as the main UX\n\nThe goal is that both paths converge on the same core runtime behavior even if\ntheir setup UX differs.\n\n## GitHub Vs Downloadable\n\nIf you are browsing this repository, treat it as the developer and self-host\nentry point.\n\nIf you want a more guided local install path, use the downloadable launcher\nwhen it is available through release/distribution channels.\n\nIn other words:\n\n- GitHub checkout = source, self-host, customization, local development\n- downloadable launcher = curated local install and runtime management\n\nBoth paths are intended to lead to the same DaedalMap runtime family.\n\n## Data Coverage\n\nThe hosted runtime ships with 40+ curated sources across disasters, demographics, economics, and climate. Coverage below reflects the current maintained pack inventory.\n\n### Global Disasters\n\n| Source | Scale | Time Range |\n|--------|-------|------------|\n| USGS Earthquakes | 1M+ events | 2150 BC - present |\n| IBTrACS Hurricanes/Cyclones | 13K storms | 1842 - present |\n| NOAA Tsunamis | 2.6K events | 2000 BC - present |\n| Smithsonian Volcanoes | 11K eruptions | Holocene |\n| Global Wildfires | 940K events/year | 2002 - 2024 |\n| USA/CAN Tornadoes | 81K events | 1950 - present |\n| Global Floods | 4.8K events | 1985 - 2019 |\n| Global Landslides | 45K events | 1760 - present |\n\nDisaster events include 22M+ geographic location relationships and 566K cross-disaster links (aftershocks, triggered events).\n\n### Global Indicators\n\n| Source | Countries | Years | Category |\n|--------|-----------|-------|----------|\n| Our World in Data CO2 | 217 | 1750 - 2024 | Environment |\n| WHO Health Statistics | 198 | 2015 - 2024 | Health |\n| IMF Balance of Payments | 195 | 2005 - 2022 | Economy |\n| UN Sustainable Development Goals | 200+ | 2000 - 2023 | SDGs 1-17 |\n| Eurostat Demographics | 37 European countries | 2000 - 2024 | Demographics |\n\n### Country-Specific Sources\n\n| Country | Source Count | Examples |\n|---------|-------------|---------|\n| USA | 15+ | Census, FEMA National Risk Index, NOAA storms |\n| Canada | 3 | Statistics Canada, NRCan earthquakes, drought |\n| Australia | 2 | ABS population, BOM cyclones |\n\n### Disaster Display\n\nDisasters are displayed with animated, type-specific rendering:\n- Point + radius: earthquakes, volcanoes, tornadoes\n- Track/trail: hurricanes and cyclones\n- Radial wave: tsunamis\n- Polygon fill: wildfires, floods\n\n## Current Runtime Shape\n\nDaedalMap now treats runtime behavior as a 2-axis matrix:\n\n- `INSTALL_MODE`\n  - `local` = local app/runtime install\n  - `cloud` = hosted/server deployment\n- `RUNTIME_MODE`\n  - `local` = query local data\n  - `cloud` = query managed cloud-backed data via local cache + DuckDB httpfs\n\nSupported combinations:\n- `local install + local data`\n- `local install + cloud data`\n- `cloud install + cloud data`\n\nNot supported as a first-class runtime shape:\n- `cloud install + local data`\n\nThe current hosted/runtime direction is:\n- a hosted app runtime\n- object storage for runtime data\n- optional auth and account services\n\nIn `RUNTIME_MODE=cloud`, the runtime:\n- eagerly syncs only small metadata files to local cache\n- queries parquet directly from object storage via DuckDB `httpfs`\n- does not sync the full parquet tree at startup\n\nHosted deployment topology, release lanes, and operator control-plane details\nbelong in private deployment notes.\n\nThat means the same codebase can be used in:\n- full local-data mode\n- hosted-style cloud-data mode\n\n## Guest And Logged-In Behavior\n\nGuest users can open the app and try the public workflow without logging in.\n\nLogged-in users currently get:\n- authenticated session identity\n- user-scoped frontend persistence\n- user-scoped backend session cache\n- account-owned settings and login on `daedalmap.com`\n\nThe public app no longer owns the account/settings UI.\n`app.daedalmap.com` stays focused on the runtime and map engine, while `.com`\nowns login, account, billing, and admin/runtime control-plane views.\n\n## Quick Start\n\n### 1. Install dependencies\n\n```powershell\ncd county-map\npip install -r requirements.txt\n```\n\n### 2. Add environment variables\n\nFor the smallest GitHub/local setup:\n\n```powershell\nCopy-Item .env.example .env\n```\n\nThen edit `DATA_ROOT`. The minimum local configuration is:\n\n```env\nDEPLOYMENT=local\nINSTALL_MODE=local\nRUNTIME_MODE=local\nDATA_ROOT=C:/path/to/your/local/data\n```\n\nIf you leave `DATA_ROOT` blank, DaedalMap uses the default local app-data path and expects your data to live there.\nNo S3, R2, AWS, database, account, or hosted-control-plane configuration is\nneeded for this path.\n\nNo model API key is required for local data operations. Set\n`OPENAI_API_KEY` or `ANTHROPIC_API_KEY` only for the built-in local chat UI.\nFor research using the model from an MCP-capable subscription client, see\n[docs/RESEARCH_MCP.md](docs/RESEARCH_MCP.md).\n\nHosted-style object-storage configuration is intentionally deployment-specific.\nFor public self-hosting, start with local data. Operators who run a cloud-backed\ndeployment should provide their own object-storage bucket, endpoint, and\ncredentials through environment variables.\n\nMost local users should leave these blank unless they intentionally want overrides:\n\n```env\nDATA_ROOT=\nAPP_URL=\nSITE_URL=\n```\n\nWhat they mean:\n- `DATA_ROOT`\n  only used in `RUNTIME_MODE=local`; leave blank to use the default local app-data folder\n- `APP_URL`\n  optional advertised app URL; leave blank for normal local runs\n- `SITE_URL`\n  optional website/docs/account URL override; leave blank for normal local runs\n\nIf you are configuring your own hosted deployment, set:\n\n```env\nINSTALL_MODE=cloud\nRUNTIME_MODE=cloud\nPORT=7000\n```\n\nIf you want hosted account behavior, connect this runtime to your own auth,\ndatabase, and analytics stack or to a separate private control plane you\noperate. Those business-side services are intentionally not bundled here.\n\n### 3. Run the app\n\n```powershell\npython app.py\n```\n\nOpen:\n- `http://localhost:7000`\n\n## API Discovery\n\nThe runtime exposes discovery and query endpoints on your local instance.\n\nDiscovery (no auth, no payment):\n\n- `GET /api/v1/guide`\n- `GET /api/v1/catalog`\n- `GET /api/v1/packs/{pack_id}`\n\nExecution:\n\n- `POST /api/v1/query/dataset`\n\nSelf-host instances return `commercial_access_unavailable` for the paid execution lane unless a commercial verifier is configured. Discovery endpoints work without additional setup.\n\nFor managed data access via the hosted API or MCP, see [daedalmap.com/docs/for-agents](https://daedalmap.com/docs/for-agents).\n\n## Data Resolution\n\nThe runtime resolves behavior from two explicit modes:\n\n1. `INSTALL_MODE`\n   controls deployment defaults like writable directories and default URLs\n2. `RUNTIME_MODE`\n   controls the data plane\n\nData mode behavior:\n\n1. `RUNTIME_MODE=local`\n   uses `DATA_ROOT`\n2. `RUNTIME_MODE=cloud`\n   uses the hydrated local cloud cache as `DATA_ROOT`\n\nDefault local writable folders on Windows:\n- `CONFIG_DIR=%LOCALAPPDATA%\\DaedalMap\\config`\n- `STATE_DIR=%LOCALAPPDATA%\\DaedalMap\\state`\n- `CACHE_DIR=%LOCALAPPDATA%\\DaedalMap\\cache`\n- `LOG_DIR=%LOCALAPPDATA%\\DaedalMap\\logs`\n- `PACKS_ROOT=%LOCALAPPDATA%\\DaedalMap\\packs`\n- `DATA_ROOT=%LOCALAPPDATA%\\DaedalMap\\data`\n\nIn hosted/cloud mode:\n- metadata is cached locally\n- parquet is queried remotely from object storage\n\nThat makes local cloud-mode testing useful for reproducing hosted-runtime behavior before deploy.\n\nImportant note:\n- the current public repo does not include a bundled `data/` demo tree\n- a source checkout therefore needs either `DATA_ROOT` in `local` mode, or `RUNTIME_MODE=cloud` with cloud storage configured\n- built-in local chat needs `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`; the hosted\n  Research MCP instead uses the model in the researcher's MCP-capable client\n\n## Data And Pack Direction\n\nThe old “demo data folder plus converters” framing is no longer the whole story.\n\nThe current direction is:\n- the engine stays open\n- maintained data is packaged as packs\n- packs are validated and promoted with explicit release gates\n- runtime catalogs eventually depend on pack availability, installation, and entitlement state\n\nKey concepts:\n- `available packs`\n- `installed packs`\n- `entitled packs`\n- `active runtime catalog`\n\nThese are intentionally distinct.\n\n## Explore And Research Contract\n\nExplore chat and Research chat use different discovery paths:\n- Explore starts from the runtime catalog, then selects sources.\n- Research starts from the active corpus manifest or loaded artifacts, then selects sources.\n\nAfter a specific source is selected, they should follow the same source contract:\n- source-level `temporal_coverage` is discovery guidance\n- metric-level `metrics.{metric_id}.years` is the execution truth\n- default year windows, slider bounds, and metric year ranges should clamp to the selected metric when available\n\nThat shared source-specific logic now lives in [mapmover/source_time_contract.py](mapmover/source_time_contract.py).\nUse that helper module for metric-aware year bounds instead of re-implementing time-range logic separately in Explore or Research code paths.\n\n## Settings Page\n\n`/settings` now behaves differently depending on mode:\n\n- hosted/account-aware mode: redirects to the paired account surface\n- self-host/local mode: shows local runtime setup guidance\n\nFor self-host users, `/settings` is the in-app reminder page for:\n- required LLM key setup\n- current runtime/data/config paths\n- the current state of local data vs future pack install flow\n\n## Useful Paths In This Repo\n\nImportant files and folders:\n- `app.py` - FastAPI app entrypoint\n- `mapmover/` - runtime logic, routes, path helpers, DuckDB helpers\n- `static/` - frontend app modules and styles\n- `templates/` - app HTML shell\n- `docs/` - local documentation for schemas, runtime notes, and reference material\n\n## Documentation In This Repo\n\nPublic runtime docs live in [docs/README.md](docs/README.md).\n\nRecommended starting points:\n- [docs/CONTEXT.md](docs/CONTEXT.md) - technical router for contributors and researchers\n- [docs/LOCAL_AND_HOSTED.md](docs/LOCAL_AND_HOSTED.md) - runtime mode selection and self-host basics\n- [docs/RUNTIME_MODES.md](docs/RUNTIME_MODES.md) - Explore, Research, Ops, and Tutorial\n- [docs/RUNTIME_UNIFICATION.md](docs/RUNTIME_UNIFICATION.md) - shared architecture and mode extension contract\n- [docs/DATA_SCHEMAS.md](docs/DATA_SCHEMAS.md) - schema and `loc_id` conventions\n- [docs/DATA_PREPARATION.md](docs/DATA_PREPARATION.md) - convert and validate your own data\n- [docs/PACK_AUTHORING.md](docs/PACK_AUTHORING.md) - build research packs and corpora\n\n## Local Development Modes\n\nUseful local modes:\n\n1. Full local-data mode\n- points at your local `DATA_ROOT`\n- best current self-host mode for GitHub users\n\n2. Hosted-style S3 mode\n- local server, but object-storage-backed data path\n- best for reproducing hosted runtime behavior before deploy\n\n3. Installed/runtime-pack mode\n- planned product direction beyond raw source checkout\n- engine/runtime installed separately from data packs\n- pack selection and updates handled outside the repo clone flow\n\n## Contact\n\nQuestions, feedback, or self-host issues: support@daedalmap.com\n\n## License\n\nMIT\n\n---\n\nIf an agent or tool was pointed at this README for programmable access, use:\n- Agent docs: https://daedalmap.com/docs/for-agents\n- Machine-readable entry: https://daedalmap.com/llms.txt\n",
  "bytes": 15446,
  "sha": "f5b82ba4a1a6b8975956891c0f535ff7806458074ac919e53038bcd38ce8b87c",
  "repo_slug": "xyver/daedal-map",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_daedalmap_boundaries_3049bb7c/readme"
}