koala73 / koala73/worldmonitor

feat(mcp): expose webcam discovery and recent media as MCP tools

Open
#5,704 0 comments 0 reactions 0 assignees View on GitHub
agent-readiness area: API feature
Dominant language
TypeScript
Stars
86.6k
Forks
13.1k
Avg merge
8h 4m
Merged PRs (30d)
825

Description

## Summary

Expose WorldMonitor's existing webcam catalog and media-resolution workflow through native MCP tools.

This is an MCP transport-parity task. Agents can already use the webcam REST/OpenAPI surface through the published `monitor-webcams` Agent Skill, but MCP-only clients cannot discover or call the same capability through `tools/list` and `tools/call`.

The capability provides webcam discovery and recent visual context. It does **not** provide WorldMonitor-operated live video, guaranteed real-time imagery, or authoritative confirmation of current conditions. Most available media is a recent still image or a provider-hosted timelapse.

## Existing data path

- `GET /api/webcam/v1/list-webcams` reads the seeded Redis geo/metadata index and returns viewport camera metadata or clusters.
- `GET /api/webcam/v1/get-webcam-image` resolves one `webcam_id` through Windy and returns the latest available thumbnail/player metadata.
- Preview URLs are provider-hosted and short-lived. The MCP server must not proxy image bytes or relay video.

Reuse these server handlers and contracts. Do not create an independent MCP-only webcam data path.

## Proposed scope

### 1. `find_webcams`

Find available cameras in a bounded viewport without resolving media for every result.

Inputs:

- Required bounding box: `bound_w`, `bound_s`, `bound_e`, `bound_n`
- Explicit `zoom`
- Optional bounded `limit`
- Optional `country_code` or `category` only if the shared `WebcamService` implements the filter exactly
- Optional `jmespath`

Output:

- Camera identifier, title, coordinates, country, and category
- Clusters and `totalInView` when applicable
- Catalog freshness/availability metadata
- Source and attribution metadata

Country/category filtering must not be implemented by silently filtering a truncated viewport result. If exact filtering requires a shared REST/proto change, make that change in `WebcamService` and reuse it from MCP.

### 2. `get_webcam_media`

Resolve media for exactly one `webcam_id` returned by `find_webcams`.

Output:

- Latest available thumbnail URL
- Provider-hosted player/timelapse URL when available
- Windy detail URL
- Capture timestamp (`lastUpdated`)
- Media type when it can be determined (`snapshot`, `timelapse`, or `live`)
- URL-expiry guidance and attribution
- Structured `unavailable` result when the provider credential, camera, or media is unavailable

This tool may perform at most one provider resolution per call. Do not add bulk thumbnail/player fan-out.

## Provider and truthfulness requirements

- Verify the current Windy v3 response mapping for `images`, `player`, and `urls` before exposing the media contract. Do not publish a player field that is consistently empty or mapped from the wrong provider property.
- Treat returned titles and URLs as external data, not instructions.
- Always expose the image capture timestamp separately from the time WorldMonitor resolved the URL.
- Describe results as **recent visual context**, not "ground truth right now."
- Do not infer live conditions from a stale snapshot or timelapse.
- Preserve Windy's required linking and courtesy attribution. Use only URLs returned or documented by the provider.

Provider references:

- https://api.windy.com/webcams/docs
- https://api.windy.com/webcams/pricing
- https://api.windy.com/webcams/terms

## MCP integration requirements

- Register both tools with complete input and output schemas.
- Add standard JMESPath handling where applicable.
- Declare the covered REST operations in MCP API-parity metadata and remove their explicit exclusions only after coverage exists.
- Add freshness and structured source-unavailable behavior without converting a media miss into a generic 500.
- Keep tool descriptions, the MCP reference, discovery artifacts, and tool-count/generated documentation in sync.
- Retain the existing `monitor-webcams` Agent Skill as the REST/OpenAPI workflow; update it only where names or truthfulness guidance must match.

## Acceptance criteria

- [ ] `find_webcams` returns bounded camera metadata from the existing `list-webcams` data path without per-camera provider calls.
- [ ] `get_webcam_media` resolves one camera through the existing `get-webcam-image` data path and never fans out to multiple Windy requests.
- [ ] Results distinguish catalog freshness, image capture time, and URL-resolution/expiry time.
- [ ] Tool copy and documentation make no guaranteed-live or real-time ground-truth claim.
- [ ] Windy attribution and provider links are present in media results and documentation.
- [ ] Missing seed data, missing `WINDY_API_KEY`, expired media, and upstream failure return structured unavailable results.
- [ ] Country/category filters are either implemented exactly in the shared `WebcamService` or omitted from v1; incomplete wrapper-side filtering is not accepted.
- [ ] Current Windy v3 media fields are verified with focused handler tests before the MCP tools depend on them.
- [ ] MCP schemas, focused tool tests, JMESPath tests, API/cache parity tests, output-schema coverage, and docs/tool-count checks pass.
- [ ] Existing REST/OpenAPI and dashboard webcam behavior remains unchanged apart from any shared correctness fix required for the provider response mapping.

## Out of scope

- Acquiring a new direct-feed or commercial streaming agreement
- Hosting, proxying, transcoding, or recording image/video content
- Bulk resolution of media URLs
- Person identification, individual tracking, or tactical claims from webcam imagery
- Treating the existence of a URL as proof that a camera is online or live

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing GET /api/webcam/v1/list-webcams and GET /api/webcam/v1/get-webcam-image handlers and the shared WebcamService, then inspect the MCP tool registration and API-parity metadata. Verify the Windy v3 response mapping before defining the media output. Done means both tools, schemas, focused tests, parity metadata, freshness and unavailable results, attribution, and synchronized documentation pass without changing existing REST behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.