Metadata-Version: 2.4
Name: clipici-mcp
Version: 0.1.1
Summary: MCP server for Clipici — turn long videos into captioned viral clips from any MCP client.
Author: Clipici
License: MIT
Keywords: captions,clipici,clips,mcp,reels,shorts,tiktok,video
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# clipici-mcp

<!-- mcp-name: io.github.magia187/clipici-mcp -->

An [MCP](https://modelcontextprotocol.io) server for **[Clipici](https://clipici.ro)** —
turn long videos into captioned, viral-ready short clips (with correct Romanian
diacritics) from any MCP client: Claude Code, Claude Desktop, Cursor, and more.

## What it does

The server wraps the Clipici REST API as MCP tools:

| Tool | What it does |
| --- | --- |
| `clipici_whoami` / `clipici_usage` | Account info and minutes/quota |
| `clipici_create_clips` | Upload a video (local file or URL) → AI clip pipeline |
| `clipici_wait_for_job` | Poll a job to completion, with live progress |
| `clipici_list_jobs` / `clipici_get_job` | Browse jobs |
| `clipici_list_clips` / `clipici_get_clip` | Browse generated clips |
| `clipici_download_clip` | Save a finished clip to disk, or get a download URL |
| `clipici_get_captions` | Export a clip's captions as SRT/VTT |
| `clipici_caption_video` | Caption-only: burn captions onto a video you already cut |
| `clipici_regenerate_clip` | Re-render with a new aspect ratio / caption style / template |
| `clipici_edit_subtitles` / `clipici_restore_diacritics` | Fix caption text & diacritics |
| `clipici_trim_clip` / `clipici_split_clip` / `clipici_merge_clips` | Cut, split, montage |
| `clipici_export_aspect_ratios` | Clone a clip into 9:16 / 1:1 / 16:9 |

It also exposes read-only **resources** (`clipici://jobs`, `clipici://jobs/{id}`,
`clipici://clips/{id}`) and a guided **prompt** `make_viral_clips`.

## Get an API key

In the Clipici dashboard → **Setări → Chei API**, generate a key (`clpc_live_…`).
It's shown once — copy it.

## Use it (local / stdio)

Add to your MCP client config (Claude Code: `~/.claude.json` or project
`.mcp.json`; Claude Desktop: `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "clipici": {
      "command": "uvx",
      "args": ["clipici-mcp"],
      "env": { "CLIPICI_API_KEY": "clpc_live_your_key_here" }
    }
  }
}
```

`CLIPICI_API_URL` defaults to `https://api.clipici.ro`. For local development
against your own backend, add `"CLIPICI_API_URL": "http://localhost:8000"`.

Then ask your agent: *"Use Clipici to turn ./talk.mp4 into viral clips, wait for
it, and download the top clip to ./clips/."*

## Hosted / remote (Streamable-HTTP)

The same server can run as a remote MCP at `https://mcp.clipici.ro` — point a
remote-MCP-capable client at it and authenticate with `Authorization: Bearer
clpc_live_…`. Note: local-file tools (`file_path`, `dest_path`) only work in
stdio mode; with the hosted server, pass a public `url` and use the returned
download URL.

## Environment variables

| Var | Default | Notes |
| --- | --- | --- |
| `CLIPICI_API_KEY` | — | Your `clpc_live_…` key (required for stdio) |
| `CLIPICI_API_URL` | `https://api.clipici.ro` | Backend base URL |
| `CLIPICI_TRANSPORT` | `stdio` | `stdio` or `http` |
| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `9000` | HTTP transport bind |

## Develop & test

```bash
cd mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q                      # unit tests (no backend needed)

# Interactive tool testing:
CLIPICI_API_KEY=clpc_live_… npx @modelcontextprotocol/inspector uvx clipici-mcp

# Opt-in end-to-end smoke against a local backend:
CLIPICI_E2E=1 CLIPICI_API_URL=http://localhost:8000 \
  CLIPICI_API_KEY=clpc_live_… CLIPICI_E2E_VIDEO=./sample.mp4 pytest -q tests/test_e2e_smoke.py
```
