clawfort/openspec/specs/mcp-image-provider-integration/spec.md

Purpose

Canonical specification for mcp-image-provider-integration requirements synced from OpenSpec change deltas.

Requirements

Requirement: Pixabay image retrieval

The system SHALL support retrieving images from Pixabay API when PIXABAY_API_KEY is configured.

Scenario: Successful Pixabay image search

• WHEN Pixabay is enabled in provider chain AND query is "artificial intelligence breakthrough"
• THEN system sends GET request to https://pixabay.com/api/?key={key}&q=artificial+intelligence+breakthrough&image_type=photo&per_page=3&safesearch=true
• AND returns first hit's webformatURL as image URL
• AND returns credit as "Photo by {user} on Pixabay"

Scenario: Pixabay returns no results

• WHEN Pixabay search returns empty hits array
• THEN system returns (None, None) for this provider
• AND fallback chain continues to next provider

Scenario: Pixabay API key not configured

• WHEN PIXABAY_API_KEY environment variable is empty or unset
• THEN Pixabay provider is skipped in the fallback chain

Requirement: Unsplash image retrieval

The system SHALL support retrieving images from Unsplash API when UNSPLASH_ACCESS_KEY is configured.

Scenario: Successful Unsplash image search

• WHEN Unsplash is enabled in provider chain AND query is "machine learning robot"
• THEN system sends GET request to https://api.unsplash.com/search/photos?query=machine+learning+robot&per_page=3 with header Authorization: Client-ID {key}
• AND returns first result's urls.regular as image URL
• AND returns credit as "Photo by {user.name} on Unsplash"

Scenario: Unsplash returns no results

• WHEN Unsplash search returns empty results array
• THEN system returns (None, None) for this provider
• AND fallback chain continues to next provider

Scenario: Unsplash API key not configured

• WHEN UNSPLASH_ACCESS_KEY environment variable is empty or unset
• THEN Unsplash provider is skipped in the fallback chain

Requirement: Pexels image retrieval

The system SHALL support retrieving images from Pexels API when PEXELS_API_KEY is configured.

Scenario: Successful Pexels image search

• WHEN Pexels is enabled in provider chain AND query is "tech startup office"
• THEN system sends GET request to https://api.pexels.com/v1/search?query=tech+startup+office&per_page=3 with header Authorization: {key}
• AND returns first photo's src.large as image URL
• AND returns credit as "Photo by {photographer} on Pexels"

Scenario: Pexels returns no results

• WHEN Pexels search returns empty photos array
• THEN system returns (None, None) for this provider
• AND fallback chain continues to next provider

Scenario: Pexels API key not configured

• WHEN PEXELS_API_KEY environment variable is empty or unset
• THEN Pexels provider is skipped in the fallback chain

Requirement: Provider timeout handling

Each provider API call SHALL timeout after 15 seconds.

Scenario: Provider request timeout

• WHEN provider API does not respond within 15 seconds
• THEN system logs timeout warning
• AND returns (None, None) for this provider
• AND fallback chain continues to next provider

Requirement: Provider error handling

The system SHALL gracefully handle provider API errors without crashing.

Scenario: Provider returns HTTP error

• WHEN provider API returns 4xx or 5xx status code
• THEN system logs error with status code
• AND returns (None, None) for this provider
• AND fallback chain continues to next provider

Scenario: Provider returns malformed response

• WHEN provider API returns invalid JSON or unexpected schema
• THEN system logs parsing error
• AND returns (None, None) for this provider
• AND fallback chain continues to next provider