birdweather-mcp 0.2.2__tar.gz

birdweather_mcp-0.2.2/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Env & secrets — never commit tokens
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Local reference scripts (not part of the published package)
+reference/
+
+# Misc
+*.db
+.uv/
+uv.lock
+dist/

birdweather_mcp-0.2.2/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] — 2026-11-14
+
+### Security
+
+- Compare HTTP bearer tokens with `hmac.compare_digest`; reject websocket scopes when `MCP_AUTH_TOKEN` is set; keep only exact `/health` public.
+- Raise `httpx`/`httpcore` loggers to WARNING; install a root logging filter that redacts station and MCP auth tokens (raw and URL-encoded); harden `_redact` and `_err` so unexpected errors never leak token-bearing URLs or tracebacks.
+- Warn at startup when HTTP binds a non-loopback host (or `MCP_ALLOWED_HOSTS=*`) without `MCP_AUTH_TOKEN` (still starts for compatibility).
+- Validate `station_id`, date windows (max 366 days), species query length, granularity/period enums, and allowlisted REST path segments; keep GraphQL values in variables.
+- Run the container as non-root (`USER app`, uid 10001); add `.dockerignore`; tighten compose with `read_only`, `cap_drop: ALL`, `no-new-privileges`, and `/tmp` tmpfs.
+- Pin GitHub Actions to full commit SHAs, set `permissions: contents: read`, `persist-credentials: false` on checkout, and add Dependabot for Actions/pip/Docker.
+- Expand `SECURITY.md` reporting policy, response expectations, and an HTTP hardening checklist; update configuration and self-hosting docs.
+
+## [0.2.1] — 2026-11-14
+
+### Changed
+
+- Documentation split into focused guides under `docs/` (installation, configuration, clients, tools, self-hosting, development, troubleshooting); README is a concise landing page.
+- Homebrew install documented (`brew install pfrederiksen/tap/birdweather-mcp`).
+
+## [0.2.0] — 2026-11-14
+
+### Added
+
+- MCP prompts: `daily_station_summary`, `weekly_report`, `species_deep_dive`.
+- MCP resources: `birdweather://station/{station_id}` and `birdweather://station/{station_id}/species`.
+- README demo illustration (`docs/assets/demo.svg`) with placeholder Example Station conversation.
+
+### Changed
+
+- Version bump to 0.2.0 consolidating reliability, packaging, analytics tools, and prompts/resources.
+
+## [0.1.4] — 2026-11-14
+
+### Added
+
+- Tools: `species_trend`, `first_of_year` / `new_arrivals`, `compare_stations`, `activity_by_hour` (with unit tests and docs/tools.md entries).
+- Detection payloads include `audio_url`, species image/thumbnail URLs, and `spectrogram_url` when the API provides them.
+
+## [0.1.3] — 2026-11-14
+
+### Added
+
+- GitHub Actions workflow to publish multi-arch Docker images to `ghcr.io/pfrederiksen/birdweather-mcp` (`latest` + SHA on `main`; semver on version tags).
+- PyPI-oriented packaging metadata and a trusted-publishing release workflow on version tags (configure the publisher on pypi.org; this repo does not publish automatically until that is set up).
+- Optional `MCP_AUTH_TOKEN` bearer auth for HTTP mode (`/health` stays open).
+- `server.json` for MCP registry metadata and [docs/clients.md](docs/clients.md) for Claude Desktop / Cursor / uvx / HTTP configs.
+
+### Changed
+
+- `docker-compose.yml` and self-hosting / Synology docs prefer pulling the prebuilt GHCR image; build-from-source remains an alternative.
+
+## [0.1.2] — 2026-11-14
+
+### Added
+
+- In-memory TTL response cache for GraphQL and REST (`BIRDWEATHER_CACHE_TTL`, `BIRDWEATHER_CACHE_MAX_ENTRIES`, `BIRDWEATHER_CACHE_ENABLED`).
+- Retries with exponential backoff and jitter on HTTP 429/5xx and timeouts (`BIRDWEATHER_MAX_RETRIES`).
+- `GET /health` liveness endpoint in streamable-HTTP mode (no upstream call); Dockerfile and compose healthchecks use it.
+- GitHub Actions CI: ruff + unit tests on Python 3.11–3.13 (no live tests).
+
+## [0.1.1] — 2026-11-14
+
+### Fixed
+
+- `daily_counts` now aggregates detections into station-local calendar days (GraphQL `dailyDetectionCounts` buckets by UTC and can return an extra day when `from == to`). Rows outside the requested range are omitted; quiet days are included with `total: 0`.
+
+### Added
+
+- `MCP_ALLOWED_HOSTS` for streamable-HTTP Host-header allowlisting (comma-separated, or `*` on trusted networks) to avoid `421 Invalid Host header` when clients use LAN/MagicDNS names.
+
+### Changed
+
+- Synology self-hosting docs: off-NAS `linux/arm64` buildx + image import, `env_file` for tokens, LAN bind + MagicDNS, Container Manager / error 2202 notes, free-port and folder-layout examples.
+
+## [0.1.0] — 2026-11-14
+
+### Added
+
+- MCP server with GraphQL tools: `get_station`, `station_counts`, `get_weather`, `recent_detections`, `top_species` / `species_list`, `daily_counts`, `species_info`, `search_species`, `search_stations`.
+- Optional `BIRDWEATHER_STATION_TOKEN` for station REST detections and all-time stats (token never logged).
+- Transports: `stdio` (default), `streamable-http`, `sse`.
+- Dockerfile (`python:3.12-slim`, multi-arch friendly) and `docker-compose.yml` for long-lived HTTP hosting.
+- Docs: README, self-hosting guide, tool reference with live samples, contributing, security policy.
+- Pytest suite with mocked unit tests and optional `@pytest.mark.live` smoke (set `BIRDWEATHER_TEST_STATION_ID`).
+
+[0.2.2]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.2.2
+[0.2.1]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.2.1
+[0.2.0]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.2.0
+[0.1.4]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.1.4
+[0.1.3]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.1.3
+[0.1.2]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.1.2
+[0.1.1]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.1.1
+[0.1.0]: https://github.com/pfrederiksen/birdweather-mcp/releases/tag/v0.1.0

birdweather_mcp-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Frederiksen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

birdweather_mcp-0.2.2/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: birdweather-mcp
+Version: 0.2.2
+Summary: Self-hostable MCP server for BirdWeather stations (detections, species, stats).
+Project-URL: Homepage, https://github.com/pfrederiksen/birdweather-mcp
+Project-URL: Documentation, https://github.com/pfrederiksen/birdweather-mcp#readme
+Project-URL: Repository, https://github.com/pfrederiksen/birdweather-mcp
+Project-URL: Issues, https://github.com/pfrederiksen/birdweather-mcp/issues
+Project-URL: Changelog, https://github.com/pfrederiksen/birdweather-mcp/blob/main/CHANGELOG.md
+Author-email: Paul Frederiksen <pfrederiksen@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: birdnet,birds,birdweather,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/header.jpg" alt="birdweather-mcp" width="100%" />
+</p>
+
+<p align="center"><em>Ask your AI about the birds your station is hearing — detections, species, and stats via MCP.</em></p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP compatible" /></a>
+  <a href="docs/self-hosting.md"><img src="https://img.shields.io/badge/docker-ready-2496ED.svg" alt="Docker ready" /></a>
+</p>
+
+# birdweather-mcp
+
+Self-hostable [MCP](https://modelcontextprotocol.io) server for [BirdWeather](https://www.birdweather.com). Point Claude, Cursor, or any MCP client at your (or any public) station and ask natural-language questions about what was detected, what’s trending, and what’s nearby.
+
+Works out of the box against the **public GraphQL API** — no account required. Optionally set a **station token** for richer REST fields. **The token is never logged or echoed.**
+
+## Features
+
+- **15 MCP tools** — station info, counts, weather, detections, top species, daily series, species trends, new arrivals, station compare, hourly activity, species search/profiles, nearby stations
+- **Prompts & resources** — daily/weekly summaries, species deep-dives, and `birdweather://station/…` URIs
+- **No auth required** for public GraphQL; optional `BIRDWEATHER_STATION_TOKEN` for REST
+- **stdio** (Claude Desktop / Cursor) or **streamable-HTTP** (Docker / Synology / Tailscale)
+- **Token-safe** — redacted in logs and errors ([SECURITY.md](SECURITY.md))
+- **Docker + compose** — prebuilt multi-arch images on GHCR (`ghcr.io/pfrederiksen/birdweather-mcp`)
+
+## Quickstart
+
+**uvx** (no clone):
+
+```bash
+uvx birdweather-mcp
+```
+
+**Homebrew:**
+
+```bash
+brew install pfrederiksen/tap/birdweather-mcp
+birdweather-mcp
+```
+
+**Docker** (stdio):
+
+```bash
+docker pull ghcr.io/pfrederiksen/birdweather-mcp:latest
+docker run --rm -i ghcr.io/pfrederiksen/birdweather-mcp:latest
+```
+
+Long-lived HTTP on a NAS → [Self-hosting](docs/self-hosting.md). More install paths → [Installation](docs/installation.md).
+
+Configure Claude Desktop / Cursor / VS Code → [Clients](docs/clients.md).
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [docs/README.md](docs/README.md) | Index of all guides |
+| [Installation](docs/installation.md) | uvx, pip, Homebrew, Docker/GHCR, from source |
+| [Configuration](docs/configuration.md) | Environment variables, station ID/token |
+| [Clients](docs/clients.md) | Claude Desktop, Cursor, Claude Code, VS Code, HTTP |
+| [Tools](docs/tools.md) | Tools, prompts, and resources |
+| [Self-hosting](docs/self-hosting.md) | Docker, Synology/arm64, LAN/Tailscale, updates |
+| [Development](docs/development.md) | Dev setup, tests, lint, release process |
+| [Troubleshooting](docs/troubleshooting.md) | Common problems and FAQ |
+
+## Demo
+
+<p align="center">
+  <img src="docs/assets/demo.svg" alt="Demo conversation about Example Station 12345" width="100%" />
+</p>
+
+Placeholder illustration of asking an MCP client about **Example Station** (`12345`) — not live data.
+
+## License
+
+Licensed under [MIT](LICENSE). See also [CHANGELOG.md](CHANGELOG.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [SECURITY.md](SECURITY.md).

birdweather_mcp-0.2.2/README.md

@@ -0,0 +1,78 @@
+<p align="center">
+  <img src="docs/assets/header.jpg" alt="birdweather-mcp" width="100%" />
+</p>
+
+<p align="center"><em>Ask your AI about the birds your station is hearing — detections, species, and stats via MCP.</em></p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP compatible" /></a>
+  <a href="docs/self-hosting.md"><img src="https://img.shields.io/badge/docker-ready-2496ED.svg" alt="Docker ready" /></a>
+</p>
+
+# birdweather-mcp
+
+Self-hostable [MCP](https://modelcontextprotocol.io) server for [BirdWeather](https://www.birdweather.com). Point Claude, Cursor, or any MCP client at your (or any public) station and ask natural-language questions about what was detected, what’s trending, and what’s nearby.
+
+Works out of the box against the **public GraphQL API** — no account required. Optionally set a **station token** for richer REST fields. **The token is never logged or echoed.**
+
+## Features
+
+- **15 MCP tools** — station info, counts, weather, detections, top species, daily series, species trends, new arrivals, station compare, hourly activity, species search/profiles, nearby stations
+- **Prompts & resources** — daily/weekly summaries, species deep-dives, and `birdweather://station/…` URIs
+- **No auth required** for public GraphQL; optional `BIRDWEATHER_STATION_TOKEN` for REST
+- **stdio** (Claude Desktop / Cursor) or **streamable-HTTP** (Docker / Synology / Tailscale)
+- **Token-safe** — redacted in logs and errors ([SECURITY.md](SECURITY.md))
+- **Docker + compose** — prebuilt multi-arch images on GHCR (`ghcr.io/pfrederiksen/birdweather-mcp`)
+
+## Quickstart
+
+**uvx** (no clone):
+
+```bash
+uvx birdweather-mcp
+```
+
+**Homebrew:**
+
+```bash
+brew install pfrederiksen/tap/birdweather-mcp
+birdweather-mcp
+```
+
+**Docker** (stdio):
+
+```bash
+docker pull ghcr.io/pfrederiksen/birdweather-mcp:latest
+docker run --rm -i ghcr.io/pfrederiksen/birdweather-mcp:latest
+```
+
+Long-lived HTTP on a NAS → [Self-hosting](docs/self-hosting.md). More install paths → [Installation](docs/installation.md).
+
+Configure Claude Desktop / Cursor / VS Code → [Clients](docs/clients.md).
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [docs/README.md](docs/README.md) | Index of all guides |
+| [Installation](docs/installation.md) | uvx, pip, Homebrew, Docker/GHCR, from source |
+| [Configuration](docs/configuration.md) | Environment variables, station ID/token |
+| [Clients](docs/clients.md) | Claude Desktop, Cursor, Claude Code, VS Code, HTTP |
+| [Tools](docs/tools.md) | Tools, prompts, and resources |
+| [Self-hosting](docs/self-hosting.md) | Docker, Synology/arm64, LAN/Tailscale, updates |
+| [Development](docs/development.md) | Dev setup, tests, lint, release process |
+| [Troubleshooting](docs/troubleshooting.md) | Common problems and FAQ |
+
+## Demo
+
+<p align="center">
+  <img src="docs/assets/demo.svg" alt="Demo conversation about Example Station 12345" width="100%" />
+</p>
+
+Placeholder illustration of asking an MCP client about **Example Station** (`12345`) — not live data.
+
+## License
+
+Licensed under [MIT](LICENSE). See also [CHANGELOG.md](CHANGELOG.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [SECURITY.md](SECURITY.md).

birdweather_mcp-0.2.2/docs/README.md

@@ -0,0 +1,15 @@
+# Documentation
+
+Guides for installing, configuring, and running [birdweather-mcp](../README.md).
+
+| Guide | Description |
+|-------|-------------|
+| [Installation](installation.md) | uvx, pip, Homebrew, Docker/GHCR, from source |
+| [Configuration](configuration.md) | Environment variables, defaults, station ID/token |
+| [Clients](clients.md) | Claude Desktop, Cursor, Claude Code, VS Code, HTTP |
+| [Tools](tools.md) | MCP tools, prompts, and resources |
+| [Self-hosting](self-hosting.md) | Docker, compose, Synology/arm64, LAN/Tailscale |
+| [Development](development.md) | Dev setup, tests, lint, release process |
+| [Troubleshooting](troubleshooting.md) | Common problems and FAQ |
+
+Also see [SECURITY.md](../SECURITY.md), [CHANGELOG.md](../CHANGELOG.md), and [CONTRIBUTING.md](../CONTRIBUTING.md).

birdweather_mcp-0.2.2/docs/assets/demo.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540" viewBox="0 0 960 540" role="img" aria-labelledby="title desc">
+  <title id="title">birdweather-mcp demo conversation</title>
+  <desc id="desc">Example chat asking about Example Station 12345 detections with placeholder data.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#1a2f28"/>
+      <stop offset="55%" stop-color="#243f36"/>
+      <stop offset="100%" stop-color="#3d5a4c"/>
+    </linearGradient>
+    <linearGradient id="panel" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#f7f3ea"/>
+      <stop offset="100%" stop-color="#ebe4d6"/>
+    </linearGradient>
+    <filter id="soft" x="-10%" y="-10%" width="120%" height="120%">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#0b1612" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+
+  <rect width="960" height="540" fill="url(#bg)"/>
+  <!-- soft foliage shapes -->
+  <circle cx="70" cy="480" r="120" fill="#2f4a3f" opacity="0.55"/>
+  <circle cx="900" cy="40" r="140" fill="#2a4439" opacity="0.45"/>
+  <circle cx="820" cy="500" r="90" fill="#4a6b58" opacity="0.25"/>
+
+  <text x="48" y="52" fill="#d8e5dd" font-family="Georgia, 'Times New Roman', serif" font-size="28" font-weight="700">birdweather-mcp</text>
+  <text x="48" y="78" fill="#a9c0b4" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13">Ask your AI what station 12345 has been hearing</text>
+
+  <rect x="48" y="108" width="864" height="380" rx="18" fill="url(#panel)" filter="url(#soft)"/>
+
+  <!-- user bubble -->
+  <rect x="420" y="140" width="460" height="64" rx="14" fill="#2f5d4a"/>
+  <text x="440" y="168" fill="#f4faf6" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15">What has Example Station been hearing this week?</text>
+  <text x="440" y="188" fill="#c5ddd2" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12">station_id 12345 · last 7 days</text>
+
+  <!-- assistant bubble -->
+  <rect x="80" y="230" width="620" height="210" rx="14" fill="#ffffff" stroke="#d7cfbf"/>
+  <text x="100" y="258" fill="#1f2a24" font-family="Georgia, 'Times New Roman', serif" font-size="16" font-weight="700">Assistant</text>
+  <text x="100" y="286" fill="#334038" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14">Called top_species + station_counts for Example Station.</text>
+  <text x="100" y="312" fill="#334038" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14">• House Finch — 273 detections</text>
+  <text x="100" y="334" fill="#334038" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14">• Anna&#39;s Hummingbird — 51</text>
+  <text x="100" y="356" fill="#334038" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14">• ~497 detections · 31 species</text>
+  <text x="100" y="386" fill="#5b6b62" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12">Timezone America/Los_Angeles · placeholder sample data</text>
+  <text x="100" y="412" fill="#2f5d4a" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12">soundscape.url available on recent_detections when present</text>
+
+  <text x="48" y="520" fill="#8eaa9b" font-family="ui-sans-serif, system-ui, sans-serif" font-size="11">Demo illustration · no live station data</text>
+</svg>

birdweather_mcp-0.2.2/docs/clients.md

@@ -0,0 +1,141 @@
+# MCP client configurations
+
+Configure Claude Desktop, Cursor, and other MCP clients to talk to birdweather-mcp over **stdio** (local process), **uvx** / Homebrew, or **streamable-HTTP** (self-hosted Docker / NAS).
+
+Use placeholder station id `12345` in prompts. Never put a real `BIRDWEATHER_STATION_TOKEN` or `MCP_AUTH_TOKEN` in committed files. Env reference: [configuration.md](configuration.md). Install paths: [installation.md](installation.md).
+
+## stdio via uvx (recommended for desktop clients)
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "command": "uvx",
+      "args": ["birdweather-mcp"]
+    }
+  }
+}
+```
+
+From git:
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/pfrederiksen/birdweather-mcp", "birdweather-mcp"]
+    }
+  }
+}
+```
+
+## stdio via Homebrew
+
+After `brew install pfrederiksen/tap/birdweather-mcp`:
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "command": "birdweather-mcp"
+    }
+  }
+}
+```
+
+Optional env:
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "command": "uvx",
+      "args": ["birdweather-mcp"],
+      "env": {
+        "BIRDWEATHER_STATION_TOKEN": ""
+      }
+    }
+  }
+}
+```
+
+## stdio via local checkout
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/birdweather-mcp", "birdweather-mcp"]
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the Windows equivalent. Use either uvx block above under `mcpServers`.
+
+## Cursor
+
+Project `.cursor/mcp.json` or Cursor MCP settings — same `mcpServers` shape as Claude Desktop.
+
+## Claude Code
+
+```bash
+claude mcp add birdweather -- uvx birdweather-mcp
+# or from git:
+claude mcp add birdweather -- uvx --from git+https://github.com/pfrederiksen/birdweather-mcp birdweather-mcp
+```
+
+## VS Code
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "birdweather": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["birdweather-mcp"]
+    }
+  }
+}
+```
+
+## streamable-HTTP (Docker / Synology / LAN)
+
+Run the server (see [self-hosting.md](self-hosting.md)), then point the client at `/mcp`:
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+
+If `MCP_AUTH_TOKEN` is set on the server, send a bearer header (exact client support varies):
+
+```json
+{
+  "mcpServers": {
+    "birdweather": {
+      "url": "http://127.0.0.1:8000/mcp",
+      "headers": {
+        "Authorization": "Bearer <your-mcp-auth-token>"
+      }
+    }
+  }
+}
+```
+
+`GET /health` stays unauthenticated for probes. Prefer LAN / Tailscale over public exposure — see [SECURITY.md](../SECURITY.md).
+
+## Registry metadata
+
+[`server.json`](../server.json) describes this server for the official MCP registry (PyPI + GHCR package entries). Publishing to the registry is a separate step after PyPI/GHCR packages exist.

birdweather_mcp-0.2.2/docs/configuration.md

@@ -0,0 +1,61 @@
+# Configuration
+
+All settings are environment variables (or CLI flags that mirror the transport trio). Copy [`.env.example`](../.env.example) for a local template. **Never commit real tokens.**
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BIRDWEATHER_STATION_TOKEN` | No | unset | Station API token for REST detections / all-time stats. **Never logged.** Without it, public GraphQL only. |
+| `MCP_TRANSPORT` | No | `stdio` | `stdio`, `streamable-http`, or `sse`. Overridable with `--transport`. |
+| `MCP_HOST` | No | `127.0.0.1` | Bind host for HTTP transports. Overridable with `--host`. Inside Docker use `0.0.0.0` and restrict with host port publish (prefer `127.0.0.1` or LAN-only on the host). Non-loopback bind without `MCP_AUTH_TOKEN` logs a SECURITY warning. |
+| `MCP_PORT` | No | `8000` | Bind port for HTTP transports. Overridable with `--port`. |
+| `MCP_ALLOWED_HOSTS` | No | unset (loopback only) | Comma-separated Host header patterns for streamable-HTTP DNS-rebinding protection (e.g. `nas.example.local:*,192.168.1.10:*`). Unset = FastMCP loopback defaults. `*` = allow any host (**trusted networks only**; warns if `MCP_AUTH_TOKEN` is unset). Fixes `421 Invalid Host header` for MagicDNS/LAN names. |
+| `MCP_AUTH_TOKEN` | No | unset | When set, HTTP `/mcp` requires `Authorization: Bearer …` (constant-time compare). Exact `/health` stays open; websockets are rejected. Strongly recommended for non-loopback HTTP. Never logged. |
+| `BIRDWEATHER_CACHE_TTL` | No | `60` | In-memory upstream cache TTL in seconds. Set `0` to disable. |
+| `BIRDWEATHER_CACHE_MAX_ENTRIES` | No | `256` | Max cached GraphQL/REST responses. |
+| `BIRDWEATHER_CACHE_ENABLED` | No | enabled when TTL > 0 | Set `false` / `0` / `no` / `off` to disable caching; `true` / `1` / `yes` / `on` to force on. |
+| `BIRDWEATHER_MAX_RETRIES` | No | `5` | Retries with exponential backoff + jitter on HTTP 429/5xx and timeouts (minimum effective value `1`). |
+| `BIRDWEATHER_TEST_STATION_ID` | No | unset | Public station id for optional live pytest (`pytest -m live`). Prefer shell-only; do not commit a personal id. |
+
+### Logging
+
+The server logs to stderr at **INFO** with format `%(levelname)s %(name)s: %(message)s`. There is no log-level env var today. Station and MCP auth tokens are **never** written to logs or tool/error payloads (raw and URL-encoded forms are redacted via a logging filter; `httpx`/`httpcore` are set to WARNING so request URLs are not printed). See [SECURITY.md](../SECURITY.md).
+
+### Health endpoint
+
+In `streamable-http` mode, `GET /health` returns `{"status":"ok","version":"..."}` with **no** upstream BirdWeather call. Used by Docker/compose healthchecks. Unaffected by `MCP_AUTH_TOKEN` (exact path only — `/health/../mcp` is not public).
+
+## Finding a station ID and token
+
+**Station ID** (public, numeric — docs use `12345`):
+
+1. Open your station on [app.birdweather.com](https://app.birdweather.com) (web) or in the BirdWeather app.
+2. Check the URL: `https://app.birdweather.com/stations/<id>` — that number is `station_id`.
+3. Or search by name/coords with the `search_stations` tool once the server is running.
+
+**Station token** (secret — optional):
+
+1. In the BirdWeather app or web UI, open **your** station’s settings.
+2. Find the **API / token** section (used for `https://app.birdweather.com/api/v1/stations/<token>/...`).
+3. Copy into `BIRDWEATHER_STATION_TOKEN` in MCP config or `.env` — never commit it.
+
+Without a token, all GraphQL tools still work for any public station. With a token, `get_station` can include all-time REST stats and `recent_detections` prefers REST (extra fields).
+
+## CLI flags
+
+```bash
+birdweather-mcp --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+| Flag | Env equivalent |
+|------|----------------|
+| `--transport` | `MCP_TRANSPORT` |
+| `--host` | `MCP_HOST` |
+| `--port` | `MCP_PORT` |
+
+## Related
+
+- [Clients](clients.md) — where to put env in Claude / Cursor / HTTP
+- [Self-hosting](self-hosting.md) — Docker, Synology, `MCP_ALLOWED_HOSTS`
+- [Troubleshooting](troubleshooting.md)