# @velxor/mcp

[![License: MIT](https://img.shields.io/badge/license-MIT-violet.svg)](./LICENSE)

An MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that
lets Claude Code, Cursor, and other MCP-capable agents drive all three
[Vlexor](https://vlexor.app) pillars — AI video editing, game-asset
generation, and motion-graphics production — directly from a coding session.

Video editing runs on your own footage: your raw video **never leaves your
machine** — only the text of your instructions (and an optional transcript)
is sent to Vlexor to generate the edit plan, which is compiled to a real
FFmpeg command and rendered entirely locally. Asset generation and motion
graphics render server-side (there's no local footage to protect) and return
a signed download URL — optionally saved straight to a local path.

## Setup

1. Generate a personal API key at **Vlexor → Settings → MCP & API**.
2. Install FFmpeg if you don't already have it (`brew install ffmpeg` on
   macOS, or point `VLEXOR_FFMPEG_DIR` at a folder that has `ffmpeg`/`ffprobe`).
3. Add this to your MCP client's config:

```json
{
  "mcpServers": {
    "vlexor": {
      "command": "npx",
      "args": ["-y", "@velxor/mcp"],
      "env": { "VLEXOR_API_KEY": "vlx_…" }
    }
  }
}
```

## Tools

**Pillar 1 — video editing** (renders locally; footage never uploaded):
- **`probe_media`** — read a local video's duration, resolution, fps, codec.
- **`generate_edit_plan`** — natural-language instruction → structured edit
  plan (calls the real Vlexor Command Engine; counts against your plan's
  usage).
- **`compile_edit_plan`** — edit plan → a real FFmpeg command, computed
  entirely locally.
- **`render`** — run the compiled command locally to produce the final video.

A typical agent flow: `probe_media` → `generate_edit_plan` → (review the
steps) → `compile_edit_plan` → (review the FFmpeg command) → `render`.

**Pillar 2 — asset generation** (renders server-side):
- **`generate_game_asset`** — prompt → a texture, 2D character, sprite sheet,
  3D model (`.glb`), sound effect, music track, parallax background, or
  character turnaround. Returns a signed download URL; pass `savePath` to
  also write the file locally.

**Pillar 3 — motion graphics** (renders server-side):
- **`generate_motion_graphic`** — a short creative brief → a rendered
  kinetic-title `.mp4` (announcement/promo card). Returns a signed download
  URL; pass `savePath` to also write the file locally.

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `VLEXOR_API_KEY` | yes | — | Personal API key from Settings → MCP & API |
| `VLEXOR_API_BASE` | no | `https://vlexor.app` | Override for self-hosted/dev instances |
| `VLEXOR_FFMPEG_DIR` | no | (system `PATH`) | Folder containing `ffmpeg`/`ffprobe`, if not on `PATH` |

## About this repository

This package is the thin integration layer that connects an MCP client to
Vlexor's real, hosted API — every tool call here is a plain, inspectable
HTTP request (you can read exactly what leaves your machine in
[`src/api-client.ts`](./src/api-client.ts)). It's open so agent developers
piping their API key through it can verify that for themselves.

The Vlexor platform itself — the editing engine, the AI prompt design, the
asset/motion-graphics generation pipelines — is closed-source. A couple of
this package's imports (`@velxor/engine`'s FFmpeg-plan compiler,
`@velxor/shared`'s type definitions) come from that private codebase and
aren't published separately, so this repo won't `pnpm install`/build
standalone — it's meant to be read, and run via the pre-built npm package
(`npx -y @velxor/mcp`), not compiled from this checkout.

Issues and PRs on the MCP integration layer itself (tool schemas, error
handling, the local FFmpeg orchestration) are welcome.

## License

[MIT](./LICENSE)