@wevi/mcp 0.1.2 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wevi AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,16 +6,23 @@ Connect Claude Desktop, Claude Code, Cursor, or Windsurf directly to your Wevi a
 
 ---
 
-## Features & Tools
+## How a video gets made
 
-* **`wevi_list_templates`**: Search and discover video templates by aspect ratio (`16:9`, `16:12`), category, or keywords.
-* **`wevi_get_template_schema`**: Inspect dynamic editable layers (text, colors, images, animations).
-* **`wevi_create_project`**: Create draft video projects and configure dynamic layer variables.
-* **`wevi_get_project`**: Retrieve video configuration parameters and render status.
-* **`wevi_trigger_render`**: Render high-definition MP4 videos via Wevi's cloud rendering pipeline with automatic polling and preview links.
-* **`wevi_get_render_status`**: Check export progress and fetch final download links.
-* **`wevi_generate_storyboard`**: Generate AI copywriting and scripts tailored to Wevi video templates.
-* **`wevi_capture_web_ui`**: Capture automated high-resolution web screenshots directly from live URLs.
+1. **`wevi_list_templates`** — browse *published* templates. Pick every template for the video from **one aspect ratio** (`16:9` or `16:12`).
+2. **`wevi_get_template_schema`** — read the editable layer keys (text, colors, sliders, toggles, dropdowns) for each template.
+3. **`wevi_create_project`** — create **one project with all scenes** (`scenes: [{ templateId, parameters, voiceoverText }]`). The aspect ratio is taken from the templates automatically.
+4. **`wevi_trigger_render`** — renders every scene and exports them as **one concatenated MP4** with music and voiceover. Returns the video URL when ready, or the current phase.
+5. **`wevi_get_render_status`** — poll by `projectId` until `phase` is `completed`, then use `videoUrl`.
+
+Helpers:
+
+* **`wevi_get_capabilities`** — what Wevi can and cannot make, what to ask the user first, limits and costs. Also sent as server instructions on connect.
+* **`wevi_get_credits`** — credit balance, per-action costs, packs and the top-up link. Live keys spend credits: 1 per scene render, 1/2/4 per 720p/1080p/4K export, 1 per storyboard draft or capture.
+* **`wevi_generate_storyboard`** — draft scene titles, on-screen text and voiceover from a brief.
+* **`wevi_capture_web_ui`** — capture a high-resolution screenshot of a live URL.
+* **`wevi_get_project`** — inspect a project's scenes and status.
+
+> Templates with `requiresUiCapture: true` need an interactive screen capture in the Wevi web app and are rejected by `wevi_create_project` for now.
 
 ---
 
@@ -23,8 +30,13 @@ Connect Claude Desktop, Claude Code, Cursor, or Windsurf directly to your Wevi a
 
 ### 1. Get your Wevi API Key
 1. Log in to [app.wevi.ai](https://app.wevi.ai).
-2. Go to **Profile → API Keys & MCP** (or visit [app.wevi.ai/app/profile?id=api-keys](https://app.wevi.ai/app/profile?id=api-keys)).
-3. Click **"Create New API Key"** and copy your secret key (`wevi_live_...`).
+2. Go to **Profile → API Keys & MCP** (or visit [app.wevi.ai/app/profile?id=api-keys](https://app.wevi.ai/app/profile?id=api-keys)).
+3. Click **"Create New API Key"** and copy your secret key.
+
+| Key | Behaviour |
+| :-- | :-- |
+| `wevi_live_…` | Production renders. Quality follows your plan (free plans export 720p with watermark). Spends API credits: your plan's monthly allowance first, then purchased packs. A `402` tells you how many credits are missing and where to top up. |
+| `wevi_test_…` | **Sandbox.** Every render is watermarked and capped at 720p, and nothing counts against your credits. Hard daily caps per key: 20 scene renders, 5 exports, max 4 scenes per project (reset 00:00 UTC). Ideal for trying prompts and CI. |
 
 ---
 
@@ -40,7 +52,7 @@ Add this to your Claude Desktop configuration file:
   "mcpServers": {
     "wevi": {
       "command": "npx",
-      "args": ["-y", "@wevi/mcp"],
+      "args": ["-y", "@wevi/mcp@latest"],
       "env": {
         "WEVI_API_KEY": "wevi_live_YOUR_SECRET_KEY_HERE"
       }
@@ -49,17 +61,11 @@ Add this to your Claude Desktop configuration file:
 }
 ```
 
----
-
 #### B. Claude Code CLI
-Run the following command in your terminal:
 
 ```bash
-claude mcp add wevi -- npx -y @wevi/mcp
+claude mcp add wevi -e WEVI_API_KEY="wevi_live_YOUR_SECRET_KEY_HERE" -- npx -y @wevi/mcp@latest
 ```
-*(When prompted or in your `.env`, provide `WEVI_API_KEY=wevi_live_...`)*
-
----
 
 #### C. Cursor & Windsurf
 Add to `.cursor/mcp.json` in your workspace:
@@ -69,7 +75,7 @@ Add to `.cursor/mcp.json` in your workspace:
   "mcpServers": {
     "wevi": {
       "command": "npx",
-      "args": ["-y", "@wevi/mcp"],
+      "args": ["-y", "@wevi/mcp@latest"],
       "env": {
         "WEVI_API_KEY": "wevi_live_YOUR_SECRET_KEY_HERE"
       }
@@ -78,25 +84,42 @@ Add to `.cursor/mcp.json` in your workspace:
 }
 ```
 
+Optional: set `WEVI_API_URL` to point at a self-hosted or staging API (defaults to `https://api-v2.wevi.ai/api/v2`).
+
 ---
 
 ## Example Prompts to Try in Claude
 
-* *"Show me available 16:9 widescreen templates for our product launch video."*
-* *"Find 16:12 desktop app templates in the SaaS category."*
-* *"Create a product promo video for our new feature launch called 'Wevi AI' and render it."*
-* *"Take a screenshot of stripe.com and use it in our showcase video template."*
+* *"List published 16:9 Wevi templates for a SaaS product launch."*
+* *"Build a 3-scene launch video for 'FocusFlow': hook, feature, CTA. Use one project, then render it and give me the MP4."*
+* *"Draft a storyboard for a 30-second promo about automated scheduling, then map it onto Wevi templates."*
+* *"Check whether my Wevi project 4f2c… has finished rendering."*
 
 ---
 
+## Remote server (Claude connectors, ChatGPT apps)
+
+The same tools are also served over HTTPS at `https://mcp.wevi.ai/mcp`, so you can add Wevi as a **custom connector** in Claude or as an app in ChatGPT without installing anything. Those clients sign you in with your Wevi account; no API key needed. See [docs.wevi.ai/docs/connectors](https://docs.wevi.ai/docs/connectors).
+
+To self-host the remote server:
+
+```bash
+npm install -g @wevi/mcp
+MCP_PUBLIC_URL=https://mcp.example.com WEVI_API_URL=https://api-v2.wevi.ai/api/v2 wevi-mcp-http
+```
+
+It exposes `/mcp`, `/health` and `/.well-known/oauth-protected-resource`, and accepts `Authorization: Bearer <Wevi OAuth token or API key>`.
+
 ## Development
 
 ```bash
 cd v2/mcp
 npm install
 npm run build
-npm start
+WEVI_API_KEY=wevi_test_... npm start
 ```
 
+Inspect the tools locally with `npx @modelcontextprotocol/inspector node dist/index.js`.
+
 ## License
 MIT © [Wevi AI](https://wevi.ai)