# topview-mcp-server

MCP server exposing TopView.ai's video and image generation API as tools for Claude.

## Setup

1. Copy `.env.example` to `.env` and fill in your credentials (Account icon > API Settings on topview.ai):

```
TOPVIEW_API_KEY=...
TOPVIEW_UID=...
```

2. Install and build:

```
npm install
npm run build
```

## Tools

### Uploading

All three return a `fileId` that the generation tools consume. Which one to use depends on
where the file is and where this server runs:

- `topview_upload_base64` — **use this by default.** The client sends the file *contents*, so it
  works regardless of where the server runs. This is the one that makes drag-and-drop
  attachments work against a hosted deployment. Practical up to ~10 MB (base64 inflates payloads
  ~33%, and MCP clients cap message size).
- `topview_upload_url` — the server downloads a public `http(s)` URL, then uploads it. Best for
  large files, or media that already lives on a CDN. URLs resolving to private, loopback, or
  link-local addresses are rejected.
- `topview_upload_file` — reads a path on **the server's own filesystem**. Only works under the
  stdio transport, where server and client share a machine. Under the hosted HTTP transport the
  client's paths do not exist on the server and every call fails; use one of the two above.

### Generation

- `topview_text_to_video_submit` / `topview_text_to_video_query`
- `topview_image_to_video_submit` / `topview_image_to_video_query`
- `topview_text_to_image_submit` / `topview_text_to_image_query`
- `topview_image_edit_submit` / `topview_image_edit_query`

Submit tools accept `waitForCompletion` (default `true`) to poll internally (every ~4s, up to 5 minutes) and return the finished asset, or `false` to return immediately with a `taskId` for manual polling via the matching query tool.

## Registering with Claude Code

```
claude mcp add topview -- node "G:/07_ClaudeCode/topview-mcp-server/dist/index.js"
```

## Registering with Claude Desktop

Add to `claude_desktop_config.json` (Settings > Developer > Edit Config), under `mcpServers`:

```json
"topview": {
  "command": "node",
  "args": ["G:/07_ClaudeCode/topview-mcp-server/dist/index.js"]
}
```

Restart Claude Desktop completely (quit, not just close the window) for it to load.

## Using it from Cowork (remote/hosted mode)

Cowork sessions run in the cloud and can't launch a local process on your machine — they can
only reach an MCP server over the network. This repo ships a second entry point,
`src/httpServer.ts`, that exposes the exact same tools over Streamable HTTP so it can be hosted
and added as a **custom connector**.

1. Deploy this repo to any Node host (Render, Railway, Fly.io, etc.):
   - Build command: `npm install && npm run build`
   - Start command: `npm run start:http`
   - Environment variables to set on the host: `TOPVIEW_API_KEY`, `TOPVIEW_UID`, and
     `TOPVIEW_MCP_ACCESS_TOKEN` (a long random secret — required, otherwise anyone who finds the
     URL can spend your TopView credits). The host usually sets `PORT` automatically.
2. Once deployed you'll have a public URL, e.g. `https://topview-mcp.onrender.com`.
3. In Claude, go to **Settings > Connectors > Add a custom connector** and fill in:
   - **Nom**: `topview`
   - **URL du serveur MCP distant**: `https://topview-mcp.onrender.com/mcp?token=YOUR_SECRET`
     (the `?token=` must match `TOPVIEW_MCP_ACCESS_TOKEN`; leave the OAuth fields empty)
4. It will then be available in every Cowork session, not just one project folder.

`GET /healthz` returns `ok` once the server is up, useful for checking a deploy succeeded.

### Uploading files in hosted mode

A hosted server has no access to your machine's filesystem, so `topview_upload_file` cannot work
there — a path like `C:\Users\you\image.png` simply does not exist inside the container, and
no amount of path rewriting changes that. Use `topview_upload_base64` (client sends the bytes)
or `topview_upload_url` (server fetches a public URL) instead. Both are transport-agnostic and
work in local mode too.