# Agnes MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that wraps the [Agnes AI](https://agnes-ai.com) image and video generation APIs, enabling AI assistants (Claude, Cursor, VS Code, etc.) to generate images and videos via standardized tool calls.

## Features

- **Image Generation** — Text-to-image and image-to-image via `generate_image`
- **Video Generation** — Text-to-video and image-to-video via `generate_video` + `get_video`
- **Two Transport Modes** — `stdio` (local) and `Streamable HTTP` (remote)
- **Auto Download** — Optionally save generated media to disk automatically
- **Blocking & Async** — `wait=true` for synchronous generation, or poll with `get_video`

## Quick Start

### 1. Install Dependencies

```bash
cd agnes-mcp-server
npm install
npm run build
```

### 2. Set API Key

```bash
export AGNES_API_KEY="sk-agnes-your-api-key-here"
```

### 3. Run the Server

**Stdio mode** (default, for local MCP clients like Claude Desktop, Cursor):

```bash
npm run start
# or
node agnes-mcp-server.cjs
```

**Streamable HTTP mode** (for remote MCP clients):

```bash
MCP_TRANSPORT=http npm run start:http
# Default port: 3100 (configurable via HTTP_PORT)
```

### 4. Configure Your MCP Client

Add this to your MCP client configuration (e.g., `.mcp.json`):

```json
{
  "mcpServers": {
    "agnes": {
      "command": "node",
      "args": ["agnes-mcp-server.cjs"],
      "env": {
        "AGNES_API_KEY": "sk-agnes-your-api-key-here"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `generate_image` | Generate or edit an image. Supports text-to-image and image-to-image modes. |
| `generate_video` | Submit a video generation task. Set `wait=true` to block until complete. |
| `get_video` | Query video generation status and optionally download the result. |

### Tool Parameters

**`generate_image`**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | — | Text description of the desired image |
| `size` | string | No | `1024x1024` | Image dimensions (e.g., `512x512`, `1024x1024`) |
| `images` | string[] | No | — | Input images (local file paths or base64 data URIs) |
| `format` | `"url"` \| `"b64"` | No | `url` | Output format when no `outputDir` is set |
| `outputDir` | string | No | — | Directory to download the image file |

**`generate_video`**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | — | Text description of the desired video |
| `image` | string \| string[] | No | — | Input image(s) for image-to-video mode |
| `mode` | string | No | — | Generation mode (e.g., `"image-to-video"`) |
| `width` | number | No | — | Video width |
| `height` | number | No | — | Video height |
| `num_frames` | number | No | — | Number of frames |
| `frame_rate` | number | No | — | Frames per second |
| `seed` | number | No | — | Random seed for reproducibility |
| `negative_prompt` | string | No | — | Things to exclude from the video |
| `outputDir` | string | No | — | Directory to download the video file |
| `wait` | boolean | No | `false` | Block until generation completes |

**`get_video`**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `videoId` | string | Yes | — | Video ID returned by `generate_video` |
| `taskId` | string | No | — | Task ID (fallback for querying) |
| `outputDir` | string | No | — | Directory to download the video file |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AGNES_API_KEY` | Yes | — | Your Agnes API key (starts with `sk-`) |
| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
| `HTTP_PORT` | No | `3100` | HTTP server port (only in `http` mode) |
| `DEFAULT_DOWNLOAD_DIR` | No | — | Root directory for auto-downloaded media |

## Project Structure

```
agnes-mcp-server/
├── src/
│   ├── app/               # Server entry points (stdio, http, bundle)
│   ├── client/            # HTTP client wrapper
│   ├── core/              # Core MCP setup and registry
│   ├── module/
│   │   ├── image/         # Image generation service
│   │   └── video/         # Video generation service
│   ├── providers/         # API providers (AgnesClient, image, video)
│   ├── tools/             # MCP tool implementations
│   └── types/             # Shared types and result formatters
├── agnes-mcp-server.cjs   # Bundled entry point
├── agnes-bundle.cjs       # Standalone bundle
├── SKILL.md               # MCP skill definition
├── TOKEN_AUTH.md          # Authentication documentation
└── package.json
```

## Development

```bash
# Watch mode (TypeScript → Node)
npm run dev

# Build TypeScript
npm run build

# Create standalone bundle
npm run bundle

# Run smoke test
npm run test
```

## Test Script

A standalone test script is included for verifying the image-to-video API flow:

```bash
npx tsx test-video-image.ts <local-image-path> <api-key>
# or
IMAGE_PATH=test.jpg AGNES_API_KEY=sk-xxx npx tsx test-video-image.ts
```

## License

MIT