# ImagineVid Agent Tools AI

Open-source distribution packages for [ImagineVid](https://imaginevid.io/), an
AI generation platform for images, videos, and music. This repository contains
the typed REST client, a CLI, and a local stdio MCP adapter. The hosted MCP
server remains the source of truth for identity, OAuth consent, scopes, credits,
quotes, idempotency, owned assets, and provider lifecycle.

## Choose a connection

### Hosted MCP

Use the OAuth-protected Streamable HTTP endpoint when your host supports remote
MCP servers:

```json
{
  "mcpServers": {
    "imaginevid": {
      "url": "https://imaginevid.io/api/mcp"
    }
  }
}
```

The host handles OAuth and explicit consent. The endpoint exposes
`models_list`, `credits_get`, `generation_quote`, `generation_create`, and
`generation_get`. See the [ImagineVid website](https://imaginevid.io/) for the
product and account flow.

### Local stdio MCP

After the npm package is released, configure a local host with:

```json
{
  "mcpServers": {
    "imaginevid": {
      "command": "npx",
      "args": ["-y", "imaginevid-mcp"],
      "env": {
        "IMAGINEVID_API_KEY": "${IMAGINEVID_API_KEY}",
        "IMAGINEVID_BASE_URL": "https://imaginevid.io"
      }
    }
  }
}
```

The local adapter uses a scoped API key, never prints it, and never retries an
ambiguous `submission_unknown` result. It accepts product capability values and
owned asset IDs, not provider parameters, arbitrary remote URLs, or inline
base64 media.

### CLI

After the npm package is released:

```bash
npm install --global imaginevid-cli
export IMAGINEVID_API_KEY="..."
imaginevid models list
imaginevid credits
```

The CLI also supports `assets upload`, `generate`, `generations get`, and
`generations wait`. `generate` quotes first and requires an exact explicit
credit confirmation plus a stable idempotency key.

## Development

```bash
pnpm install
pnpm test
pnpm build
```

The public package metadata and release files live in:

- [`imaginevid-client`](./packages/client), the typed Agent REST v1 client.
- [`imaginevid-cli`](./packages/cli), the command-line adapter.
- [`imaginevid-mcp`](./packages/mcp), the local stdio MCP adapter.
- [`server.json`](./server.json), the hosted MCP Registry metadata.

For product documentation, generation tools, and account access, visit the
[ImagineVid website](https://imaginevid.io/). Source issues belong in this
[GitHub repository](https://github.com/imagineVid/imaginevid-agent-tools-ai).

## Security and license

Do not commit API keys or account configuration. The hosted endpoint uses OAuth;
the local adapters read credentials from the environment or an owner-only local
config file. Report package or security issues through the
[ImagineVid support page](https://imaginevid.io/contact).

The public distribution code is available under [MIT-0](./LICENSE).