be-timalens

# TimaLens — MCP Server

> AI whiteboard explainer videos for training agencies and instructional designers.

**Paste a script → scenes → hand-drawn storyboard → AI narration + captions → export MP4.**

This repository is the public MCP registry manifest for [TimaLens](https://timalens.com).
The live API is hosted at `https://api.timalens.com`.

---

## Connecting via MCP

TimaLens exposes a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) MCP endpoint at:

```
https://api.timalens.com/mcp
```

Authentication uses **OAuth 2.1 with PKCE** — your MCP client handles the flow automatically.

### Quick connect (any MCP client)

```json
{
  "mcpServers": {
    "timalens": {
      "type": "streamable-http",
      "url": "https://api.timalens.com/mcp"
    }
  }
}
```

Your client will auto-discover the OAuth server from the WWW-Authenticate header and open the TimaLens consent screen in your browser.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "timalens": {
      "type": "streamable-http",
      "url": "https://api.timalens.com/mcp"
    }
  }
}
```

### Cursor / VS Code (Cline, Continue, etc.)

```json
{
  "mcp": {
    "servers": {
      "timalens": {
        "type": "streamable-http",
        "url": "https://api.timalens.com/mcp"
      }
    }
  }
}
```

---

## OAuth endpoints

| Endpoint | URL |
|---|---|
| Authorization | `https://api.timalens.com/oauth/authorize` |
| Token | `https://api.timalens.com/oauth/token` |
| Dynamic registration | `https://api.timalens.com/oauth/register` |
| Revocation | `https://api.timalens.com/oauth/revoke` |
| Protected resource metadata | `https://api.timalens.com/.well-known/oauth-protected-resource` |
| Authorization server metadata | `https://api.timalens.com/.well-known/oauth-authorization-server` |

All flows use **PKCE (S256)**. Public clients (no client secret) are supported via dynamic client registration (RFC 7591).

---

## Available tools

Once authenticated, your AI assistant can:

| Tool | Scope | Description |
|---|---|---|
| `list_projects` | `projects:read` | List all your TimaLens video projects |
| `get_project` | `projects:read` | Full project details, boards, narration, and preview links |
| `get_generation_status` | `projects:read` | Poll generation or render progress |
| `create_video_draft` | `projects:write` | Create a draft from a script or topic (free, no credits charged) |
| `upload_reference_image` | `projects:write` | Upload a PNG/JPEG/WebP logo or character reference (max 10 MB) |
| `start_generation` | `projects:write` | Generate storyboard and narration for a draft |
| `get_render_quote` | `render:write` | Preview exact credit cost before any charge |
| `confirm_render` | `render:write` | Confirm a quoted render and start the paid export |

> Credits are only charged after you explicitly call `confirm_render` with a valid quote token.
> Every render failure automatically refunds the cost to your account.

---

## OAuth scopes

| Scope | What it allows |
|---|---|
| `projects:read` | Read-only access to your projects and generation status |
| `projects:write` | Create and modify drafts, upload reference assets |
| `render:write` | Request render quotes and confirm paid renders |

You can grant a narrower set of scopes at the consent screen.

---

## Support

- Website: [timalens.com](https://timalens.com)
- Docs: [timalens.com/support](https://timalens.com/support)
- Issues with the MCP integration: open an issue in this repository