Metadata-Version: 2.4
Name: meural
Version: 0.1.0
Summary: Python client library and MCP server for Meural Canvas digital art frames
Project-URL: Homepage, https://github.com/mikelambert/meural_api
Project-URL: Repository, https://github.com/mikelambert/meural_api
Project-URL: Issues, https://github.com/mikelambert/meural_api/issues
Author-email: Mike Lambert <mlambert@gmail.com>
License: MIT
Keywords: api,digital-art,mcp,meural,smart-home
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.10
Requires-Dist: pycognito>=2024.5.1
Requires-Dist: requests>=2.28.0
Provides-Extra: all
Requires-Dist: click>=8.0.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Requires-Dist: tabulate>=0.9.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == 'cli'
Requires-Dist: tabulate>=0.9.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Meural

Python client library and MCP server for Meural Canvas digital art frames.

## Installation

```bash
pip install meural
```

For MCP server support:
```bash
pip install meural[mcp]
```

For CLI support:
```bash
pip install meural[cli]
```

For all features:
```bash
pip install meural[all]
```

## Quick Start

### As a Library

```python
from meural import MeuralAPI

# Initialize with credentials
api = MeuralAPI(username="your@email.com", password="your_password")

# Or from environment variables (MEURAL_USERNAME, MEURAL_PASSWORD)
api = MeuralAPI.from_env()

# Get user info
user = api.get_user()

# List devices
devices = api.get_user_devices()

# Get galleries
galleries = api.get_user_galleries()

# Search for art
results = api.search("monet")

# Preview an image on device
api.post_device_preview(device_id="12345", item_id="67890")
```

### CLI Usage

```bash
# Set credentials
export MEURAL_USERNAME="your@email.com"
export MEURAL_PASSWORD="your_password"

# List devices
meural-cli device list

# Show device details
meural-cli device show

# List galleries
meural-cli gallery list

# Search for art
meural-cli browse search "van gogh"

# Set brightness
meural-cli device brightness 50
```

### MCP Server

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "meural": {
      "command": "uv",
      "args": ["--directory", "/path/to/meural_api", "run", "python", "-m", "scripts.meural_mcp"],
      "env": {
        "MEURAL_USERNAME": "your@email.com",
        "MEURAL_PASSWORD": "your_password"
      }
    }
  }
}
```

Available MCP tools:
- `meural_get_device` - Get device info and status
- `meural_list_galleries` - List user's galleries/playlists
- `meural_get_gallery` - Get gallery details with items
- `meural_search` - Search Meural catalog
- `meural_preview_item` - Preview an image on device (60 seconds)
- `meural_push_gallery` - Push a gallery to device
- `meural_device_galleries` - List galleries on device
- `meural_set_brightness` - Set device brightness
- `meural_set_image` - Display an image on device

## Authentication

The library uses AWS Cognito for authentication. Tokens are automatically cached and refreshed.

Credentials can be provided via:
1. Constructor arguments
2. Environment variables (`MEURAL_USERNAME`, `MEURAL_PASSWORD`)
3. Credentials file (`~/.meural`)

## API Coverage

The library covers the Meural API v4 including:
- User management
- Device control (brightness, sleep/wake, settings)
- Gallery/playlist management
- Item uploads and management
- Favorites
- Content discovery (channels, artists, categories)
- Search

## License

MIT
