Pondlog Phenology (USA-NPN)

pondlog

面向开发者的地点感知自然数据。这些坐标处的自然环境此刻正在发生什么？

Pondlog 将免费的公共 API（iNaturalist、eBird、USA-NPN、USGS、Mushroom Observer）、本地天文计算（astronomy-engine）以及 NOAA 潮汐/云量数据整合到一个数据层中，并提供两种接口：

• 面向人类的 CLI（pondlog inat nearby --lat 48.118 --lng -123.43）
• 每个数据源各自的 MCP 服务，供 AI Agent 使用（Claude Desktop、Cursor）

作者：Andrew Christison。

包含内容

8 个数据源、7 个 MCP 服务、1 个统一命令行工具。包含约 1000 种作物的园艺规划器，提供 USDA 耐寒区数据和伴生种植关系图。

Package	npm	功能
pondlog		统一命令行工具
@pondlog/core		共享类型、Result<T>、速率限制器、USDA 耐寒区、作物日历、伴生植物
@pondlog/source-inaturalist		iNaturalist API 客户端
@pondlog/source-ebird		eBird API 客户端（21 个端点）
@pondlog/source-npn		USA-NPN 物候客户端
@pondlog/source-usgs		USGS Water Services 客户端
@pondlog/source-nightsky		本地夜空简报（astronomy-engine）
@pondlog/source-mushroomobserver		Mushroom Observer（真菌学）客户端
@pondlog/source-trefle		Trefle.io 植物分类客户端
@pondlog/mcp-inaturalist		iNaturalist MCP 服务（9 个工具）
@pondlog/mcp-ebird		eBird MCP 服务（21 个工具）
@pondlog/mcp-npn		NPN MCP 服务（8 个工具）
@pondlog/mcp-usgs		USGS MCP 服务（4 个工具）
@pondlog/mcp-mushroomobserver		Mushroom Observer MCP 服务（5 个工具，以真菌学为核心）
@pondlog/mcp-garden		园艺规划 MCP 服务（8 个工具，包含日历、耐寒区、伴生植物和 Trefle）
@pondlog/mcp-pondlog		聚合 MCP 服务（5 个工具，涵盖全部 8 个数据源）

状态

来源	库	CLI	MCP
iNaturalist	✅	✅	✅
eBird	✅	✅	✅
NPN（物候）	✅	✅	✅
USGS（水域）	✅	✅	✅
Mushroom Observer（真菌学）	✅	✅	✅
Garden（USDA 分区 + 约 5,000 种作物日历 + 伴生种 + Trefle）	✅	✅	✅
夜空（astronomy-engine）	✅	✅	✅（通过 mcp-pondlog）
聚合（pondlog today / mcp-pondlog）	不适用	✅	✅

快速开始

作为 AI Agent（MCP）

将以下内容添加到 Claude Desktop 配置中 （macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "pondlog-inaturalist": {
      "command": "npx",
      "args": ["-y", "@pondlog/mcp-inaturalist"]
    }
  }
}

然后向 Claude 提问：

过去一周，华盛顿州安吉利斯港附近有哪些两栖动物被观测到？

同一份 JSON 也适用于 Cursor 的 ~/.cursor/mcp.json。只需一条命令即可运行任意 MCP 服务：

npx -y @pondlog/mcp-inaturalist          # no key
npx -y @pondlog/mcp-garden               # offline garden tools
EBIRD_API_KEY=... npx -y @pondlog/mcp-ebird
npx -y @pondlog/mcp-pondlog              # aggregate of all eight sources

作为用户（CLI）

npm install -g pondlog
pondlog config set-location --lat 48.118 --lng -123.4307 --name "Port Angeles"
pondlog today                          # unified briefing
pondlog inat nearby
pondlog ebird notable
pondlog npn active
pondlog usgs flow --site 12045500
pondlog nightsky                       # tonight's curated briefing
pondlog garden now                     # what to plant this week

每条命令都支持 --json，用于输出机器可读内容。

架构

                          ┌─────────────────────────┐
                          │      @pondlog/core      │
                          │  types, Result<T>,      │
                          │  RateLimiter, withRetry,│
                          │  USDA zones, crops,     │
                          │  companion graph        │
                          └────────────┬────────────┘
                                       │
        ┌──────────┬──────────┬────────┼─────────┬──────────┬──────────┐
        ▼          ▼          ▼        ▼         ▼          ▼          ▼
 source-inat  source-ebird  source-npn  source-usgs  source-mo  source-trefle  source-nightsky
        │          │          │        │         │          │          │
        └──────────┴──────────┴────────┼─────────┴──────────┴──────────┘
                                       │
                  ┌────────────────────┴────────────────────┐
                  ▼                                         ▼
            pondlog (CLI)                       7 × @pondlog/mcp-* servers
            ├─ pondlog today (aggregate)         ├─ mcp-inaturalist
            ├─ pondlog inat/ebird/...             ├─ mcp-ebird
            └─ pondlog garden/nightsky            ├─ mcp-npn / mcp-usgs
                                                  ├─ mcp-mushroomobserver
                                                  ├─ mcp-garden
                                                  └─ mcp-pondlog  ◀── aggregate

数据源客户端负责所有工作（Zod 校验、速率限制、重试和标准化）。CLI 和 MCP 服务只是围绕它们构建的轻量封装。

设计原则

• 一个数据层，两种接口。 每个数据源都是一个类型化库（经过 Zod 校验、受速率限制，并返回 Result<T>）。CLI 和 MCP 服务只是轻量封装，不包含业务逻辑。
• 优雅降级。 数据源不可用时，聚合结果仍会返回其他成功的数据，并在结果中报告错误。
• 遵守速率限制。 每个客户端都会自行限流。绝不信任调用方。
• 能不需要密钥的就不使用密钥。 iNaturalist、NPN、USGS、Mushroom Observer 和夜空数据源均无需密钥即可运行。只有 eBird 和 Trefle 需要免费密钥。
• 数据不依赖外部来源时，使用本地计算。 天文学只涉及纯数学；@pondlog/source-nightsky 不会发起任何网络请求，也没有速率限制或故障模式。花园日历、分区和伴生种关系图均以内置 JSON 提供，完全离线可用。

相关项目：CropGraph

CropGraph 是一个配套的 HTTP API，提供与 @pondlog/core 和 @pondlog/mcp-garden 相同的约 1,000 种作物种植日历、USDA 耐寒区和伴生种植关系图。需要通过 HTTP 从任意语言获取数据时，可使用 CropGraph。其架构与本仓库保持同步。

贡献

欢迎提交 PR。本项目使用 pnpm 构建：

git clone https://github.com/andrewschristison/pondlog.git
cd pondlog
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm smoke   # live tests against iNaturalist

作物日历 / 伴生种植数据

作物日历（packages/core/src/data/crop-calendar.json）和伴生关系图（packages/core/src/data/companions.json）接受社区 PR。两者的数据文件旁都附有 JSON Schema：

• packages/core/src/data/crop-calendar.schema.json
• packages/core/src/data/companions.schema.json

添加作物条目时，请为每个条目添加 source，引用真实的推广服务机构（USDA、Cornell、WSU、Oregon State、UMass、UF/IFAS 等）。添加伴生关系边时，请提供 evidence（strong 或 moderate）和 citation URL。Zod 校验会在模块加载时运行，因此格式错误的 PR 会立即导致 import "@pondlog/core" 失败。

代码

每个软件包都遵循严格的模式，详见docs/METHODOLOGY.md。数据源客户端总是先于使用它们的 CLI 命令或 MCP 工具发布。

许可证

MIT。请参阅 LICENSE。