Good Earth

Good Earth

为小型特色作物农场和花卉农场提供区域范围的气候分析， 通过 Tollbooth DPYC™ Bitcoin Lightning 微支付实现变现。

是 Good Brew 商店的姊妹项目。

• 面向种植者： Web 应用 https://goodearth.tollbooth-dpyc.com
• 面向 AI Agent： MCP 服务 https://goodearth-mcp.fastmcp.app/mcp （可流式传输的 HTTP）——与 Web 应用调用的工具相同。

连接 AI Agent

任何支持远程服务 URL 的 MCP 客户端都可以连接；无需账户，也无需 API 密钥。

客户端	操作方法
Claude.ai / Claude Desktop	自定义 → 连接器 → 添加自定义连接器 → https://goodearth-mcp.fastmcp.app/mcp（OAuth 字段留空）
Claude Code	claude mcp add --transport http goodearth https://goodearth-mcp.fastmcp.app/mcp，或在项目的 .mcp.json 中添加：{"mcpServers": {"goodearth": {"type": "http", "url": "https://goodearth-mcp.fastmcp.app/mcp"}}}
Cursor	.cursor/mcp.json：{"mcpServers": {"goodearth": {"url": "https://goodearth-mcp.fastmcp.app/mcp"}}}
VS Code	.vscode/mcp.json：{"servers": {"goodearth": {"type": "http", "url": "https://goodearth-mcp.fastmcp.app/mcp"}}}

仓库根目录的 server.json 是在官方 MCP Registry 中注册的入口， 名称为 io.github.lonniev/goodearth-mcp——DPYC 全部项目都列在该命名空间下。 .github/workflows/publish-mcp-registry.yml 会在每个 v* 标签发布时 进行发布，通过 GitHub OIDC 登录并从标签获取版本，因此无需保管密钥。 有一项测试会确保已提交的 version 与 pyproject.toml 一致。

首次连接流程

1. 向种植者索取其 Nostr npub——绝不要索取其 nsec。
2. goodearth_request_npub_proof(patron_npub=…) 会向其发送私信。对方从自己的 Nostr 客户端回复后，再调用一次 goodearth_receive_npub_proof(patron_npub=…, nonce=…)，并使用请求返回的 nonce。之后连接便会保存该 npub：每次付费调用只需传入 npub。
3. 调用 goodearth_check_balance 查看余额；通过 goodearth_purchase_credits（种植者支付的 Lightning 发票）充值，并调用 goodearth_check_payment。
4. 调用 goodearth_block_list 查看对方已保存的土地，或选择一个示例开始使用。

无需证明即可免费使用：goodearth_service_status 和 goodearth_oracle_* 工具。goodearth_check_price 可预览费用。服务器自身的 instructions 会重复说明以上全部内容，方便首次连接的 Agent 查看。

核心理念

农场不是一个点。 同一片土地上的田埂和洼地，霜冻日期并不相同，而所有免费的天气计算器给出的都是某个图钉位置的数据。

Good Earth 提供的是针对 土地 的答案。种植者只需使用 goodearth_block_save 将地块保存为一个 区块——带有名称的 GeoJSON 多边形 或 {lat, lon, radius_m} 定位点。此后，其他所有工具都可通过区块的 ID、 名称、别名，或仅属于一个区块的名称片段来引用该 block。每个工具都会对区块内的地形进行采样，并返回汇总值 以及区块内的差异范围。这正是产品的核心：它能告诉种植者，整个区块是否适合采用同一个种植日期。

区块可以相互重叠或嵌套：田地中的一块种植床也可以作为独立区块。 种植者种植的作物、关注的事项和已观察到的情况，都会通过 goodearth_block_item_save 按区块记录，因此季节工具无需传入任何列表。

      YOU (operator, human in the loop)
        │                         │
        │ set & tune prices       │ drive credential intake
        ▼                         ▼
  ┌───────────────┐        ┌──────────────────────────────────────────────┐
  │ Pricing Studio│ prices │        Good Earth — OPERATOR MCP              │
  │    (iOS)      ├───────▶│        FastMCP · deployed on Horizon          │
  └───────────────┘  Neon  │  ┌────────────────────────────────────────┐  │
                           │  │ region · sources · gdd · season        │  │
   Patron (Citizen)        │  │ @runtime.paid_tool(FROZEN_UUID) tools   │  │
   + MCP client  ─────────▶│  ├────────────────────────────────────────┤  │
   (Claude, the SPA) npub  │  │ tollbooth-dpyc SDK (the wheel)          │  │
                    +sats  │  │  ledger · vault (AES-256-GCM) · pricing │  │
                           │  │  ConstraintGate · Secure Courier·audit  │  │
                           │  └────────────────────────────────────────┘  │
                           └───┬─────────┬──────────┬───────────┬─────────┘
                               ▼         ▼          ▼           ▼
                         Neon Postgres  BTCPay▶  Sponsor     Nostr relays
                         (your schema)  Lightning Authority   proofs·courier
                         ledger+pricing invoices  certify +    DMs·audit
                                                  provision        │
                     Open-Meteo archive ◀── domain   │             ▼
                     forecast · elevation   calls    └──▶ DPYC Oracle +
                                                          dpyc-community

温度范围实际上是如何得出的

这是整个产品赖以建立的设计决策，因此我们会开诚布公地说明，而不是把它藏起来。

免费的网格化温度数据源最高约为 2 km 分辨率（归档的高分辨率模式运行数据），ERA5 再分析数据则为 9 km。同一座农场上的两个采样点可能落在同一个网格单元中，返回完全相同的数值——若将其报告为“您所在区域的温度范围”，就是把谎言包装成数据。然而，地形分辨率可达 90 m，而农场内真正存在差异的正是地形。

因此，Good Earth 从网格化数据源读取区域信号，并根据海拔推算区域内的变化：

影响	适用于	原因
温度递减率（3.57 °F / 1000 ft）	最高温和最低温	海拔越高，气温越低
冷空气沉降（上限为 6 °F）	仅最低温	在发生霜冻的晴朗无风夜晚，密度较大的冷空气会聚集在洼地中

每个响应都会注明所用数据源的原生分辨率，因此绝不会向种植者兜售数据本身并不具备的精度。

工具

除非另有说明，以下每个工具都需要一个已保存的 block。

工具	用途
地块
goodearth_block_save	保存一个地块（多边形或标记点），并为其设置名称和别名；一次调用可保存多个种植床
goodearth_block_list	列出已保存的地块及其边界；如果尚未保存任何地块，则提供一个完整示例
goodearth_block_transform	在地块内建议种植床布局；不会写入任何内容
goodearth_block_item_save、goodearth_block_item_list	查看在地块上种植、监测、观察到的内容，或留作种子的内容
goodearth_forget_my_ground	删除所有地块及其记录的所有内容（免费）
季节
goodearth_gdd_season_curve	查看本季截至目前的热量累积情况，并与过去十个季节对比
goodearth_frost_window	查看这块地通常何时结霜，以及本周是否即将结霜
goodearth_soil_temp_projection	查看土壤何时达到种植温度阈值
goodearth_planting_window	查看何时开始育苗、何时移栽，以及作物最晚何时仍能成熟
goodearth_crop_gdd_status	查看每次种植的进度，以及能否在霜冻前成熟
goodearth_crop_suitability	查看哪些作物能在这块地成熟，以及时间余量有多少
goodearth_almanac	查看这块地的天气记录，包括常年情况、实际情况和未来天气
goodearth_drying_window	查看露水何时蒸发、未来的干燥天气，以及下一场雨何时到来
goodearth_sunlight	查看地块各月的直射日照时长，以及太阳能板可产生的电量
害虫、病害和野生动物
goodearth_pest_catalog、goodearth_pest_threshold	查看此处建模的害虫虫态，以及各虫态当前的积温进度
goodearth_disease_risk	查看叶面湿润时长，以及病害模型对此的评估
goodearth_nearby_species	分页查看这块地附近的物种记录
goodearth_wildlife_catalog、goodearth_wildlife_calendar	查看这块地周围记录了哪些动物，以及它们何时出现
树木和伴生植物
goodearth_tree_suitability	查看树木能否在这块地存活并满足需冷量
goodearth_tree_year	查看春季何时到达这块地，以及树液的变化情况
goodearth_companions	查看适合某次种植的伴生植物——依据引用的科属规则（iNaturalist 分类）的协同关系，或根据种植者提供的花色、株高和花期进行设计
规划
goodearth_plan_the_season	季节规划访谈，作为可执行的工作流（无需提供地块）
goodearth_review_roster	根据这块地的记录，审核作物清单
goodearth_calibration	将地块自身的田间报告转化为模型校正
goodearth_task_save、goodearth_task_list、goodearth_task_set_done、goodearth_task_delete	农场的任务清单
日历订阅源
goodearth_calendar_dataset	计算地块的日期化季节数据，并储存起来以发布为日历订阅源
goodearth_calendar_fetch、goodearth_calendar_list、goodearth_calendar_revoke	读取、列出和停止发布订阅源（免费）

标准 DPYC 工具（check_balance、purchase_credits、Secure Courier、 Oracle、定价、约束）通过 register_standard_tools 从 wheel 中提供——此处不会重新实现其中任何功能。

数据源

全部公开。每个数据源都免费，只有 EIA 数据源需要密钥：运营方通过 Secure Courier 提供一个可选的 eia_api_key，这样 Sun 页面就能显示该地块所在州每度电的售价。

Source	Role	Native resolution
Open-Meteo archived model runs	观测到的每日最高/最低温度、累计生长季	~2 km
Open-Meteo archive (ERA5)	备用每日记录；用于日照的逐小时辐射数据	~9 km
Daymet v4 (NASA ORNL)	用于气候常值的长期每日历史数据，覆盖北美	1 km
Open-Meteo forecast	延伸预测 7 天	~2–11 km（视模型而定）
Open-Meteo elevation (SRTM)	地形降尺度	~90 m
Copernicus GLO-30 DEM, Meta/WRI canopy height, CGLS land cover	用于日照分析的地形、树木和遮荫数据	30 m, 1 m, 100 m
iNaturalist, GBIF, USA National Phenology Network	附近记录的物种；Companions 使用的科和属信息；物候	—
EIA retail electricity prices, DOE PV cost benchmarks, Nominatim	各州每度电售价和每千瓦成本	—

读取整个区域的生长季数据，无论采样点数量多少，都只需 三次上游请求：采样点会映射到存档自身的网格，因此每个不同网格单元只获取一次；十个生长季的气候常值范围会通过一次区间请求获取，再在本地切分，而非分别调用十次。

入门路线图

1. Nostr 密钥对 — 生成一个（nak key generate）；服务器只需要 nsec 作为唯一的环境变量（TOLLBOOTH_NOSTR_OPERATOR_NSEC）。
2. Sponsor Authority — 注册；系统会为你配置 Neon 数据库。
3. Secure Courier — 通过 goodearth_request_credential_channel 提交 btcpay_host、btcpay_api_key、 btcpay_store_id（以及可选的 eia_api_key）。绝不要将它们设为环境变量，也不要写进代码。
4. 在 Pricing Studio 中设置价格 — 新工具默认没有定价，未定价的工具无人可以调用。
5. 在 Horizon 上部署 — fastmcp.json 已完成配置。

获取 Pricing Studio （iOS）。 它会直接读取和写入 Neon 中的定价模型，因此价格永远不会存放在代码里——动态调价、欢乐时段、忠诚度折扣和免费试用，都是固定收费墙无法提供的功能。

SPA

frontend/ 包含 Good Earth 应用（采用 taxsort-mcp 模式——一个代码库，内含 React 应用）。登录和 Nostr 个人资料面板来自整个服务群共用的 @tollbooth-dpyc/web 包。这里没有账户：种植者就是一个 npub。

种植者的地块、地块上的记录、任务和已发布的日历订阅源，都按其 npub 存储在运营方的 Neon 数据库中。地块的名称、别名和边界使用 SDK 的保险库密码算法加密；地块记录的项目（作物名称、物种、田间报告）则以明文存储，以便排序和搜索。goodearth_forget_my_ground 会删除所有这些数据；种植者的余额和购买记录则会保留在 patron 名下。

开发

uv venv --python python3.12          # coincurve has no 3.14 wheel
uv pip install -e ".[dev]"
ruff check .
pytest -v
python -m goodearth_mcp.server       # runs the validate_operator_tools guard

cd frontend && npm install && npm run build

许可证

Apache-2.0