84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
## 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
|