/pixel-setup

description: Configure pixel-mcp server and verify Aseprite installation
argument-hint: [aseprite-path]
allowed-tools: Read, Write, Bash

/pixel-setup - Plugin Configuration

Configure the pixel-mcp server and verify Aseprite installation.

Usage

/pixel-setup [aseprite-path]

Arguments

**aseprite-path** (optional): Path to Aseprite executable

• If not provided, attempts auto-detection
• If detection fails, prompts user for path

What This Command Does

1. **Detects Aseprite installation**

• Searches common installation paths for current platform
• macOS: `/Applications/Aseprite.app/Contents/MacOS/aseprite`
• Linux: `/usr/bin/aseprite`, `/usr/local/bin/aseprite`
• Windows: `C:\Program Files\Aseprite\Aseprite.exe`

2. **Creates configuration file**

• Generates `~/.config/pixel-mcp/config.json` (macOS/Linux)
• Generates `%APPDATA%\pixel-mcp\config.json` (Windows)
• Sets `aseprite_path` in configuration

3. **Validates configuration**

• Tests that Aseprite executable exists and is executable
• Verifies pixel-mcp can communicate with Aseprite
• Reports version information

4. **Tests MCP server**

• Runs health check on pixel-mcp server
• Confirms tools are accessible
• Reports success or errors

Examples

/pixel-setup
→ Auto-detects Aseprite installation and configures

/pixel-setup /Applications/Aseprite.app/Contents/MacOS/aseprite
→ Uses specified path for macOS

/pixel-setup "C:\Program Files\Aseprite\Aseprite.exe"
→ Uses specified path for Windows

/pixel-setup /usr/local/bin/aseprite
→ Uses specified path for Linux

Auto-Detection Paths

**macOS:**

• `/Applications/Aseprite.app/Contents/MacOS/aseprite`
• `$HOME/Applications/Aseprite.app/Contents/MacOS/aseprite`
• `/usr/local/bin/aseprite`
• `$HOME/.local/bin/aseprite`

**Linux:**

• `/usr/bin/aseprite`
• `/usr/local/bin/aseprite`
• `$HOME/.local/bin/aseprite`
• `$HOME/bin/aseprite`
• `/opt/aseprite/bin/aseprite`
• `/snap/bin/aseprite`

**Windows:**

• `C:\Program Files\Aseprite\Aseprite.exe`
• `C:\Program Files (x86)\Aseprite\Aseprite.exe`
• `%LOCALAPPDATA%\Aseprite\Aseprite.exe`
• `%USERPROFILE%\AppData\Local\Aseprite\Aseprite.exe`

Configuration File Format

**Location:**

• macOS/Linux: `~/.config/pixel-mcp/config.json`
• Windows: `%APPDATA%\pixel-mcp\config.json`

**Contents:**

{
  "aseprite_path": "/path/to/aseprite",
  "temp_dir": "/tmp/pixel-mcp",
  "timeout": 30,
  "log_level": "info",
  "log_file": "",
  "enable_timing": false
}

**Required Field:**

• `aseprite_path`: Path to Aseprite executable (only required field)

**Optional Fields:**

• `temp_dir`: Temporary directory for MCP operations (default: system temp)
• `timeout`: Command timeout in seconds (default: 30)
• `log_level`: Logging level: "debug", "info", "warn", "error" (default: "info")
• `log_file`: Path to log file (default: "" = no file logging)
• `enable_timing`: Log operation timings for performance analysis (default: false)

Implementation

**Step 1: Auto-Detection** 1. Check if aseprite-path argument provided 2. If not, run detection script: `config/detect-aseprite.sh` 3. Detection script checks common paths for current OS 4. If found, use detected path; if not, prompt user for path

**Step 2: Validate Path** 1. Check if file exists at specified path 2. Check if file is executable 3. Optionally run `aseprite --version` to verify

**Step 3: Create Configuration** 1. Determine config directory based on OS 2. Create directory if it doesn't exist: `mkdir -p ~/.config/pixel-mcp` 3. Write config.json with aseprite_path and defaults 4. Set appropriate permissions (readable/writable by user)

**Step 4: Test MCP Server** 1. Run health check: `${CLAUDE_PLUGIN_ROOT}/bin/pixel-mcp --health` 2. Capture output and check for success 3. Report Aseprite version and MCP status

**Step 5: Report Results** 1. Display configuration summary 2. Show config file location 3. Show Aseprite path 4. Confirm MCP server is ready 5. Provide next steps or troubleshooting if failed

Success Output

✓ Aseprite detected at: /Applications/Aseprite.app/Contents/MacOS/aseprite
✓ Configuration created: ~/.config/pixel-mcp/config.json
✓ Aseprite version: v1.3.2
✓ MCP server ready

Plugin setup complete! You can now create pixel art with commands like:
  /pixel-new
  /pixel-palette set nes

Error Handling

**Aseprite not found:**

✗ Aseprite not found in common installation paths

Please install Aseprite from: https://www.aseprite.org/
Or specify the path manually: /pixel-setup /path/to/aseprite

**Invalid path provided:**

✗ Aseprite not found at: /invalid/path

Please check the path and try again, or run /pixel-setup without arguments for auto-detection.

**Permission errors:**

✗ Cannot create configuration directory: ~/.config/pixel-mcp
  Permission denied

Please check directory permissions or run with appropriate privileges.

**MCP server health check failed:**

✗ MCP server health check failed
  Error: [error details]

Please check that:
  1. Aseprite path is correct
  2. Aseprite is executable
  3. pixel-mcp binary has execute permissions

Troubleshooting Tips

Include in output if errors occur:

1. **Verify Aseprite is installed**: https://www.aseprite.org/ 2. **Check pixel-mcp binary permissions**: `chmod +x ${CLAUDE_PLUGIN_ROOT}/bin/pixel-mcp` 3. **Manually edit config**: Edit `~/.config/pixel-mcp/config.json` 4. **Test Aseprite directly**: Run `aseprite --version` in terminal 5. **Check logs**: Set `log_file` in config for debugging

Platform-Specific Notes

**macOS:**

• Aseprite.app is a bundle; executable is inside Contents/MacOS/
• May need to grant Terminal/Claude Code permissions in System Preferences
• If downloaded from website, may need to allow in Security & Privacy

**Linux:**

• Installed via package manager: usually in /usr/bin/
• Compiled from source: often in /usr/local/bin/
• AppImage: specify full path to .AppImage file

-