gh-willibrandon-pixel-plugin/commands/pixel-setup.md at master

zhongwei/gh-willibrandon-pixel-plugin

Fork 0

Files

Zhongwei Li 4de211b5a8 Initial commit

2025-11-30 09:06:21 +08:00

7.2 KiB

Raw Permalink Blame History

description, argument-hint, allowed-tools

description

argument-hint

allowed-tools

Configure pixel-mcp server and verify Aseprite installation

aseprite-path

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

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
Creates configuration file
- Generates ~/.config/pixel-mcp/config.json (macOS/Linux)
- Generates %APPDATA%\pixel-mcp\config.json (Windows)
- Sets aseprite_path in configuration
Validates configuration
- Tests that Aseprite executable exists and is executable
- Verifies pixel-mcp can communicate with Aseprite
- Reports version information
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

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

Step 2: Validate Path

Check if file exists at specified path
Check if file is executable
Optionally run aseprite --version to verify

Step 3: Create Configuration

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

Step 4: Test MCP Server

Run health check: ${CLAUDE_PLUGIN_ROOT}/bin/pixel-mcp --health
Capture output and check for success
Report Aseprite version and MCP status

Step 5: Report Results

Display configuration summary
Show config file location
Show Aseprite path
Confirm MCP server is ready
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:

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

Platform-Specific Notes