# clipquery

Search a personal video library with natural language. Videos
processed by the Flashback system are split into ~30-second
segments, analysed for visual content, transcribed, and embedded;
a query is matched semantically against those segments, and each
result comes back with an AI-generated description, a relevance
score (0–1), a direct URL to view the segment, and the time that
URL expires. Presigned URLs expire after 1 hour — run the query
again for fresh ones.

## Configuration

Two environment variables are required for `query_videos`:

- `FLASHBACK_USER_ID` — your unique Flashback account identifier
  (e.g. `4087fce3-3d86-4047-b35f-4004b4c19192`)
- `FLASHBACK_API_BASE_URL` — the base URL of the Flashback video
  processing API. The upstream publishes no default, so this must
  be set; a missing value is an error naming the variable, raised
  before any request.

`get_setup_instructions` is local and needs no configuration.

## CLI

```bash
npx @reneturcios/clipquery query "person talking" --max-results 5
npx @reneturcios/clipquery query "meeting discussion about deadlines"
npx @reneturcios/clipquery setup
npx @reneturcios/clipquery --version
```

Exit codes: `0` on success, `1` on a runtime error (including
missing configuration), `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/clipquery mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "clipquery": {
      "command": "npx",
      "args": ["-y", "@reneturcios/clipquery", "mcp"],
      "env": {
        "FLASHBACK_USER_ID": "your-flashback-user-id",
        "FLASHBACK_API_BASE_URL": "https://your-flashback-api-host"
      }
    }
  }
}
```

### Tools

- `query_videos` — Search for video clips based on natural
  language query. `query` (string, required) — natural language
  description of what you're looking for; `max_results` (integer,
  optional, default 10) — maximum number of results to return
  (1–15).
- `get_setup_instructions` — Get detailed setup instructions for
  the video query system. No parameters.

The server also mirrors the upstream's documented resource URI
concept in its guide text only; no MCP resources are served.

## Docker

```bash
docker run -i -e FLASHBACK_USER_ID -e FLASHBACK_API_BASE_URL ghcr.io/cloudcorprecords/clipquery
docker run --rm ghcr.io/cloudcorprecords/clipquery setup
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios