{
  "markdown": "<div align=\"center\">\n\n<img src=\"https://qinisolabs.github.io/floodwise/logo.svg\" width=\"96\" height=\"96\" alt=\"Qiniso\" />\n\n# floodwise\n\n**England flood-risk by postcode for AI agents — verified Environment Agency data, not guesses.**\n\n*Verified, trustworthy data tools for AI agents. \"Qiniso\" means \"truth\" in Zulu.*\n\n[Website](https://qinisolabs.github.io/floodwise/) · [npm](https://www.npmjs.com/package/floodwise) · [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=floodwise)\n\n</div>\n\n---\n\nAsk an LLM \"what's the flood risk at SW1A 1AA?\" and it will answer confidently — but it **cannot know**: per-postcode flood risk is specific, curated data that lives in a government dataset, not in a model's weights. **floodwise** looks the postcode up in the Environment Agency's official *\"Flood risk: postcode search tool\"* data and returns the real long-term risk band — or an honest *\"not found\"* instead of a guess.\n\n## ⚠️ Read this first — what floodwise is and isn't\n\n- **England only.** The data is the Environment Agency's, which covers **England**. Wales (Natural Resources Wales), Scotland (SEPA) and Northern Ireland (DfI) are **not** covered. A valid Welsh/Scottish postcode returns *\"not found\"*, never a guess.\n- **Area-level, not property-level.** The risk is for *the area around* the addresses in a postcode — not a specific building. The EA states this data is *\"generally not suitable for property level assessment\"*.\n- **Long-term risk, not a live warning.** It reflects the long-term annual chance of flooding, not whether flooding is happening now or forecast. It is **not** insurance, underwriting, surveying or professional advice.\n\n## Add it to Claude\n\nfloodwise runs locally over stdio (no key, no login). Once it's on npm, add it under `mcpServers` in your client config:\n\n```json\n{ \"command\": \"npx\", \"args\": [\"-y\", \"floodwise\"] }\n```\n\n## Use it as a library\n\n```bash\nnpm i floodwise\n```\n\n```ts\nimport { floodRiskByPostcode, validatePostcode } from \"floodwise\";\n\nfloodRiskByPostcode(\"SW1A 1AA\");\n// {\n//   postcode: \"SW1A 1AA\", found: true, headlineRisk: \"Very Low\",\n//   addressesAtRisk: { high: 0, medium: 0, low: 0 }, groundwater: \"Unlikely\",\n//   coverage: \"England\", dataset: \"ea-official\", ...\n// }\n\nfloodRiskByPostcode(\"EH1 1AA\").found;   // false — valid postcode, but Scotland (out of EA coverage), no guess\nvalidatePostcode(\"ec1a1bb\");            // { valid: true, postcode: \"EC1A 1BB\", outcode: \"EC1A\", incode: \"1BB\" }\n```\n\nPostcodes are accepted spaced or unspaced, any case. A well-formed postcode that isn't in the loaded England dataset returns `found: false` with a clear note — it never invents a risk level.\n\n## Tools — 2\n\n| Tool | What it answers |\n| --- | --- |\n| **flood_risk_by_postcode** | The EA long-term flood-risk band (High/Medium/Low/Very Low) for an England postcode, address counts per band, and the groundwater indication |\n| **validate_postcode** | Is this a well-formed UK postcode? (deterministic format check + outcode/incode split) |\n\n## Data\n\nThe flood data is the Environment Agency **\"Flood risk: postcode search tool data\"** (England), published as open data under the **Open Government Licence v3.0**. Each postcode carries the number of addresses whose surrounding area is at high (≥3.3%/yr), medium (1–3.3%) or low (0.1–1%) long-term risk from rivers, sea or surface water (the highest of these), plus a separate groundwater *Possible/Unlikely* indication. Refreshed roughly quarterly.\n\n> This repository ships an **illustrative starter sample** (non-geographic `ZZ` pseudo-postcodes) so tests run out of the box — every response from it is tagged `dataset: \"sample\"`. To load the real data, download `Postcodes_Risk_Assessment_All.csv` from [data.gov.uk](https://www.data.gov.uk/) / the Defra Data Services Platform and run:\n>\n> ```bash\n> npm run build-data /path/to/Postcodes_Risk_Assessment_All.csv 2025-Q4\n> npm run build && npm test\n> ```\n\nAttribution: *Contains public sector information licensed under the Open Government Licence v3.0. © Environment Agency copyright and/or database right.* See `NOTICE`.\n\n## What it is *not*\n\n- **Not advice.** Not insurance, underwriting, surveying, mortgage or legal advice; not a property-level survey.\n- **Not all flood types.** Excludes flooding from highway drains, sewers and overland flow; groundwater is reported separately and isn't combined into the headline band.\n- **Not the whole UK.** England only (see above).\n- **Not a guesser.** Unknown/out-of-coverage postcodes return an honest \"not found\", never a fabricated risk level.\n\n## Architecture\n\nA single TypeScript package exposing one MCP server over **stdio** (local / `npx`), driven by the same `core.ts` tool definitions that power the importable library. A Cloudflare Worker entry is included for a future hosted edge endpoint — note the full England dataset (~1.6M postcodes) exceeds the Worker bundle limit, so the hosted build will move the data into Cloudflare D1 (a follow-on); the npm library and stdio server run the full dataset directly.\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n## Privacy\n\nThis tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. All reference data is bundled — no network calls, and nothing leaves your device. Full policy: <https://qinisolabs.github.io/privacy.html>.\n\n## License\n\nApache-2.0. Flood data © Environment Agency, Open Government Licence v3.0; see `NOTICE`.\n",
  "bytes": 5490,
  "sha": "30911e07c7c15e85a29540be297b1628e227f8f8791779575fdc5439c6d8fe8e",
  "repo_slug": "qinisolabs/floodwise",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_qinisolabs_floodwise_3b33422c/readme"
}