npm package: @kompressr/mcp-server
Description: Kompressr CDN MCP server for AI agents — upload, optimize, and serve assets
Author: Kompressr
Latest version: 0.9.2-beta

# @kompressr/mcp-server

[![npm version](https://img.shields.io/npm/v/@kompressr/mcp-server.svg)](https://www.npmjs.com/package/@kompressr/mcp-server)

MCP (Model Context Protocol) server that enables AI agents to upload, optimize, and serve assets through the Kompressr CDN.

## Quick Start

Run it directly with npx — no install needed:

```bash
npx -y @kompressr/mcp-server
```

Full docs at https://kompressr.com/agents

### Configure your AI client

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`, Cursor, etc):

```json
{
  "mcpServers": {
    "kompressr": {
      "command": "npx",
      "args": ["-y", "@kompressr/mcp-server"]
    }
  }
}
```

If you already have a Kompressr account, set credentials via environment variables:

```json
{
  "mcpServers": {
    "kompressr": {
      "command": "npx",
      "args": ["-y", "@kompressr/mcp-server"],
      "env": {
        "KOMPRESSR_API_KEY": "your-api-key",
        "KOMPRESSR_PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

Or create `~/.kompressr/config.json`:

```json
{
  "api_key": "your-api-key",
  "project_id": "your-project-id",
  "api_url": "https://kompressr.com"
}
```

## Tools

### `register`

Create a new Kompressr account. After registering, a verification email is sent.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Email address for the account |
| `password` | string | Yes | Password (minimum 8 characters) |

**Example prompt:** "Register me for Kompressr with email user@example.com"

### `verify_email`

Verify your email using the token from the verification email. On success, this activates your account and saves API credentials to `~/.kompressr/config.json` automatically.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | string | Yes | Verification token from the email link (`?token=...` parameter) |

**Example prompt:** "Verify my Kompressr email with token abc123def456"

### `upload_asset`

Upload a file to the Kompressr CDN. Supports images (PNG, JPG, WebP, AVIF, SVG), PDFs, fonts (WOFF2, WOFF, TTF), CSS, JavaScript, and video files. The file is served immediately via CDN and optimization happens in the background.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | One of these | Absolute path to a local file |
| `file_url` | string | is required | URL of a remote file to upload |

**Returns:** CDN URL, asset ID, status, and original file size.

**Example prompts:**
- "Upload /path/to/logo.png to Kompressr"
- "Upload https://example.com/hero.jpg to the CDN"

### `get_asset_status`

Check the optimization status of a previously uploaded asset. Returns processing status, original and compressed sizes, and savings percentage.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `asset_id` | string | Yes | Asset ID from the upload response |

**Example prompt:** "Check the status of asset 42 on Kompressr"

### `list_assets`

List your uploaded assets with their CDN URLs and optimization status.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Max results (1-100, default 20) |

**Example prompt:** "List my recent uploads on Kompressr"

## Authentication Flow

For agents starting from scratch (no existing account):

1. Agent calls `register` with email + password
2. User checks email, finds verification token
3. Agent calls `verify_email` with the token
4. Credentials are saved automatically to `~/.kompressr/config.json`
5. Agent can now use `upload_asset`, `get_asset_status`, and `list_assets`

For existing users: set `KOMPRESSR_API_KEY` and `KOMPRESSR_PROJECT_ID` environment variables, or create the config file manually. The API key is shown on your dashboard after login.

## Configuration Priority

1. **Environment variables** (`KOMPRESSR_API_KEY`, `KOMPRESSR_PROJECT_ID`, `KOMPRESSR_API_URL`) — highest priority
2. **Config file** (`~/.kompressr/config.json`) — fallback

## Development

```bash
npm install
npm run build    # Compile TypeScript
npm run dev      # Run with tsx (hot reload)
npm test         # Run tests
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `KOMPRESSR_API_KEY` | — | API key (overrides config file) |
| `KOMPRESSR_PROJECT_ID` | — | Project ID (overrides config file) |
| `KOMPRESSR_API_URL` | `https://kompressr.com` | API base URL |