# Screenshot MCP Gateway

A unified MCP (Model Context Protocol) server that combines screenshot capture capabilities with HTTP/SSE gateway functionality for remote access. This project integrates [HTTP-ScreenShotMCP](https://github.com/davinoishi/HTTP-ScreenShotMCP) with [Supergateway](https://github.com/supercorp-ai/supergateway) to provide a single deployable solution for remote screenshot services.

## Features

- ✅ Full-page screenshot capture with Puppeteer
- ✅ Element-specific screenshots using CSS selectors
- ✅ Device viewport presets (mobile, tablet, desktop)
- ✅ Custom viewport configurations
- ✅ Advanced wait conditions (selector, function, timeout, networkidle)
- ✅ HTTP/SSE transport for remote access
- ✅ CORS support for cross-origin requests
- ✅ Headless browser operation (perfect for server deployments)
- ✅ Automatic Chrome installation for headless environments

## Quick Start

### Installation

```bash
npm install
```

This will automatically:
1. Install all dependencies
2. Download and configure Chromium for headless operation
3. Build the TypeScript source

### Running the Server

```bash
npm start
```

The server will start on port 3000 (or the port specified in `PORT` environment variable).

**Endpoints:**
- SSE MCP endpoint: `http://localhost:3000/sse`
- Health check: `http://localhost:3000/health`

### Configuration

Copy `.env.example` to `.env` and customize:

```bash
cp .env.example .env
```

**Environment Variables:**
- `PORT`: Server port (default: 3000)
- `BROWSER_HEADLESS`: Run browser in headless mode (default: true)
- `BROWSER_TIMEOUT`: Browser timeout in milliseconds (default: 30000)
- `MAX_CONCURRENT_SCREENSHOTS`: Maximum concurrent screenshots (default: 5)

## Available MCP Tools

### 1. `capture_screenshot`

Capture a full-page screenshot of a webpage with advanced options.

**Parameters:**
- `url` (required): The URL of the webpage to screenshot
- `viewport` (optional): Viewport configuration
  - `preset`: Device preset (mobile, tablet, desktop)
  - `width`: Viewport width in pixels
  - `height`: Viewport height in pixels
  - `deviceScaleFactor`: Device scale factor
  - `isMobile`: Whether to emulate mobile device
  - `hasTouch`: Whether device has touch support
- `waitFor` (optional): Wait condition before taking screenshot
  - `type`: Type of wait condition (selector, function, timeout, networkidle)
  - `value`: Value for wait condition
  - `timeout`: Timeout in milliseconds
  - `idleTime`: Network idle time in milliseconds
- `standardDelay` (optional): Apply standard 2.5s delay after networkidle2 (default: true)
- `delay` (optional): Additional delay in milliseconds
- `waitUntil` (optional): When to consider navigation complete (default: networkidle2)

### 2. `capture_element`

Capture a screenshot of a specific element on a webpage.

**Parameters:**
- `url` (required): The URL of the webpage
- `selector` (required): CSS selector for the element to capture
- `viewport` (optional): Viewport configuration
- `standardDelay` (optional): Apply standard 2.5s delay (default: true)

### 3. `list_device_presets`

List available device presets with their configurations.

**No parameters required.**

## Usage with MCP Clients

### Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://localhost:3000/sse"
      ]
    }
  }
}
```

### Remote Access

To expose your screenshot server publicly, use [ngrok](https://ngrok.com/):

```bash
# Terminal 1: Start the screenshot server
npm start

# Terminal 2: Expose via ngrok
ngrok http 3000
```

Then use the ngrok URL in your MCP client configuration:

```json
{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://your-ngrok-url.ngrok-free.app/sse"
      ]
    }
  }
}
```

## Deployment

### Standard Deployment

1. Clone this repository
2. Install dependencies: `npm install`
3. Build the project: `npm run build`
4. Set environment variables (create `.env` from `.env.example`)
5. Start the server: `npm start`

### Docker Deployment

Create a `Dockerfile`:

```dockerfile
FROM node:18

# Install dependencies for Puppeteer headless Chrome
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libgdk-pixbuf2.0-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Build TypeScript
RUN npm run build

# Set environment variables for headless Chrome
ENV PUPPETEER_SKIP_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
ENV BROWSER_HEADLESS=true

EXPOSE 3000

CMD ["npm", "start"]
```

Build and run:

```bash
docker build -t screenshot-mcp-gateway .
docker run -p 3000:3000 screenshot-mcp-gateway
```

### Headless Server Requirements

For headless server deployments (Ubuntu/Debian):

```bash
# Install Chrome dependencies
sudo apt-get update
sudo apt-get install -y \
    chromium-browser \
    chromium-codecs-ffmpeg \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libgdk-pixbuf2.0-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils
```

## Development

### Build

```bash
npm run build
```

### Development Mode (with auto-reload)

```bash
npm run dev
```

### Clean Build Artifacts

```bash
npm run clean
```

## Architecture

This project combines:
- **Screenshot MCP Server**: Provides screenshot capture functionality using Puppeteer
- **Supergateway Pattern**: HTTP/SSE transport layer for remote MCP access
- **Express.js**: Web server framework
- **MCP SDK**: Official Model Context Protocol SDK
- **Puppeteer**: Headless Chrome automation

## Security Considerations

- The server is exposed on the network when running in HTTP mode
- Consider implementing authentication for production deployments
- Use environment variables for sensitive configuration
- Implement rate limiting for production use
- Be cautious with URL inputs to prevent SSRF attacks

## Troubleshooting

### Chrome Installation Issues

If Chrome fails to install automatically:

```bash
npx puppeteer browsers install chrome
```

### Headless Mode Issues

If screenshots fail in headless mode, try:

1. Set `BROWSER_HEADLESS=false` for debugging
2. Check Chrome dependencies are installed
3. Verify Chrome executable path

### Connection Issues

- Ensure the port is not already in use
- Check firewall settings for the specified port
- Verify CORS settings if accessing from web clients

## License

MIT

## Credits

This project integrates:
- [HTTP-ScreenShotMCP](https://github.com/davinoishi/HTTP-ScreenShotMCP)
- [Supergateway](https://github.com/supercorp-ai/supergateway)