{
  "markdown": "# pondlog\n\nPlace-aware nature data for developers. **What's happening in nature at\nthese coordinates right now?**\n\nPondlog stitches together free public APIs (iNaturalist, eBird, USA-NPN,\nUSGS, Mushroom Observer) plus local astronomy computation\n(`astronomy-engine`) and NOAA tides/cloud cover into one data layer\nwith two interfaces:\n\n- A **CLI** for humans (`pondlog inat nearby --lat 48.118 --lng -123.43`)\n- An **MCP server** per source for AI agents (Claude Desktop, Cursor)\n\nBy [Andrew Christison](https://github.com/andrewschristison).\n\n## What's in the box\n\n8 data sources. 7 MCP servers. 1 unified CLI. A ~1000-crop garden\nplanner with USDA hardiness zones and companion-planting graph.\n\n| Package | npm | What it does |\n|---|---|---|\n| [`pondlog`](./packages/cli) | [![npm](https://img.shields.io/npm/v/pondlog.svg)](https://www.npmjs.com/package/pondlog) | Unified CLI |\n| [`@pondlog/core`](./packages/core) | [![npm](https://img.shields.io/npm/v/@pondlog/core.svg)](https://www.npmjs.com/package/@pondlog/core) | Shared types, `Result<T>`, rate limiter, USDA zones, crop calendar, companions |\n| [`@pondlog/source-inaturalist`](./packages/source-inaturalist) | [![npm](https://img.shields.io/npm/v/@pondlog/source-inaturalist.svg)](https://www.npmjs.com/package/@pondlog/source-inaturalist) | iNaturalist API client |\n| [`@pondlog/source-ebird`](./packages/source-ebird) | [![npm](https://img.shields.io/npm/v/@pondlog/source-ebird.svg)](https://www.npmjs.com/package/@pondlog/source-ebird) | eBird API client (21 endpoints) |\n| [`@pondlog/source-npn`](./packages/source-npn) | [![npm](https://img.shields.io/npm/v/@pondlog/source-npn.svg)](https://www.npmjs.com/package/@pondlog/source-npn) | USA-NPN phenology client |\n| [`@pondlog/source-usgs`](./packages/source-usgs) | [![npm](https://img.shields.io/npm/v/@pondlog/source-usgs.svg)](https://www.npmjs.com/package/@pondlog/source-usgs) | USGS Water Services client |\n| [`@pondlog/source-nightsky`](./packages/source-nightsky) | [![npm](https://img.shields.io/npm/v/@pondlog/source-nightsky.svg)](https://www.npmjs.com/package/@pondlog/source-nightsky) | Local night-sky briefing (astronomy-engine) |\n| [`@pondlog/source-mushroomobserver`](./packages/source-mushroomobserver) | [![npm](https://img.shields.io/npm/v/@pondlog/source-mushroomobserver.svg)](https://www.npmjs.com/package/@pondlog/source-mushroomobserver) | Mushroom Observer (mycology) client |\n| [`@pondlog/source-trefle`](./packages/source-trefle) | [![npm](https://img.shields.io/npm/v/@pondlog/source-trefle.svg)](https://www.npmjs.com/package/@pondlog/source-trefle) | Trefle.io plant taxonomy client |\n| [`@pondlog/mcp-inaturalist`](./packages/mcp-inaturalist) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-inaturalist.svg)](https://www.npmjs.com/package/@pondlog/mcp-inaturalist) | iNaturalist MCP server (9 tools) |\n| [`@pondlog/mcp-ebird`](./packages/mcp-ebird) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-ebird.svg)](https://www.npmjs.com/package/@pondlog/mcp-ebird) | eBird MCP server (21 tools) |\n| [`@pondlog/mcp-npn`](./packages/mcp-npn) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-npn.svg)](https://www.npmjs.com/package/@pondlog/mcp-npn) | NPN MCP server (8 tools) |\n| [`@pondlog/mcp-usgs`](./packages/mcp-usgs) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-usgs.svg)](https://www.npmjs.com/package/@pondlog/mcp-usgs) | USGS MCP server (4 tools) |\n| [`@pondlog/mcp-mushroomobserver`](./packages/mcp-mushroomobserver) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-mushroomobserver.svg)](https://www.npmjs.com/package/@pondlog/mcp-mushroomobserver) | Mushroom Observer MCP server (5 tools, mycology-first) |\n| [`@pondlog/mcp-garden`](./packages/mcp-garden) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-garden.svg)](https://www.npmjs.com/package/@pondlog/mcp-garden) | Garden-planning MCP server (8 tools, calendar + zones + companions + Trefle) |\n| [`@pondlog/mcp-pondlog`](./packages/mcp-pondlog) | [![npm](https://img.shields.io/npm/v/@pondlog/mcp-pondlog.svg)](https://www.npmjs.com/package/@pondlog/mcp-pondlog) | Aggregate MCP server (5 tools, all eight sources) |\n\n## Status\n\n| Source | Library | CLI | MCP |\n|---|---|---|---|\n| iNaturalist | ✅ | ✅ | ✅ |\n| eBird | ✅ | ✅ | ✅ |\n| NPN (phenology) | ✅ | ✅ | ✅ |\n| USGS (water) | ✅ | ✅ | ✅ |\n| Mushroom Observer (mycology) | ✅ | ✅ | ✅ |\n| Garden (USDA zones + ~5,000-crop calendar + companions + Trefle) | ✅ | ✅ | ✅ |\n| Night sky (`astronomy-engine`) | ✅ | ✅ | ✅ (via `mcp-pondlog`) |\n| Aggregate (`pondlog today` / `mcp-pondlog`) | n/a | ✅ | ✅ |\n\n## Quick start\n\n### As an AI agent (MCP)\n\nAdd to your Claude Desktop config\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on\nmacOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"pondlog-inaturalist\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pondlog/mcp-inaturalist\"]\n    }\n  }\n}\n```\n\nThen ask Claude:\n\n> What amphibians have been seen near Port Angeles, WA in the last week?\n\nThe same JSON works in `~/.cursor/mcp.json` for Cursor. Run any MCP\nserver in one command:\n\n```sh\nnpx -y @pondlog/mcp-inaturalist          # no key\nnpx -y @pondlog/mcp-garden               # offline garden tools\nEBIRD_API_KEY=... npx -y @pondlog/mcp-ebird\nnpx -y @pondlog/mcp-pondlog              # aggregate of all eight sources\n```\n\n### As a human (CLI)\n\n```sh\nnpm install -g pondlog\npondlog config set-location --lat 48.118 --lng -123.4307 --name \"Port Angeles\"\npondlog today                          # unified briefing\npondlog inat nearby\npondlog ebird notable\npondlog npn active\npondlog usgs flow --site 12045500\npondlog nightsky                       # tonight's curated briefing\npondlog garden now                     # what to plant this week\n```\n\n`--json` works on every command for machine output.\n\n## Architecture\n\n```\n                          ┌─────────────────────────┐\n                          │      @pondlog/core      │\n                          │  types, Result<T>,      │\n                          │  RateLimiter, withRetry,│\n                          │  USDA zones, crops,     │\n                          │  companion graph        │\n                          └────────────┬────────────┘\n                                       │\n        ┌──────────┬──────────┬────────┼─────────┬──────────┬──────────┐\n        ▼          ▼          ▼        ▼         ▼          ▼          ▼\n source-inat  source-ebird  source-npn  source-usgs  source-mo  source-trefle  source-nightsky\n        │          │          │        │         │          │          │\n        └──────────┴──────────┴────────┼─────────┴──────────┴──────────┘\n                                       │\n                  ┌────────────────────┴────────────────────┐\n                  ▼                                         ▼\n            pondlog (CLI)                       7 × @pondlog/mcp-* servers\n            ├─ pondlog today (aggregate)         ├─ mcp-inaturalist\n            ├─ pondlog inat/ebird/...             ├─ mcp-ebird\n            └─ pondlog garden/nightsky            ├─ mcp-npn / mcp-usgs\n                                                  ├─ mcp-mushroomobserver\n                                                  ├─ mcp-garden\n                                                  └─ mcp-pondlog  ◀── aggregate\n```\n\nSource clients do all the work (Zod validation, rate limiting, retry,\nnormalization). The CLI and MCP servers are thin wrappers around them.\n\n## Design principles\n\n- **One data layer, two interfaces.** Each source is a typed library\n  (Zod-validated, rate-limited, returns `Result<T>`). The CLI and MCP\n  servers are thin wrappers. No business logic in them.\n- **Degrade gracefully.** When a source is down, the aggregate still\n  returns whatever else worked, with errors reported in-band.\n- **Rate limits respected.** Each client throttles itself. Never trust\n  the caller.\n- **No keys for what doesn't need them.** iNaturalist, NPN, USGS,\n  Mushroom Observer, and the night-sky source all run keyless. Only\n  eBird and Trefle require free keys.\n- **Local computation when the data isn't external.** Astronomy is\n  pure math; `@pondlog/source-nightsky` ships zero network calls,\n  zero rate limits, zero failure modes. The garden calendar, zones,\n  and companion graph are bundled JSON, all offline.\n\n## Related: CropGraph\n\n[CropGraph](https://api.cropgraph.com) is a sibling HTTP API exposing\nthe same ~1000-crop planting calendar, USDA hardiness zones, and\ncompanion-planting graph used by `@pondlog/core` and `@pondlog/mcp-garden`.\nUse CropGraph when you want the data over HTTP from any language. The\nschemas are kept in lockstep with this repo.\n\n## Contributing\n\nPRs welcome. The build is pnpm-based:\n\n```sh\ngit clone https://github.com/andrewschristison/pondlog.git\ncd pondlog\npnpm install\npnpm typecheck\npnpm build\npnpm test\npnpm smoke   # live tests against iNaturalist\n```\n\n### Crop calendar / companion-planting data\n\nThe crop calendar (`packages/core/src/data/crop-calendar.json`) and\ncompanion graph (`packages/core/src/data/companions.json`) accept\ncommunity PRs. Both have JSON Schemas alongside the data:\n\n- `packages/core/src/data/crop-calendar.schema.json`\n- `packages/core/src/data/companions.schema.json`\n\nWhen adding a crop entry, include a per-entry `source` citing a real\nextension service (USDA, Cornell, WSU, Oregon State, UMass, UF/IFAS,\netc.). When adding a companion edge, include `evidence` (`strong` or\n`moderate`) and a `citation` URL. Zod validation runs at module load,\nso a malformed PR breaks `import \"@pondlog/core\"` immediately.\n\n### Code\n\nEach package follows a strict pattern documented in\n[`docs/METHODOLOGY.md`](./docs/METHODOLOGY.md). Source clients always\nship before the CLI commands or MCP tools that consume them.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 9783,
  "sha": "0600858e102ba4e37630ed2c70ac51daad8872990902940954846d565c0439c7",
  "repo_slug": "andrewschristison/pondlog",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_andrewschristison_pondlog_gard_ac786dce/readme"
}