zetaphoenix888-byte/screen2claude

Headless Screen2Claude MCP

Version: 1.0.0 Platform: Windows 10 / 11 Runtime: Node.js 18+

A headless MCP (Model Context Protocol) server that captures the active window screenshot and sends it to a configured HTTP endpoint for AI-powered UI analysis.

🎯 Features

• Headless Operation: No GUI, runs as a background process
• MCP Integration: Works with Claude Code and other MCP clients
• Flexible Prompts: Support for custom prompts and presets
• HTTP Integration: Send screenshots to your own analysis endpoint
• Non-Intrusive: Captures without stealing focus from active window

📋 Requirements

• OS: Windows 10 or Windows 11
• Node.js: Version 18.0.0 or higher
• HTTP Endpoint: A server that can receive and analyze screenshots (see HTTP Endpoint Requirements)

🚀 Quick Start

1. Installation

# Clone or download this repository
cd screen

# Install dependencies
npm install

# Build the project
npm run build

2. Configuration

Copy the example configuration file and edit it:

cp config.example.json config.json

Edit config.json with your settings:

{
  "endpoint_url": "http://localhost:12345/claude/ui-review",
  "auth_token": "",
  "default_prompt": "Please review this UI and point out 3 improvements.",
  "presets": {
    "ui_review": "Please review this UI and point out 3 improvements.",
    "element_list": "List all visible UI elements with their role and label."
  }
}

3. Register with Claude Code

Add to your .claude.json:

{
  "mcpServers": {
    "screen2claude": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/screen/dist/server.js"],
      "env": {
        "S2C_CONFIG": "C:/Users/YOUR_USERNAME/screen/config.json"
      }
    }
  }
}

4. Usage

From Claude Code, you can now use the capture_ui_screen tool:

Can you capture the current screen and analyze the UI?

Or with custom prompt:

Capture the screen with prompt: "List all accessibility issues"

Or with preset:

Capture the screen using preset: element_list

⚙️ Configuration

Configuration File Location

The server looks for configuration in this order:

1. Path specified in S2C_CONFIG environment variable
2. ./config.json in the current directory

Configuration Fields

Example Presets

{
  "presets": {
    "ui_review": "Please review this UI and point out 3 improvements.",
    "element_list": "List all visible UI elements with their role and label.",
    "accessibility": "Analyze this UI for accessibility issues and suggest improvements.",
    "color_contrast": "Check the color contrast ratios and identify any WCAG violations."
  }
}

🌐 HTTP Endpoint Requirements

Your HTTP endpoint should:

Accept POST Requests

Endpoint: As configured in endpoint_url Method: POST Content-Type: application/json

Request Body:

{
  "prompt": "Please review this UI...",
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "meta": {
    "captured_at": "2025-11-09T12:34:56.789Z",
    "source": "headless-mcp"
  }
}

Return Analysis Results

Recommended Response (JSON):

{
  "result": "This UI has the following improvements..."
}

Alternative Response (Plain Text):

This UI has the following improvements...

Both formats are supported. The server will extract the result field from JSON or use the entire response body as plain text.

🛠️ Development

Available Scripts

# Build TypeScript to JavaScript
npm run build

# Build and run the server
npm run dev

# Run the built server
npm run start

# Clean build artifacts
npm run clean

# Clean and rebuild
npm run rebuild

# Run test HTTP endpoint (for development)
npm run test:endpoint

# Run production HTTP endpoint (Claude API integration)
npm run prod:endpoint

Production Endpoint (Claude API Integration)

This project includes a production-ready HTTP endpoint that integrates with Claude API for real UI analysis.

Setup

1. Get Claude API Key: Sign up at https://console.anthropic.com/ and get your API key

2. Start the production endpoint:

# Using environment variable
ANTHROPIC_API_KEY=your-api-key-here npm run prod:endpoint

# Or using .env file
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env.production
source .env.production  # On Windows: set /p < .env.production
npm run prod:endpoint

3. Update MCP config to use the production endpoint:

{
  "endpoint_url": "http://localhost:3001/claude/vision",
  "auth_token": "",
  "default_prompt": "Please review this UI and point out 3 improvements.",
  "presets": { ... }
}

Environment Variables

Example with Authentication

# Start with authentication enabled
ANTHROPIC_API_KEY=your-api-key \
AUTH_TOKEN=your-secret-token \
npm run prod:endpoint

Then update your config:

{
  "endpoint_url": "http://localhost:3001/claude/vision",
  "auth_token": "your-secret-token"
}

Manual Testing

1. Start your HTTP endpoint (see Creating a Test Endpoint)
2. Run the MCP server manually:

   npm run dev
   

3. The server communicates via stdio (JSON-RPC 2.0)
4. Send a tool execution request to test

Creating a Test Endpoint

Create a simple Express server to test:

// test-server.js
import express from 'express';

const app = express();
app.use(express.json({ limit: '50mb' }));

app.post('/claude/ui-review', (req, res) => {
  console.log('Received prompt:', req.body.prompt);
  console.log('Image size:', req.body.image_base64?.length);

  res.json({
    result: `Analysis: This is a test response. Prompt was: ${req.body.prompt}`
  });
});

app.listen(12345, () => {
  console.log('Test endpoint running on http://localhost:12345');
});

Run with:

node test-server.js

📡 MCP Tool Reference

Tool: capture_ui_screen

Captures the active window screenshot and sends it for analysis.

Input Parameters

{
  prompt?: string;   // Custom prompt (overrides preset and default)
  preset?: string;   // Preset name from config.json
}

Priority:

1. prompt (if provided)
2. preset (if provided and exists in config)
3. default_prompt (from config)
4. Fallback: "Please analyze this UI screenshot."

Output (Success)

{
  "status": "success",
  "analysis": "This UI has...",
  "endpoint": "http://localhost:12345/claude/ui-review"
}

Output (Error)

{
  "status": "error",
  "error_code": "capture_failed | http_failed | config_missing",
  "message": "Detailed error message"
}

🐛 Troubleshooting

Error: endpoint_url is required in config.json

Solution: Make sure config.json exists and contains the endpoint_url field.

Error: Capture failed

Possible causes:

• No active window
• Screenshot library error

Solution: Check the error logs for details. Make sure you have an active window open.

Error: HTTP failed

Possible causes:

• Endpoint server is not running
• Wrong URL in config.json
• Network/firewall issues

Solution:

1. Verify your HTTP endpoint is running: curl http://localhost:12345/claude/ui-review
2. Check the endpoint URL in config.json
3. Review server logs for HTTP status codes

Server doesn't appear in Claude Code

Solution:

1. Check .claude.json syntax is valid
2. Restart Claude Code
3. Verify the path to server.js is correct (use absolute paths)

📝 Architecture

Components

┌─────────────────┐
│  MCP Client     │ (Claude Code)
│  (stdio)        │
└────────┬────────┘
         │ JSON-RPC 2.0
         ▼
┌─────────────────┐
│  MCP Server     │ (this project)
│  - server.ts    │
│  - config.ts    │
│  - capture.ts   │
│  - http-client.ts│
└────────┬────────┘
         │ HTTP POST
         ▼
┌─────────────────┐
│  HTTP Endpoint  │ (your server)
│  (AI analysis)  │
└─────────────────┘

File Structure

screen/
├── src/
│   ├── types.ts              # Type definitions
│   ├── config.ts             # Configuration loader
│   ├── capture.ts            # Screenshot capture
│   ├── http-client.ts        # HTTP POST to endpoint
│   ├── server.ts             # MCP server entry point
│   └── screenshot-desktop.d.ts  # Type declarations
├── dist/                     # Compiled JavaScript
├── config.json               # Your configuration (gitignored)
├── config.example.json       # Example configuration
├── package.json              # npm package definition
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🔒 Security Notes

• config.json is gitignored by default to prevent accidentally committing sensitive tokens
• If using auth_token, keep config.json secure
• The endpoint receives base64-encoded screenshots which can be large
• Screenshots are never saved to disk (memory only)

📄 License

MIT

🙏 Acknowledgments

• Built with Model Context Protocol SDK
• Screenshot capture via screenshot-desktop

Questions or Issues? Check the CLAUDE.md file for technical details and development notes.