floodwise

floodwise is a data tool for AI agents, used to look up long-term flood risk in England by postcode. Its name "Qiniso" means "truth" in Zulu, emphasizing the provision of verified, trustworthy data rather than model guesses.

Purpose When a user asks a large language model, "What is the flood risk for SW1A 1AA?", the model often answers confidently, but the flood risk for each postcode is specific, curated data that exists in government datasets, not in model weights. floodwise looks up that postcode in the Environment Agency's official "Flood risk: postcode search tool" data, returning the real long-term risk band, or honestly returning "not found" instead of guessing.

Main capabilities

• Look up the long-term flood risk level in England by postcode.
• Return the number of addresses in the surrounding area of each postcode that are at high (≥3.3%/year), medium (1–3.3%), or low (0.1–1%) long-term risk (from rivers, the sea, or surface water, whichever is highest), and separately provide a groundwater "possible/unlikely" indication.
• Postcodes are accepted with or without spaces, in any case.
• Postcodes that are correctly formatted but not in the loaded England dataset return found: false with a clear explanation, and never fabricate a risk level.
• Data is refreshed about once a quarter.

How to use floodwise runs locally via stdio (no key, no login required). After it is published on npm, it can be added under mcpServers in the client configuration. It can also be imported and used as a library, driven by the same set of core.ts tool definitions. The repository includes an illustrative starter sample (a non-geographic ZZ pseudo-postcode), so testing works out of the box, and each of its responses is marked dataset: "sample". To load real data, download Postcodes_Risk_Assessment_All.csv from data.gov.uk / Defra Data Services Platform and run the corresponding command.

Use cases Suitable for scenarios that need to provide trustworthy England flood risk data for AI agents, such as querying the long-term flood risk for a specific postcode in a conversation, or integrating it into an application as a library.

Limitations

• England only. The data comes from the Environment Agency and covers England; Wales (Natural Resources Wales), Scotland (SEPA), and Northern Ireland (DfI) are not covered. Valid Welsh/Scottish postReturns "not found" — never guesses.
• Area-level, not property-level. Risk applies to the area surrounding an address within a postcode, not a specific building. The Environment Agency states the data is "not generally suitable for property-level assessment".
• Long-term risk, not real-time warnings. Reflects long-term annual flood probability, not whether flooding is currently occurring or forecast. Not insurance, underwriting, surveying, or professional advice.
• Does not cover all flood types. Excludes flooding from highway drainage, sewers, and surface water runoff; groundwater is reported separately and is not merged into the main risk bands.
• Not all of the UK. England only.
• No guessing. Unknown or out-of-coverage postcodes return an honest "not found" — never a fabricated risk rating.

Technical notes This is a single TypeScript package that exposes an MCP server over stdio (local / npx), driven by the same set of core.ts tool definitions as the importable library. It includes a Cloudflare Worker entry point for a future hosted edge endpoint — note that the full England dataset (around 1.6 million postcodes) exceeds Worker bundle limits, so the hosted version will move the data into Cloudflare D1 (future work); the npm library and stdio server run the full dataset directly. The tool runs on your local machine and is designed not to collect, store, or transmit user data — no analytics, no telemetry, no accounts. All reference data is bundled in — no network calls, data never leaves the device.

Licence Apache-2.0. Flood data © Environment Agency, Open Government Licence v3.0.