内容
<div align="center">
<img src="https://qinisolabs.github.io/floodwise/logo.svg" width="96" height="96" alt="Qiniso" />
# 洪水风险查询
**基于邮政编码的英格兰洪水风险数据，为AI代理提供验证后的环境署数据，而非猜测。**
*验证的、值得信赖的数据工具，适用于AI代理。“Qiniso”在祖鲁语中意为“真相”。*
[官方网站](https://qinisolabs.github.io/floodwise/) · [npm](https://www.npmjs.com/package/floodwise) · [MCP 注册中心](https://registry.modelcontextprotocol.io/v0/servers?search=floodwise)
</div>
---
询问一个大型语言模型“SW1A 1AA的洪水风险是多少？”，它会自信地回答——但**它无法知道**：每个邮政编码的洪水风险都是特定的、精心策划的数据，存在于政府的数据集中，而不在模型的权重中。**floodwise**会在环境署的官方“洪水风险：邮政编码搜索工具”数据中查找邮政编码，并返回真正的长期风险等级——或者一个诚实的“未找到”，而不是猜测。
## ⚠️ 请先阅读——什么是floodwise，什么不是
- **仅限英格兰。** 数据来自环境署，涵盖**英格兰**。威尔士（自然资源威尔士）、苏格兰（苏格兰环境保护局）和北爱尔兰（交通部）**不**包含在内。有效的威尔士/苏格兰邮政编码返回“未找到”，而不会猜测。
- **区域级别，而不是房产级别。** 风险是针对邮政编码区域内的地址，而不是特定的建筑。环境署表示，这些数据“通常不适合房产级别的评估”。
- **长期风险，而不是实时警告。** 它反映了长期的年度洪水风险，而不是当前或预测的洪水情况。它**不是**保险、承保、测量或专业建议。
## 将其添加到Claude
floodwise在stdio上本地运行（无需密钥，无需登录）。一旦它出现在npm上，请在客户端配置文件中的`mcpServers`下添加它：
```json
{ "command": "npx", "args": ["-y", "floodwise"] }
```
## 作为库使用
```bash
npm i floodwise
```
```ts
import { floodRiskByPostcode, validatePostcode } from "floodwise";
floodRiskByPostcode("SW1A 1AA");
// {
// postcode: "SW1A 1AA", found: true, headlineRisk: "Very Low",
// addressesAtRisk: { high: 0, medium: 0, low: 0 }, groundwater: "Unlikely",
// coverage: "England", dataset: "ea-official", ...
// }
floodRiskByPostcode("EH1 1AA").found; // false — 有效的邮政编码，但苏格兰（超出环境署覆盖范围），不猜测
validatePostcode("ec1a1bb"); // { valid: true, postcode: "EC1A 1BB", outcode: "EC1A", incode: "1BB" }
```
邮政编码可以有空格或无空格，大小写不限。格式正确的邮政编码如果不在加载的英格兰数据集中，会以`found: false`和明确的注释返回——它永远不会编造风险等级。
## 工具 — 2
| 工具 | 回答内容 |
| --- | --- |
| **flood_risk_by_postcode** | 英格兰邮政编码的长期洪水风险等级（高/中等/低/极低）、每个等级的地址数量和地下水指示 |
| **validate_postcode** | 这是一个格式正确的英国邮政编码吗？（确定性格式检查 + 前缀/后缀拆分） |
## 数据
洪水数据是环境署的**“洪水风险：邮政编码搜索工具数据”**（英格兰），作为**开放政府许可 v3.0**下的开放数据发布。每个邮政编码都包含周围区域处于高（≥3.3%/年）、中（1–3.3%）或低（0.1–1%）长期洪水风险的地址数量（河流、海或地表水的最高值），以及单独的地下水**可能/不太可能**指示。大约每季度更新一次。
> 此存储库提供了一个**示例起始样本**（非地理`ZZ`伪邮政编码），以便测试可以直接运行——其所有响应都标记为`dataset: "sample"`。要加载实际数据，请从[data.gov.uk](https://www.data.gov.uk/) / Defra数据服务平台下载`Postcodes_Risk_Assessment_All.csv`，并运行：
>
> ```bash
> npm run build-data /path/to/Postcodes_Risk_Assessment_All.csv 2025-Q4
> npm run build && npm test
> ```
致谢：*包含根据开放政府许可 v3.0 授权的公共部门信息。© 环境署版权和/或数据库权利。* 见 `NOTICE`。
## 它不是什么
- **不是建议。** 不是保险、承保、测量、抵押贷款或法律建议；不是房产级别的调查。
- **不是所有类型的洪水。** 排除公路排水沟、下水道和地面径流引起的洪水；地下水单独报告，不纳入主要风险等级。
- **不是整个英国。** 仅限英格兰（见上文）。
- **不是猜测工具。** 未知/超出覆盖范围的邮政编码返回一个诚实的“未找到”，而不会捏造风险等级。
## 架构
一个TypeScript软件包，通过**stdio**（本地 / `npx`）暴露一个MCP服务器，由相同的`core.ts`工具定义驱动，这些定义为可导入的库提供支持。包含一个Cloudflare Worker入口，以便将来托管边缘端点——注意完整的英格兰数据集（~1.6M邮政编码）超过了Worker捆绑包限制，因此托管构建将数据移动到Cloudflare D1（后续）；npm库和stdio服务器直接运行完整的数据集。
```bash
npm install
npm run build
npm test
```
## 隐私
该工具在您的机器上本地运行，设计时不收集、存储或传输您的数据——无分析、无遥测、无账户。所有参考数据都已捆绑——无需网络调用，数据不会离开您的设备。完整政策：<https://qinisolabs.github.io/privacy.html>.
## 许可证
Apache-2.0. 洪水数据 © 环境署，开放政府许可 v3.0；参见 `NOTICE`.
