avalonia-headless-mcp by minorum - MCP Server

Autonia MCP - UI Automation Server

An AI-powered development assistant for Avalonia applications. This MCP (Model Context Protocol) server enables AI agents to discover, connect to, and interact with running Avalonia applications during development workflows.

Purpose

This server transforms AI agents into Avalonia development assistants that can:

🔍 Discover running Avalonia applications on your system
🔗 Connect to your applications during development
📸 Capture screenshots for visual testing and documentation
🖱️ Interact with UI elements for automated testing
🔍 Analyze your application's UI in real-time

Perfect for prototyping, testing, and validating Avalonia applications with AI assistance.

Architecture

Unlike traditional UI automation tools, this server connects to external running applications rather than creating isolated UIs. This enables AI agents to work directly with your actual development projects.

┌─────────────────┐    MCP Protocol    ┌──────────────────────┐
│   AI Agent      │ ◄─────────────────► │   MCP Server         │
│ (Claude Code)   │                    │ (This Project)       │
└─────────────────┘                    └──────────────────────┘
                                                    │
                                                    │ Process Discovery
                                                    │ & Connection
                                                    ▼
                                        ┌──────────────────────┐
                                        │ Your Avalonia Apps   │
                                        │ (Running Processes)  │
                                        └──────────────────────┘

Getting Started

Prerequisites

.NET 9.0 or higher
Claude Code (for AI interaction)

Quick Setup with Claude Code

Add Autonia to your Avalonia app (one line):

public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .WithInterFont()
        .UseAutonia();  // ← Add this line

Add to Claude Code (one command):

# Generic command for any Avalonia project:
claude mcp add my-avalonia-app dotnet "run --project YourApp.csproj" --cwd "/path/to/your/project"

# Or use the provided script:
./add-to-claude.sh YourApp.csproj my-app-name

Start using in Claude Code:
- "Take a screenshot of my Avalonia app"
- "Click the Submit button and show me the result"
- "Type 'test@example.com' in the email field"

Alternative: Manual Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "my-avalonia-app": {
      "command": "dotnet",
      "args": ["run", "--project", "YourApp.csproj"],
      "cwd": "/path/to/your/project"
    }
  }
}

Available MCP Tools

🔍 Application Discovery

DiscoverAvaloniaApplications - Find all running Avalonia applications
ConnectToApplication - Connect to a specific application by process ID
ListConnectedApplications - Show active connections
DisconnectFromApplication - Clean up connections

📸 Visual Testing

CaptureWindowScreenshot - Take screenshots of connected applications
SaveImageToFile - Save screenshots to disk
CompareImages - Visual regression testing with pixel-perfect comparison

🖱️ UI Interaction

ClickElement - Click UI elements by name or coordinates
TypeText - Type text into input fields
GetElementProperty / SetElementProperty - Read/write element properties
WaitForElement - Wait for elements to appear or meet conditions

Example Workflow

// 1. Discover running Avalonia applications
{
  "tool": "DiscoverAvaloniaApplications"
}

// 2. Connect to your application
{
  "tool": "ConnectToApplication",
  "parameters": {
    "processId": 1234
  }
}

// 3. Take a screenshot
{
  "tool": "CaptureWindowScreenshot", 
  "parameters": {
    "connectionId": "abc123",
    "format": "png"
  }
}

// 4. Interact with UI elements
{
  "tool": "ClickElement",
  "parameters": {
    "connectionId": "abc123",
    "elementName": "SubmitButton"
  }
}

Development Benefits

For AI-Assisted Development

Real-time feedback on your actual applications
Automated testing during development iterations
Visual documentation generation
UI accessibility analysis and suggestions

For Team Workflows

Consistent testing across development environments
Automated screenshots for design reviews
Regression testing during rapid prototyping
Integration with CI/CD pipelines

Technical Details

Framework: .NET 9.0 with C# 13
Protocol: Model Context Protocol (latest specification)
Transport: STDIO for MCP communication
Dependencies: Minimal - no external APIs or configuration required
Process Safety: Proper connection management and cleanup

No Configuration Required

This server requires no setup:

❌ No API keys or environment variables
❌ No external service dependencies
❌ No complex configuration files
✅ Just build and run with dotnet run

Contributing

This project focuses on AI development assistance for Avalonia applications. Contributions should enhance the ability for AI agents to discover, connect to, and interact with running Avalonia applications.

minorum/avalonia-headless-mcp