pixel-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

An MCP (Model Context Protocol) server implementation in Go that exposes Aseprite's pixel art and animation capabilities through programmatic access. The server integrates with Aseprite's command-line interface and Lua scripting API to enable AI assistants to create and manipulate sprites.

Build Commands

# Build the server binary
make build
# or: go build -o bin/pixel-mcp ./cmd/pixel-mcp

# Run tests
make test
# or: go test -v -race -cover ./...

# Run integration tests (requires real Aseprite)
go test -tags=integration ./...

# Generate test coverage report
make test-coverage

# Run linters
make lint

# Clean build artifacts
make clean

# Install binary
make install

Configuration Requirements

CRITICAL: This project requires explicit configuration - no automatic discovery or environment variables.

All operations require a configuration file at ~/.config/pixel-mcp/config.json:

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

Configuration fields:

• aseprite_path (required): Absolute path to Aseprite executable
• temp_dir (optional): Temporary directory, defaults to /tmp/pixel-mcp
• timeout (optional): Command timeout in seconds, defaults to 30
• log_level (optional): Verbosity level (debug, info, warn, error), defaults to info
• log_file (optional): Path to persistent log file, empty means stderr only
• enable_timing (optional): Enable request tracking/timing, defaults to false

The aseprite_path MUST be an absolute path to a real Aseprite executable. The project does NOT:

• Auto-discover Aseprite installations
• Use environment variables for Aseprite path
• Search system PATH for Aseprite

Testing Philosophy

ALL tests use real Aseprite - no mocks, stubs, or fakes for Aseprite integration.