pondlog

pondlog

Place-aware nature data for developers. What's happening in nature at these coordinates right now?

Pondlog stitches together free public APIs (iNaturalist, eBird, USA-NPN, USGS, Mushroom Observer) plus local astronomy computation (astronomy-engine) and NOAA tides/cloud cover into one data layer with two interfaces:

• A CLI for humans (pondlog inat nearby --lat 48.118 --lng -123.43)
• An MCP server per source for AI agents (Claude Desktop, Cursor)

By Andrew Christison.

What's in the box

8 data sources. 7 MCP servers. 1 unified CLI. A ~1000-crop garden planner with USDA hardiness zones and companion-planting graph.

| Package | npm | What it does | |---|---|---| | pondlog |  | Unified CLI | | @pondlog/core |  | Shared types, Result<T>, rate limiter, USDA zones, crop calendar, companions | | @pondlog/source-inaturalist |  | iNaturalist API client | | @pondlog/source-ebird |  | eBird API client (21 endpoints) | | @pondlog/source-npn |  | USA-NPN phenology client | | @pondlog/source-usgs |  | USGS Water Services client | | @pondlog/source-nightsky |  | Local night-sky briefing (astronomy-engine) | | @pondlog/source-mushroomobserver |  | Mushroom Observer (mycology) client | | @pondlog/source-trefle |  | Trefle.io plant taxonomy client | | @pondlog/mcp-inaturalist |  | iNaturalist MCP server (9 tools) | | @pondlog/mcp-ebird |  | eBird MCP server (21 tools) | | @pondlog/mcp-npn |  | NPN MCP server (8 tools) | | @pondlog/mcp-usgs |  | USGS MCP server (4 tools) | | @pondlog/mcp-mushroomobserver |  | Mushroom Observer MCP server (5 tools, mycology-first) | | @pondlog/mcp-garden |  | Garden-planning MCP server (8 tools, calendar + zones + companions + Trefle) | | @pondlog/mcp-pondlog |  | Aggregate MCP server (5 tools, all eight sources) |

Status

| Source | Library | CLI | MCP | |---|---|---|---| | iNaturalist | ✅ | ✅ | ✅ | | eBird | ✅ | ✅ | ✅ | | NPN (phenology) | ✅ | ✅ | ✅ | | USGS (water) | ✅ | ✅ | ✅ | | Mushroom Observer (mycology) | ✅ | ✅ | ✅ | | Garden (USDA zones + ~5,000-crop calendar + companions + Trefle) | ✅ | ✅ | ✅ | | Night sky (astronomy-engine) | ✅ | ✅ | ✅ (via mcp-pondlog) | | Aggregate (pondlog today / mcp-pondlog) | n/a | ✅ | ✅ |

Quick start

As an AI agent (MCP)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Then ask Claude:

What amphibians have been seen near Port Angeles, WA in the last week?

The same JSON works in ~/.cursor/mcp.json for Cursor. Run any MCP server in one command:

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

As a human (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 works on every command for machine output.

Architecture

                          ┌─────────────────────────┐
                          │      @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

Source clients do all the work (Zod validation, rate limiting, retry, normalization). The CLI and MCP servers are thin wrappers around them.

Design principles

• One data layer, two interfaces. Each source is a typed library

(Zod-validated, rate-limited, returns Result<T>). The CLI and MCP servers are thin wrappers. No business logic in them.

• Degrade gracefully. When a source is down, the aggregate still

returns whatever else worked, with errors reported in-band.

• Rate limits respected. Each client throttles itself. Never trust

the caller.

• No keys for what doesn't need them. iNaturalist, NPN, USGS,

Mushroom Observer, and the night-sky source all run keyless. Only eBird and Trefle require free keys.

• Local computation when the data isn't external. Astronomy is

pure math; @pondlog/source-nightsky ships zero network calls, zero rate limits, zero failure modes. The garden calendar, zones, and companion graph are bundled JSON, all offline.

Related: CropGraph

CropGraph is a sibling HTTP API exposing the same ~1000-crop planting calendar, USDA hardiness zones, and companion-planting graph used by @pondlog/core and @pondlog/mcp-garden. Use CropGraph when you want the data over HTTP from any language. The schemas are kept in lockstep with this repo.

Contributing

PRs welcome. The build is pnpm-based:

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

Crop calendar / companion-planting data

The crop calendar (packages/core/src/data/crop-calendar.json) and companion graph (packages/core/src/data/companions.json) accept community PRs. Both have JSON Schemas alongside the data:

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

When adding a crop entry, include a per-entry source citing a real extension service (USDA, Cornell, WSU, Oregon State, UMass, UF/IFAS, etc.). When adding a companion edge, include evidence (strong or moderate) and a citation URL. Zod validation runs at module load, so a malformed PR breaks import "@pondlog/core" immediately.

Code

Each package follows a strict pattern documented in docs/METHODOLOGY.md. Source clients always ship before the CLI commands or MCP tools that consume them.

License

MIT. See LICENSE.