Pondlog Phenology (USA-NPN)

pondlog

開発者向けの場所に基づく自然データです。今、この座標で自然界では何が起きているでしょうか？

pondlog は、無料の公開 API（iNaturalist、eBird、USA-NPN、USGS、Mushroom Observer）に、ローカルでの天文計算 （astronomy-engine）と NOAA の潮汐・雲量データを組み合わせ、2 つのインターフェースを備えたデータレイヤーを提供します。

• 人向けの CLI（pondlog inat nearby --lat 48.118 --lng -123.43）
• AI エージェント（Claude Desktop、Cursor）向けのソースごとの MCP サーバー

Andrew Christison によるプロジェクトです。

内容

8 つのデータソース。7 つの MCP サーバー。1 つの統合 CLI。USDA 耐寒性ゾーンとコンパニオンプランティングのグラフを備えた、約 1000 種の作物に対応するガーデンプランナーです。

パッケージ	npm	機能
pondlog		統合 CLI
@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 エージェントとして（MCP）

Claude Desktop の設定に追加します （macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

次のように Claude に尋ねます：

過去1週間に、WA州ポートエンジェルス付近で目撃された両生類はいますか？

同じ JSON は、Cursor の ~/.cursor/mcp.json でも使用できます。任意の MCP サーバーを1つのコマンドで実行できます：

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 サーバーは、その薄いラッパーです。

設計原則

• データレイヤーは1つ、インターフェースは2つ。 各ソースは型付きライブラリです（Zod による検証、レート制限を備え、Result<T> を返します）。CLI と MCP サーバーは薄いラッパーです。そこにビジネスロジックはありません。
• 障害があっても適切に処理します。 ソースが停止している場合でも、集約処理は他に正常に動作したソースの結果を返し、エラーも結果に含めて報告します。
• レート制限を遵守します。 各クライアントが自身のリクエストを調整します。呼び出し元を信用してはいけません。
• 不要なキーは求めません。 iNaturalist、NPN、USGS、Mushroom Observer、夜空のソースはすべてキーなしで動作します。無料キーが必要なのは eBird と Trefle だけです。
• データが外部にない場合はローカルで計算します。 天文学は純粋な数学です。@pondlog/source-nightsky はネットワーク呼び出しも、レート制限も、障害要因も一切ありません。庭のカレンダー、ゾーン、コンパニオンプランツのグラフは JSON に同梱されており、すべてオフラインで利用できます。

関連プロジェクト：CropGraph

CropGraph は、@pondlog/core と @pondlog/mcp-garden で使用されている約1,000作物の栽培カレンダー、USDA 耐寒性ゾーン、コンパニオンプランツのグラフと同じデータを公開する姉妹 HTTP API です。任意の言語から 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

作物のエントリーを追加する場合は、実在する普及機関（USDA、Cornell、WSU、Oregon State、UMass、UF/IFAS など）を引用する source をエントリーごとに記載してください。コンパニオンの関連を追加する場合は、evidence（strong または moderate）と citation URL を記載してください。Zod による検証はモジュールの読み込み時に実行されるため、不正な PR があると import "@pondlog/core" は直ちに失敗します。

コード

各パッケージは、docs/METHODOLOGY.md に記載されている厳格なパターンに従います。ソースクライアントは、それを使用する CLI コマンドや MCP ツールより先に提供されます。

ライセンス

MIT。詳細は LICENSE をご覧ください。