# @auraimage/mcp-server

[![Images powered by AuraImage](https://img.shields.io/badge/Images%20powered%20by-AuraImage-0b0b0b?style=flat-square)](https://auraimage.ai)

Model Context Protocol server that gives any MCP-compatible AI agent (Claude Code, Cursor, Cline, Continue, etc.) direct access to the AuraImage toolkit — auditing, migrating, and generating responsive image markup without leaving the editor.

## Tools exposed

| Tool | Description |
|------|-------------|
| `audit_lcp` | Scans a project directory for unoptimized images and estimates LCP savings. |
| `migrate_assets` | Uploads local images to AuraImage and returns the new CDN URLs. Supports `dryRun: true`. |
| `generate_alt` | Generates accessible alt text for an image URL using vision AI. |
| `generate_responsive_tag` | Returns a `<picture>` element with AVIF + WebP srcsets for the given image. |
| `smart_crop_preview` | Returns crop variant URLs for an image at the requested width/height. |
| `push_og_template` | Pushes an OG template (social preview card) to a project and returns its Render URL. |

### `push_og_template`

Pushes one OG template to a project and returns its Render URL. A template is HTML with Tailwind in a `tw` attribute and `{{name}}` holes; the canvas, fonts, defaults, and quality are arguments, so the file stays a design.

| Argument | Type | Default | Notes |
| --- | --- | --- | --- |
| `projectName` | `string` | required | Your AuraImage project name. |
| `name` | `string` | required | Template name, `[a-z0-9-]{1,64}`. |
| `html` | `string` | — | Template markup. Provide this or `file`. |
| `file` | `string` | — | Absolute path to the template file. Provide this or `html`. |
| `width` | `number` | `1200` | Canvas width, 100–4096. |
| `height` | `number` | `630` | Canvas height, 100–4096. |
| `fonts` | `string[]` | `[]` | Google Font families by name, at most 4. |
| `defaults` | `object` | `{}` | Default value per variable. |
| `quality` | `number` | `80` | 1–100, JPEG and WebP only. |

Requires `AURA_SECRET_KEY`. Push is idempotent, and a rejected template comes back with the exact reason: the class token that has no `<style>` rule, the variable in a style position, the font family Google Fonts does not have. See the [OG images guide](https://auraimage.ai/docs/og-images).

## Configuration

Add the server to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "auraimage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@auraimage/mcp-server@latest"],
      "env": {
        "AURA_SECRET_KEY": "${AURA_SECRET_KEY}"
      }
    }
  }
}
```

### Environment variables

| Variable | Needed by | Notes |
|----------|-----------|-------|
| `AURA_SECRET_KEY` | `migrate_assets`, `push_og_template` | Your project's Secret Key — signs upload tokens. Keep it server-side. |

`audit_lcp`, `generate_alt`, `generate_responsive_tag`, and `smart_crop_preview` need no credentials. `generate_alt` is generated server-side by the AuraImage API (GPT-5.6 Luna) for images already on the AuraImage CDN, rate-limited per IP. The server always starts without any environment variables; a tool that is missing its key returns a clear error when called.

## Run standalone

```bash
npx @auraimage/mcp-server@latest
```

The server speaks stdio and is compatible with every MCP-aware client.

## Documentation

Full docs and tool examples: [auraimage.ai/docs/ai-integration](https://auraimage.ai/docs/ai-integration).

## License

MIT © AuraImage

---

Images powered by [AuraImage](https://auraimage.ai) — the image CDN that
installs itself. Set it up in any project with `npx aura init`, or from your
AI agent with [Agent Skills](https://github.com/auraimage/skills) and the
[MCP server](https://github.com/auraimage/mcp-server).