# Vestaboard MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server for controlling Vestaboard displays via both cloud and local APIs.

## Features

- **Cloud API Support**: Send messages, read current display, manage transitions
- **Local API Support**: Direct control of devices on your network
- **Message Formatting**: Convert text to character codes automatically
- **Animation Effects**: Animate message display with multiple strategies
- **Environment Configuration**: Use `.env` files for API credentials (minimal deps)
- **Type Safe**: Full Python type hints with mypy support

## Installation

### Prerequisites
- Python 3.10+
- A Vestaboard device

### Setup

```bash
# Clone and install
git clone https://github.com/lintility/vestaboard-mcp.git
cd vestaboard-mcp
pip install -e .

# Configure credentials
cp src/.env.example .env
```

Edit `.env` with your API credentials:
- `VESTABOARD_CLOUD_TOKEN`: Get from https://www.vestaboard.com/account/integrations
- `VESTABOARD_LOCAL_ENABLEMENT_TOKEN`: Sent via email by Vestaboard
- `VESTABOARD_LOCAL_API_KEY`: Auto-populated after enabling local API (optional)

## Usage

### Run the Server

```bash
python -m src.server
```

### Configure with Claude

Add to `~/.config/claude/mcp.json`:

```json
{
  "mcpServers": {
    "vestaboard": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/vestaboard-mcp",
      "env": {
        "VESTABOARD_CLOUD_TOKEN": "your_token",
        "VESTABOARD_LOCAL_API_KEY": "your_local_key"
      }
    }
  }
}
```

## Available Tools

### Cloud API

- **cloud_read_message**: Get current display
- **cloud_send_message**: Send text or character codes
- **cloud_format_message**: Convert text to character codes
- **cloud_get_transition**: Get transition settings
- **cloud_set_transition**: Set animation effects (wave, drift, curtain, classic)

### Local API

- **local_enable_api**: Activate local API (one-time setup)
- **local_send_message**: Send message with optional animation
- **local_read_message**: Read current display

## Project Structure

```
vestaboard-mcp/
├── src/
│   ├── server.py           # MCP server implementation
│   ├── vestaboard.py       # API client classes
│   └── .env.example        # Configuration template
├── tests/
│   └── test_server.py      # Test suite
├── pyproject.toml          # Dependencies and config
└── README.md               # This file
```

## Development

```bash
# Run tests
pytest tests/

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/
```

## Dependencies

**Core:**
- `mcp>=0.1.0` - Model Context Protocol SDK
- `httpx>=0.24.0` - Async HTTP client
- `python-dotenv>=1.0.0` - Environment configuration

**Dev:**
- `pytest>=7.4.0` - Testing
- `pytest-asyncio>=0.21.0` - Async test support
- `black>=23.0.0` - Code formatting
- `ruff>=0.0.275` - Linting
- `mypy>=1.0.0` - Type checking

## API Documentation

- [Vestaboard Cloud API](https://docs.vestaboard.com/docs/read-write-api/endpoints)
- [Vestaboard Local API](https://docs.vestaboard.com/docs/local-api/endpoints)

## Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Example Servers](https://github.com/modelcontextprotocol/servers)