video-context-mcp-server 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -1,6 +1,9 @@
 # Video Context MCP Server
 
-Video Context MCP Server is a Model Context Protocol (MCP) server that gives MCP-compatible coding assistants (such as GitHub Copilot in VS Code, Cursor, and Claude Code) the ability to understand and analyze video content. Supports two AI backends: **Kimi K2.5** (Moonshot AI) and **GLM-4.6V** (Z.AI).
+An MCP server that gives coding assistants (GitHub Copilot, Cursor, Claude Code) the ability to understand and analyze video content.
+
+**[Official Documentation](https://www.videocontextmcp.com/)**<br />
+**[Tutorials Playlist](https://www.youtube.com/playlist?list=PL3Big7arQA0Rc1B6WVLmZqXKwDyp1fyme)**
 
 ## Features
 
@@ -9,42 +12,57 @@ Video Context MCP Server is a Model Context Protocol (MCP) server that gives MCP
 - 🖼️ **Frame Extraction** — Extract frames at specific timestamps or intervals
 - 🔍 **Timestamp Search** — Find the exact moment when something happens in a video
 - 📊 **Video Metadata** — Get duration, resolution, fps, codec, and other technical details
-- 🔄 **Dual Backend Support** — Choose between GLM-4.6V (cheap/free) or Kimi K2.5 (broader format support)
+- 🎙️ **Audio Transcription** — Transcribe speech with paragraph-level timestamps (`[MM:SS]`) or export as SRT/VTT subtitles and JSON using Deepgram, AssemblyAI, Groq/Whisper, or Gemini
+- 🔊 **Speaker Diarization** — Identify who said what (Deepgram and AssemblyAI)
+- 🔊 **Audio-Enhanced Analysis** — Auto-transcribes audio and injects transcripts into AI prompts for richer results (GLM/Kimi/Qwen)
+- 🔄 **Multi-Provider Support** — Choose between GLM-4.6V, Qwen3.6, Kimi K2.5, Gemini, or MiMo-V2 Omni
 - 🎯 **Smart Video Handling** — Extracts keyframes from long videos to reduce token usage
+- ⭐ **Pro tier** — Extended frame extraction, multi-platform downloads, higher resolution. [Learn more ↓](#pro)
 
-## Installation
-
-### Quick Start (Recommended for ordinary users)
+---
 
-#### 1. Prerequisites
+## Quick Start
 
-- Node.js 18+
-- VS Code with GitHub Copilot Chat enabled
+### Prerequisites
 
-#### 2. Get API keys
+- **Node.js 20+**
+- A supported MCP client (VS Code + GitHub Copilot Chat, Cursor, or Claude Code)
+- At least one video and one audio API key — see [API Keys](#api-keys) below
 
-You'll need API keys for one or both backends:
+### Install
 
-- **Kimi K2.5 (Moonshot AI)**: [Get API Key](https://platform.moonshot.ai)
-- **GLM-4.6V (Z.AI)**: [Get API Key](https://z.ai/manage-apikey/apikey-list)
+```bash
+npm install -g video-context-mcp-server
+```
 
-#### 3. Install the MCP server
+### Updating & version check
 
 ```bash
-npm install -g video-context-mcp-server
+npm ls -g video-context-mcp-server   # installed version
+npm outdated -g video-context-mcp-server        # check for updates
+npm install -g video-context-mcp-server@latest  # update
 ```
 
-This installs the executable command: `video-context-mcp`.
+### Configure Your MCP Client
+
+<details open>
+<summary><strong>VS Code</strong></summary>
+
+You can configure the MCP server globally (for all projects) or at the workspace level.
+
+**Global configuration**
 
-> **Tip:** Periodically re-run the above command to get the latest version:
->
-> ```bash
-> npm install -g video-context-mcp-server@latest
-> ```
+Open VS Code → Settings → MCP and add the server configuration.
 
-#### 4. Configure VS Code MCP
+**Workspace-level configuration**
 
-Create (or update) `.vscode/mcp.json` in your project/workspace:
+Create or update `.vscode/mcp.json` in your workspace.
+
+> **Important:** This file contains sensitive API keys. **Never commit it to source control.** Ensure it is added to your `.gitignore` file.
+
+#### Minimal configuration
+
+You only need one video API key to get started. The example below uses Gemini, which has a free tier and requires no credit card:
 
 ```json
 {
@@ -53,19 +71,46 @@ Create (or update) `.vscode/mcp.json` in your project/workspace:
       "type": "stdio",
       "command": "video-context-mcp",
       "env": {
+        "GEMINI_API_KEY": "your-gemini-key"
+      }
+    }
+  }
+}
+```
+
+#### Full configuration (all providers)
+
+Set all keys to enable the full fallback chain. If one provider is unavailable or rate-limited, the server automatically tries the next:
+
+```json
+{
+  "servers": {
+    "videoMcp": {
+      "type": "stdio",
+      "command": "video-context-mcp",
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
+        "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
         "MOONSHOT_API_KEY": "your-moonshot-key",
-        "Z_AI_API_KEY": "your-zai-key"
+        "MIMO_API_KEY": "your-mimo-key",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key"
       }
     }
   }
 }
 ```
 
-Open Copilot Chat in VS Code. The MCP server starts automatically when tools are needed.
+Open Copilot Chat — the MCP server starts automatically when tools are needed.
+
+</details>
 
-### Configure Cursor MCP
+<details>
+<summary><strong>Cursor</strong></summary>
 
-Add this server to your Cursor MCP configuration (global or project-level):
+You can configure the MCP server globally (for all projects) or at the project level. The configuration format is the same for both:
 
 ```json
 {
@@ -73,65 +118,86 @@ Add this server to your Cursor MCP configuration (global or project-level):
     "videoMcp": {
       "command": "video-context-mcp",
       "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
+        "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
         "MOONSHOT_API_KEY": "your-moonshot-key",
-        "Z_AI_API_KEY": "your-zai-key"
+        "MIMO_API_KEY": "your-mimo-key",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key"
       }
     }
   }
 }
 ```
 
-Notes:
+**Global configuration**
 
-- Run `npm install -g video-context-mcp-server` first if you haven't already.
-- If you prefer not to install globally, use `npx -y video-context-mcp-server@latest` as the command (slower startup due to registry check).
-- Set one or both API keys depending on which provider you use.
+Open Cursor → Settings → MCP and add the server configuration above.
 
-### Configure Claude Code MCP
+**Project-level configuration**
 
-Use the Claude CLI to register the MCP server:
+Create a `.cursor/mcp.json` (or `.mcp.json`) in your project root with the configuration above.
 
-```bash
-claude mcp add videoMcp video-context-mcp \
-  --env MOONSHOT_API_KEY=your-moonshot-key \
-  --env Z_AI_API_KEY=your-zai-key
-```
+> **Important:** This file contains sensitive API keys. **Never commit it to source control.** Ensure it is added to your `.gitignore` file.
 
-Then verify with:
+</details>
 
-```bash
-claude mcp list
-```
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-If you prefer not to install globally, register via `npx` instead (slower startup due to registry check):
+**Option A — CLI (`claude mcp add`)**
 
 ```bash
-claude mcp add videoMcp npx -y video-context-mcp-server@latest \
+claude mcp add \
+  --env GEMINI_API_KEY=your-gemini-key \
+  --env Z_AI_API_KEY=your-zai-key \
+  --env DASHSCOPE_API_KEY=your-dashscope-key \
   --env MOONSHOT_API_KEY=your-moonshot-key \
-  --env Z_AI_API_KEY=your-zai-key
+  --env MIMO_API_KEY=your-mimo-key \
+  --env DEEPGRAM_API_KEY=your-deepgram-key \
+  --env ASSEMBLYAI_API_KEY=your-assemblyai-key \
+  --env GROQ_API_KEY=your-groq-key \
+  videoMcp -- video-context-mcp
 ```
 
-### Troubleshooting Setup
+Verify with `claude mcp list`.
+
+**Option B — project-level `.mcp.json`**
+
+Create `.mcp.json` in your project root:
 
-- **`video-context-mcp: command not found`**
-  - Make sure Node.js is installed and available in your shell (`node -v`, `npm -v`).
-  - If installed globally, re-run: `npm install -g video-context-mcp-server`.
-  - If global binaries are not on PATH, use `npx -y video-context-mcp-server@latest` instead of `video-context-mcp`.
+> **Important:** This file contains sensitive API keys. **Never commit it to source control.** Ensure it is added to your `.gitignore` file.
+
+```json
+{
+  "mcpServers": {
+    "videoMcp": {
+      "command": "video-context-mcp",
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
+        "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
+        "MOONSHOT_API_KEY": "your-moonshot-key",
+        "MIMO_API_KEY": "your-mimo-key",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key"
+      }
+    }
+  }
+}
+```
 
-- **MCP server not appearing in client**
-  - Restart the client app after changing MCP configuration.
-  - Validate JSON syntax in your MCP config file.
-  - For Claude Code, verify registration with `claude mcp list`.
+</details>
 
-- **Missing API key errors**
-  - Set `Z_AI_API_KEY` for GLM usage and `MOONSHOT_API_KEY` for Kimi usage.
-  - You can set only one key if you only use one provider.
-  - For local files, if `provider=glm` is requested but `Z_AI_API_KEY` is missing, the server automatically falls back to Kimi when `MOONSHOT_API_KEY` is available.
-  - For remote `http(s)` video URLs, use `provider=glm` (Kimi requires local file input).
+<details>
+<summary><strong>Run via npx (no global install)</strong></summary>
 
-### Alternative: Run via npx without global install
+Use `npx -y video-context-mcp-server@latest` as the command instead of `video-context-mcp`. This adds a startup delay (npm registry check) but self-updates automatically.
 
-If you prefer not to install globally, you can use `npx` instead. Note this adds a startup delay due to the npm registry check on each run:
+**VS Code example:**
 
 ```json
 {
@@ -141,137 +207,516 @@ If you prefer not to install globally, you can use `npx` instead. Note this adds
       "command": "npx",
       "args": ["-y", "video-context-mcp-server@latest"],
       "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
+        "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
         "MOONSHOT_API_KEY": "your-moonshot-key",
-        "Z_AI_API_KEY": "your-zai-key"
+        "MIMO_API_KEY": "your-mimo-key",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key"
       }
     }
   }
 }
 ```
 
-The `@latest` tag ensures you always get the newest published version, at the cost of a network round-trip on every startup — this also means the `npx` approach self-updates automatically and requires no manual update step.
+**Claude Code:**
+
+```bash
+claude mcp add \
+  --env GEMINI_API_KEY=your-gemini-key \
+  --env Z_AI_API_KEY=your-zai-key \
+  --env DASHSCOPE_API_KEY=your-dashscope-key \
+  --env MOONSHOT_API_KEY=your-moonshot-key \
+  --env MIMO_API_KEY=your-mimo-key \
+  --env DEEPGRAM_API_KEY=your-deepgram-key \
+  --env ASSEMBLYAI_API_KEY=your-assemblyai-key \
+  --env GROQ_API_KEY=your-groq-key \
+  videoMcp -- npx -y video-context-mcp-server@latest
+```
+
+</details>
 
-### For contributors: install from source
+> **Tip:** Set keys for all providers you can access — this maximises the fallback chain. If the default provider is unavailable or rate-limited, the server automatically retries with the next available one. At minimum you need one video key and one audio key, but more is better.
 
-Clone this repository, then:
+---
+
+## Available Tools
+
+| Tool               | Description                          | Key Parameters                                                                              |
+| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `analyze_video`    | Ask questions about video content    | `videoPath`, `question`, `provider?`                                                        |
+| `summarize_video`  | Generate a structured video summary  | `videoPath`, `provider?`                                                                    |
+| `extract_frames`   | Extract frames from a video          | `videoPath`, `mode`, `count/intervalSec/timestamps/sceneThreshold`, `maxImages?`, `offset?` |
+| `search_timestamp` | Find when something specific happens | `videoPath`, `query`, `provider?`                                                           |
+| `get_video_info`   | Get video metadata                   | `videoPath`                                                                                 |
+| `transcribe_video` | Transcribe audio/speech from a video | `videoPath`, `provider?`, `language?`, `diarize?`, `translate?`, `outputFormat?`            |
+
+All tools accept local file paths, `file://` URIs, and remote `http(s)` URLs. Remote videos are downloaded automatically.
+
+### Usage Examples
+
+**Local files**
+
+> "Analyze the video at `./demo.mp4` and tell me what happens in it"
+
+> "Summarize `./long-video.mp4`"
+
+> "Extract 5 evenly-spaced frames from `./recording.mp4`"
+
+> "Extract frames at scene changes from `./video.mp4`" (set `mode: scene`)
+
+> "At what timestamp does the person wave in `./clip.mp4`?"
+
+> "Transcribe `./interview.mp4` with speaker diarization using AssemblyAI"
+
+> "Transcribe this Spanish video and translate it to English: `./video.mp4`"
+
+> "Generate SRT subtitles for `./interview.mp4`" (set `outputFormat: srt`)
+
+> "Export a WebVTT subtitle file from `./talk.mp4`" (set `outputFormat: vtt`)
+
+**Remote video files** (direct URLs — works for all users)
+
+> "Analyze this video: `https://example.com/product-demo.mp4`"
+
+> "Get the metadata for `https://cdn.example.com/sample.webm`"
+
+**Platform videos** (YouTube, Vimeo, TikTok, Bilibili, etc. — requires [Pro](#pro) for non-YouTube)
+
+> "Summarize this YouTube video: `https://www.youtube.com/watch?v=dQw4w9WgXcQ`"
+
+> "At what point does the speaker mention pricing in `https://www.youtube.com/watch?v=abc123`?"
+
+> "Transcribe the audio from `https://vimeo.com/123456789`"
+
+---
+
+## API Keys
+
+### Video Providers
+
+Set all keys to get the full fallback chain. The server will try Gemini first, then GLM, then Qwen, then Kimi, then MiMo, so having all keys ensures it never gets stuck without a working provider:
+
+| Provider                                        | Key                 | Link                                                                                          |
+| ----------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
+| **Gemini 3 Flash Preview** (default, free-tier) | `GEMINI_API_KEY`    | [Get key](https://aistudio.google.com/app/apikey)                                             |
+| **GLM-4.6V** (free-tier)                        | `Z_AI_API_KEY`      | [Get key](https://z.ai/manage-apikey/apikey-list)                                             |
+| **Qwen3.6** (FREE — promotional)                | `DASHSCOPE_API_KEY` | [Get key](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=dashboard#/api-key) |
+| **Kimi K2.5** (paid)                            | `MOONSHOT_API_KEY`  | [Get key](https://platform.moonshot.ai)                                                       |
+| **MiMo-V2 Omni** (paid)                         | `MIMO_API_KEY`      | [Get key](https://platform.xiaomimimo.com/#/console/api-keys)                                 |
+
+When a provider's API key is missing or its API call fails at runtime, tools automatically fall back through the remaining providers in priority order, starting from the configured default:
+
+- Gemini default (standard): **Gemini → GLM → Qwen → Kimi → MiMo**
+- GLM default: **GLM → Gemini → Qwen → Kimi → MiMo**
+- Qwen default: **Qwen → Gemini → GLM → Kimi → MiMo**
+- Kimi default: **Kimi → Gemini → GLM → Qwen → MiMo**
+- MiMo default: **MiMo → Gemini → GLM → Qwen → Kimi**
+
+### Audio Providers
+
+Similarly, set all audio keys so transcription always has a fallback provider available:
+
+| Provider                                  | Key                  | Link                                            |
+| ----------------------------------------- | -------------------- | ----------------------------------------------- |
+| **Deepgram** (default, $200 free credits) | `DEEPGRAM_API_KEY`   | [Get key](https://console.deepgram.com/)        |
+| **AssemblyAI** ($50 free credits)         | `ASSEMBLYAI_API_KEY` | [Get key](https://www.assemblyai.com/dashboard) |
+| **Groq/Whisper** (free-tier)              | `GROQ_API_KEY`       | [Get key](https://console.groq.com/)            |
+| **Gemini** (free-tier)                    | `GEMINI_API_KEY`     | Reuses the same key as the video provider       |
+
+When an audio key is missing or an audio API call fails at runtime, tools automatically fall back through the remaining providers in priority order, starting from the configured default (e.g. with Deepgram default: **Deepgram → AssemblyAI → Groq → Gemini**).
+
+---
+
+## Provider Comparison
+
+### Video Providers
+
+| Feature        | Gemini 3 Flash Preview (default)               | GLM-4.6V                                               | Qwen3.6                                                | Kimi K2.5                                      | MiMo-V2 Omni                                           |
+| -------------- | ---------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------ |
+| Price          | Free tier available                            | Free tier available (GLM-4.6V-Flash)                   | **FREE** (promotional launch period)                   | $0.60 input / $3.00 output per 1M tokens       | $0.40 input / $2.00 output per 1M tokens               |
+| Video formats  | mp4, mpeg, mov, avi, flv, mpg, webm, wmv, 3gpp | mp4, avi, mov, wmv, webm, m4v                          | mp4, avi, mov, wmv, webm, m4v                          | mp4, mpeg, mov, avi, flv, mpg, webm, wmv, 3gpp | mp4, mov, avi, wmv                                     |
+| Context window | 1M tokens                                      | 128K tokens                                            | 1M tokens                                              | 256K tokens                                    | 256K tokens                                            |
+| Max file size  | 2 GB                                           | ~12 MB base64 / frames fallback / **unlimited w/ S3↓** | ~10 MB base64 / frames fallback / **unlimited w/ S3↓** | 100 MB                                         | ~10 MB base64 / frames fallback / **unlimited w/ S3↓** |
+| Best for       | **Default** — free, no card required           | Free, no card required                                 | **FREE during promo** — SOTA agentic coding            | Paid — broadest format support                 | Paid — thinking mode; multimodal                       |
+
+**Gemini 3 Flash Preview** is the default — it offers a free tier with no credit card required, 1M context window, and 2 GB file support. **GLM-4.6V** is the second fallback — also free with no card required. **Qwen3.6** is currently **FREE** during its promotional launch period (released April 2, 2026) — standard pricing will be $0.50 input / $3.00 output per 1M tokens. **Kimi K2.5** is a paid provider with the broadest video format support. **MiMo-V2 Omni** is Xiaomi's multimodal model with thinking mode support ($0.40 input / $2.00 output per 1M tokens).
+
+Set `VIDEO_MCP_DEFAULT_PROVIDER=gemini`, `glm`, `qwen`, `kimi`, or `mimo` to change the default provider used when a tool call does not pass `provider`. If a tool call includes `provider`, that per-call value takes precedence.
+
+> **ℹ️ Large local files with GLM, Qwen, or MiMo:** All three providers have a 10–12 MB base64 limit for local files. When a file exceeds this limit, the server first tries to fall back to an upload-capable provider (Gemini or Kimi) if one is available in the fallback chain. Frame-based analysis (evenly-spaced keyframes sent as images) is used only as a **last resort** when no upload-capable provider is available, or when all upload-capable providers fail at runtime — no configuration needed. For the highest quality with large local videos, set up the optional **S3 relay** (below) — GLM, Qwen, and MiMo will receive a presigned URL to the full video, bypassing the limit entirely and taking priority over both fallbacks.
+
+<details open>
+<summary><strong>Automatic S3 relay: bypass the 10 MB local file limit with GLM, Qwen, and MiMo</strong></summary>
+
+**GLM-4.6V**, **Qwen3.6**, and **MiMo-V2 Omni** all accept direct video URLs, but base64-encoding a local file caps out at **10–12 MB**. Above that limit, the server first tries to fall back to an upload-capable provider (Gemini or Kimi) if one is available, then falls back to **frame-based analysis** as a last resort. For the best results on large local videos, set `AWS_S3_BUCKET` — the server uploads the full video to S3 and passes a presigned URL to GLM, Qwen, and MiMo, bypassing the base64 limit entirely and taking priority over both fallbacks. No manual upload step needed.
+
+#### Why S3 works
+
+GLM, Qwen, and MiMo require the serving endpoint to provide `Content-Length` and `Content-Type` headers alongside the video. AWS S3 presigned URLs include both headers automatically.
+
+---
+
+#### Prerequisites
+
+Before setting up the S3 relay, you'll need an AWS account and access credentials.
+
+##### 1. Create an AWS account
+
+1. Go to [aws.amazon.com](https://aws.amazon.com/) and click **Create an AWS Account**.
+2. Enter your email address, a password, and an AWS account name.
+3. Choose the **Basic Support — Free** plan (sufficient for S3 relay usage).
+4. Fill in your contact and billing information. A valid credit or debit card is required, but S3 usage within the free tier costs nothing.
+5. Verify your identity via phone call or SMS.
+6. Once confirmed, sign in to the [AWS Management Console](https://console.aws.amazon.com/).
+
+> New AWS accounts include a 12-month Free Tier with 5 GB of S3 storage and 20,000 GET requests per month — more than enough for typical video analysis workflows.
+
+##### 2. Get your AWS Access Key ID and Secret Access Key
+
+The S3 relay needs programmatic access to your S3 bucket. You'll create an IAM user with limited permissions:
+
+1. In the AWS Console, search for **IAM** in the top search bar and open the IAM dashboard.
+2. Click **Users** in the left sidebar, then **Create user**.
+3. Enter a user name (e.g., `video-mcp-s3`) and click **Next**.
+4. Under **Permissions options**, select **Attach policies directly**.
+5. Click **Create policy** — this opens a new tab:
+   - Switch to the **JSON** tab and paste the following minimum-permission policy:
+     ```json
+     {
+       "Version": "2012-10-17",
+       "Statement": [
+         {
+           "Effect": "Allow",
+           "Action": [
+             "s3:PutObject",
+             "s3:GetObject",
+             "s3:DeleteObject",
+             "s3:ListBucket"
+           ],
+           "Resource": [
+             "arn:aws:s3:::your-globally-unique-bucket-name",
+             "arn:aws:s3:::your-globally-unique-bucket-name/*"
+           ]
+         }
+       ]
+     }
+     ```
+
+- Replace `your-globally-unique-bucket-name` with your actual globally unique bucket name (you'll create it in the next step).
+- Click **Next**, give the policy a name like `VideoMcpS3Access`, then **Create policy**.
+
+6. Go back to the user creation tab, click the refresh icon, search for `VideoMcpS3Access`, select it, and click **Next** → **Create user**.
+7. Open the newly created user, go to the **Security credentials** tab.
+8. Under **Access keys**, click **Create access key**.
+9. On **Access key best practices & alternatives**, choose **Other** or the closest equivalent programmatic/local-code option shown in your console, then click **Next**.
+10. Optionally add a description tag, then click **Create access key**.
+11. Copy and save the **Access Key ID** and **Secret Access Key** — you won't be able to see the secret key again after closing this dialog.
+
+> **Never commit your Secret Access Key to version control or share it publicly.** Only add it to your local MCP configuration or AWS credentials file.
+
+##### 3. (Optional) Install and configure the AWS CLI
+
+The AWS CLI is only needed if you want to create buckets from the terminal or use the `~/.aws/credentials` method instead of environment variables. If you plan to add credentials directly to your MCP `env` block, you can skip this step.
+
+**Install the AWS CLI**
+
+- **Windows:** Download the installer from [aws.amazon.com/cli](https://aws.amazon.com/cli/) or run:
+  ```bash
+  winget install Amazon.AWSCLI
+  ```
+- **macOS:**
+  ```bash
+  curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
+  sudo installer -pkg AWSCLIV2.pkg -target /
+  ```
+- **Linux:**
+  ```bash
+  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+  unzip awscliv2.zip
+  sudo ./aws/install
+  ```
+
+**Configure your credentials**
+
+Run the following command and paste your Access Key ID and Secret Access Key when prompted:
 
 ```bash
-npm install
-npm run build
+aws configure
 ```
 
-Then use this `.vscode/mcp.json` server command:
+You'll be asked for:
+
+- **AWS Access Key ID** — paste the key you saved earlier
+- **AWS Secret Access Key** — paste the secret key you saved earlier
+- **Default region name** — enter your preferred region (e.g., `us-east-1`)
+- **Default output format** — press Enter for `json`
+
+This stores your credentials in `~/.aws/credentials` and `~/.aws/config`, which the MCP server reads automatically.
+
+---
+
+#### One-time setup
+
+##### 1. Create an S3 bucket
+
+If you installed the AWS CLI:
+
+```bash
+aws s3 mb s3://your-globally-unique-bucket-name
+```
+
+Or create it manually in the [S3 Console](https://s3.console.aws.amazon.com/):
+
+1. Open the S3 dashboard and click **Create bucket**.
+2. Enter a globally unique bucket name (e.g., `your-globally-unique-bucket-name`).
+3. Choose the AWS Region you want to use. This should match `AWS_REGION` in your MCP config or AWS CLI profile.
+4. Leave **Block all public access** enabled. The bucket does not need to be public — the server uses presigned URLs.
+5. Keep the default **Object Ownership** setting (`ACLs disabled` / `Bucket owner enforced`).
+6. Leave the remaining settings at their defaults, then click **Create bucket**.
+
+> You do not need to add a bucket policy or make objects public. A private bucket works fine because the MCP server generates time-limited presigned URLs for each uploaded video.
+
+##### 2. Add `AWS_S3_BUCKET` to your MCP config
+
+**VS Code (`.vscode/mcp.json`)**
 
 ```json
 {
   "servers": {
     "videoMcp": {
       "type": "stdio",
-      "command": "node",
-      "args": ["${workspaceFolder}/dist/index.js"],
+      "command": "video-context-mcp",
       "env": {
-        "MOONSHOT_API_KEY": "your-moonshot-key",
-        "Z_AI_API_KEY": "your-zai-key"
+        "AWS_S3_BUCKET": "your-globally-unique-bucket-name",
+        "GEMINI_API_KEY": "your-gemini-key"
       }
     }
   }
 }
 ```
 
-### Debugging Behavior in VS Code
+---
+
+#### AWS Credential Resolution
+
+The server resolves AWS credentials in this order — you only need to configure one:
+
+1. **Environment variables** — add directly to your MCP `env` block (no AWS CLI needed):
+   ```jsonc
+   "AWS_S3_BUCKET": "your-globally-unique-bucket-name",
+   "AWS_ACCESS_KEY_ID": "AKIA...",
+   "AWS_SECRET_ACCESS_KEY": "your-secret-key",
+   "AWS_REGION": "us-east-1"
+   ```
+2. **`~/.aws/credentials`** — if the AWS CLI is configured, credentials are picked up automatically. Only `AWS_S3_BUCKET` is needed in your MCP config:
+   ```jsonc
+   "AWS_S3_BUCKET": "your-globally-unique-bucket-name"
+   ```
+3. **IAM instance role / ECS task role** — for AWS-hosted environments.
+
+---
+
+#### How it works at runtime
 
-When your `.vscode/mcp.json` includes a `dev` block such as:
+Every time you analyze a local video (or a platform download like YouTube) with GLM, Qwen, or MiMo:
+
+1. The server detects the file is too large for base64 encoding.
+2. The file is uploaded to `s3://your-globally-unique-bucket-name/video-mcp-relay/<uuid>.<ext>`.
+3. A presigned URL (valid for 1 hour) is passed to the AI provider.
+4. The provider downloads the video directly from S3.
+5. The object is kept in the bucket for reuse within the same session.
+
+**Cleanup:** Relayed S3 objects are deleted automatically when the MCP server session ends. Orphaned objects from crashed sessions are swept at next startup.
+
+To keep objects in the bucket for reuse across sessions (useful for large files you analyze repeatedly):
 
 ```jsonc
-"dev": {
-  "watch": "src/**/*.ts",
-  "debug": { "type": "node" }
-}
+"AWS_S3_RELAY_CLEANUP": "false"
 ```
 
-you may see frequent logs in the **Output** panel under `MCP: videoMcp`.
+**Cost**: AWS S3 free tier covers 5 GB storage + 20K GET requests/month for 12 months. After the free tier, storage costs roughly $0.023/GB/month — negligible for most use cases.
+
+---
 
-This is expected in development mode:
+#### Manual presigned URLs (alternative)
 
-- `watch` restarts/reloads the MCP server when TypeScript files change
-- `debug` enables Node debug integration
-- MCP protocol payloads (tool schemas, discovery events, lifecycle messages) are printed in that output channel
+You can also pass a presigned URL directly to any tool without configuring the relay:
 
-If you want less noise, remove either:
+```bash
+aws s3 cp my-video.mp4 s3://your-globally-unique-bucket-name/my-video.mp4
+aws s3 presign s3://your-globally-unique-bucket-name/my-video.mp4 --expires-in 3600
+# → https://your-globally-unique-bucket-name.s3.amazonaws.com/my-video.mp4?X-Amz-...
+```
 
-- `dev.debug` (keeps auto-watch, disables debug integration), or
-- the full `dev` block (disables watch + debug behavior)
+Then pass the URL directly to `analyze_video`, `summarize_video`, or any other tool.
 
-## Available Tools
+</details>
+
+### Audio Providers
 
-| Tool               | Description                          | Parameters                                          |
-| ------------------ | ------------------------------------ | --------------------------------------------------- |
-| `analyze_video`    | Ask questions about video content    | `videoPath`, `question`, `provider?`                |
-| `summarize_video`  | Generate a structured video summary  | `videoPath`, `provider?`                            |
-| `extract_frames`   | Extract frames from a video          | `videoPath`, `mode`, `count/intervalSec/timestamps` |
-| `search_timestamp` | Find when something specific happens | `videoPath`, `query`, `provider?`                   |
-| `get_video_info`   | Get video metadata                   | `videoPath`                                         |
+| Feature             | Deepgram (default)           | AssemblyAI               | Groq/Whisper            | Gemini                     |
+| ------------------- | ---------------------------- | ------------------------ | ----------------------- | -------------------------- |
+| Price               | Paid ($200 free credits)     | Paid ($50 free credits)  | Free tier available     | Free tier available        |
+| Speaker diarization | Yes                          | Yes                      | No                      | No                         |
+| English Translation | No                           | No                       | Yes                     | Yes                        |
+| Best for            | **Default** (fast, accurate) | High-quality diarization | Free/cost-conscious use | Users already using Gemini |
 
-### Path and Provider Constraints
+> **Note:** "Translation" here means speech-to-English conversion (output English regardless of the spoken language). It is distinct from multilingual transcription — Deepgram and AssemblyAI both support transcribing dozens of languages natively, but they always output in the source language. Use Groq or Gemini when you need an English transcript of non-English audio.
 
-- `analyze_video` and `summarize_video` support local files and `http(s)` URLs.
-- For remote `http(s)` URLs, only `provider=glm` is supported. `provider=kimi` requires a local file.
-- `search_timestamp`, `extract_frames`, and `get_video_info` currently support local files only.
-- For local inputs, `analyze_video`, `summarize_video`, and `search_timestamp` accept normal paths or `file://` URIs.
-- `extract_frames` and `get_video_info` currently expect local filesystem path strings.
+Set `AUDIO_MCP_DEFAULT_PROVIDER` to change the default.
 
-## Usage Examples
+---
 
-### Analyze Video
+## Environment Variables
 
-Ask Copilot Chat:
+### Core
 
-> "Analyze the video at `./demo.mp4` and tell me what happens in it"
+| Variable                     | Description                                                                                                           | Default  |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- |
+| `Z_AI_API_KEY`               | Z.AI API key for GLM-4.6V                                                                                             | —        |
+| `DASHSCOPE_API_KEY`          | Alibaba Cloud API key for Qwen3.6                                                                                     | —        |
+| `MOONSHOT_API_KEY`           | Moonshot AI API key for Kimi K2.5                                                                                     | —        |
+| `GEMINI_API_KEY`             | Google API key for Gemini                                                                                             | —        |
+| `MIMO_API_KEY`               | Xiaomi MiMo API key for MiMo-V2 Omni                                                                                  | —        |
+| `VIDEO_MCP_DEFAULT_PROVIDER` | Default video provider used when a tool call does not pass `provider`; a per-call `provider` argument can override it | `gemini` |
 
-### Summarize Video
+### S3 Relay
 
-> "Summarize the video at `./long-video.mp4`"
+| Variable                | Description                                                                                                                                                                                             | Default |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `AWS_S3_BUCKET`         | S3 bucket name for automatic video relay. When set, local videos (and platform downloads) are uploaded to S3 and GLM/Qwen receive a presigned URL — bypassing the 10–12 MB base64 limit.                | —       |
+| `AWS_ACCESS_KEY_ID`     | AWS access key ID. Required if you are not using `~/.aws/credentials` or an IAM role.                                                                                                                   | —       |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret access key. Required alongside `AWS_ACCESS_KEY_ID`.                                                                                                                                          | —       |
+| `AWS_REGION`            | AWS region for the S3 bucket (e.g. `us-east-1`). Required if not set in `~/.aws/config`.                                                                                                                | —       |
+| `AWS_S3_RELAY_CLEANUP`  | Set to `false` to keep relayed S3 objects in the bucket for reuse across sessions. Default: relayed objects are deleted when the MCP server session ends **and** orphaned objects are swept at startup. | `true`  |
 
-### Extract Frames
+### Audio
 
-> "Extract 5 evenly-spaced frames from `./video.mp4`"
+| Variable                       | Description                                                                                                                                                                       | Default    |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `DEEPGRAM_API_KEY`             | Deepgram API key                                                                                                                                                                  | —          |
+| `ASSEMBLYAI_API_KEY`           | AssemblyAI API key                                                                                                                                                                | —          |
+| `GROQ_API_KEY`                 | Groq API key for Whisper transcription                                                                                                                                            | —          |
+| `AUDIO_MCP_DEFAULT_PROVIDER`   | Default audio provider: `deepgram`, `assemblyai`, `groq`, or `gemini`. Falls back in that order when the selected key is missing.                                                 | `deepgram` |
+| `AUDIO_ENHANCE_VIDEO_ANALYSIS` | Inject audio transcripts into `analyze_video`/`summarize_video` prompts (GLM/Kimi/Qwen/MiMo). `auto` = transcribe when audio track detected; `true` = always; `false` = disabled. | `auto`     |
 
-> "Extract a frame at timestamp 30 seconds from `./video.mp4`"
+### Caching
 
-### Search Timestamp
+Downloaded videos, extracted frames, audio tracks, and transcripts are cached together in a persistent per-video directory. Subsequent tool calls that reference the same video reuse cached artifacts instead of re-running ffmpeg, re-downloading, or re-calling audio provider APIs.
 
-> "In `./video.mp4`, at what timestamp does the person wave?"
+| Variable                      | Description                                                                                                                   | Default           |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `VIDEO_MCP_CACHE_TTL_MINUTES` | How long video artifacts (video file, frames, audio, transcripts) are cached across tool calls (minutes). Set `0` to disable. | `43200` (30 days) |
+| `VIDEO_MCP_CACHE_MAX_ENTRIES` | Max entries in the artifact cache. LRU eviction at the video level. Set `0` for unbounded.                                    | `100`             |
+| `VIDEO_MCP_CACHE_MAX_MB`      | Max total disk size for the cache (megabytes). LRU eviction when the limit is reached. Set `0` to disable.                    | `5120` (5 GB)     |
 
-### Get Video Info
+#### Cache Storage Location
 
-> "Get the video info for `./video.mp4`"
+The cache is stored in a `video-mcp-cache` folder within your system's temporary directory:
 
-## Additional Guides
+- **Windows:** `%TEMP%\video-mcp-cache`  
+  (e.g., `C:\Users\<you>\AppData\Local\Temp\video-mcp-cache`)
+- **macOS:** `$TMPDIR/video-mcp-cache`  
+  (e.g., `/var/folders/xx/yyyy/T/video-mcp-cache`)
+- **Linux:** `/tmp/video-mcp-cache`
 
-- [Screen Recording for Small File Sizes (Windows)](docs/screen-recording-small-files.md)
+#### Automatic Cleanup
 
-## Backend Comparison
+The server automatically manages the cache by:
 
-| Feature        | GLM-4.6V                      | Kimi K2.5                                      |
-| -------------- | ----------------------------- | ---------------------------------------------- |
-| Video formats  | mp4, avi, mov, wmv, webm, m4v | mp4, mpeg, mov, avi, flv, mpg, webm, wmv, 3gpp |
-| Price          | $0.30 input / $0.90 output    | $0.60 input / $3.00 output                     |
-| Free tier      | Yes (GLM-4.6V-Flash)          | No                                             |
-| Context window | 128K                          | 256K                                           |
-| Best for       | Cost efficiency, free tier    | Broader format support                         |
+1. **Startup Sweep:** Removing any cache entries older than the TTL at server startup.
+2. **LRU Eviction:** Evicting the least-recently-used video entry (all its artifacts together) when the `VIDEO_MCP_CACHE_MAX_ENTRIES` limit is reached.
+3. **Size Eviction:** Evicting the least-recently-used video entry when the total cache size exceeds `VIDEO_MCP_CACHE_MAX_MB` (default 5 GB).
 
-**GLM-4.6V is the default backend** because it offers a free tier (GLM-4.6V-Flash) — meaning you can get started at no cost. If you have spare API credits or budget to spend, Kimi K2.5 is worth trying for its broader format support and larger context window. Set `VIDEO_MCP_DEFAULT_PROVIDER=kimi` to switch the default. This env default is used when a tool call omits the `provider` parameter.
+#### Cache Management CLI
 
-## Environment Variables
+`video-context-mcp` (or the short alias `vmcp`) ships with built-in cache management commands. Run them from any terminal — they complete immediately and do **not** start the MCP server.
+
+```bash
+# Show cache location, size, entry count, TTL, and per-entry breakdown
+vmcp cache status
+
+# Print the cache directory path (useful for scripting)
+vmcp cache path
+cd "$(vmcp cache path)"
+
+# Copy the entire cache tree to ./video-mcp-cache (or a custom path)
+vmcp cache copy
+
+# macOS / Linux — absolute path
+vmcp cache copy --dest=/Users/alice/projects/cache-backup
+vmcp cache copy --dest=/tmp/cache-backup
+
+# Windows — absolute path (both \ and / are supported)
+vmcp cache copy --dest=C:\Users\alice\projects\cache-backup
+vmcp cache copy --dest=C:/Users/alice/projects/cache-backup
+
+# Relative path (resolved from CWD — works on all platforms)
+vmcp cache copy --dest=./backup
+vmcp cache copy --dest=../sibling/cache
+
+# Paths with spaces — wrap the value in quotes
+vmcp cache copy --dest="/Users/alice/My Projects/cache-backup"
+vmcp cache copy --dest="C:\Users\alice\My Documents\cache-backup"
+
+# Remove only entries older than the TTL (defaults to 30 days if not set)
+vmcp cache clear:expired
+
+# If you've set a custom TTL in mcp.json, pass it explicitly — CLI commands
+# run as a separate process and don't inherit env vars from mcp.json
+VIDEO_MCP_CACHE_TTL_MINUTES=10 vmcp cache clear:expired
+
+# Delete ALL cache entries — prompts for confirmation
+vmcp cache clear:all
+vmcp cache clear:all --yes   # skip confirmation
+```
+
+### Video Summarization
+
+| Variable               | Description                                                                                                                                                                                                                                                                                                                                                                          | Default               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
+| `VIDEO_MCP_MAX_FRAMES` | Max keyframes for `summarize_video` (GLM/Qwen/MiMo always; Kimi only when video > 100 MB; Gemini always uploads full video). **Free**: clamped 5–50. **Pro**: default 100; set `0` for uncapped. Either way, trailing frames are automatically dropped if the total payload exceeds the provider's size limit (12 MB for GLM, 10 MB for Qwen/MiMo, 80 MB for Kimi's frame fallback). | `50` free / `100` pro |
+
+### Qwen
+
+| Variable                  | Description                                                                                                                                                                                                                                                | Default                                                                   |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `QWEN_BASE_URL`           | Override the DashScope API endpoint. Use for regional routing: Singapore (default), Virginia (`https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions`), or Beijing (`https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`). | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions` |
+| `QWEN_REQUEST_TIMEOUT_MS` | Client-side timeout (ms) for Qwen API requests. DashScope applies a server-side limit of ~5 minutes, so values above ~285000 are unlikely to help. Increase to e.g. `270000` for extra headroom on large frame payloads.                                   | `240000` (4 min)                                                          |
+
+### GLM
 
-| Variable                     | Description                       | Required                                 |
-| ---------------------------- | --------------------------------- | ---------------------------------------- |
-| `MOONSHOT_API_KEY`           | Moonshot AI API key for Kimi K2.5 | Optional (if using GLM)                  |
-| `Z_AI_API_KEY`               | Z.AI API key for GLM-4.6V         | Optional (if using Kimi)                 |
-| `VIDEO_MCP_DEFAULT_PROVIDER` | Default backend (`glm`, `kimi`)   | Optional (default: `glm`)                |
-| `VIDEO_MCP_MAX_FRAMES`       | Max frames for summarization      | Optional (default: 20; clamped to 5-100) |
+| Variable                 | Description                                                                                                                                                                                              | Default          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| `GLM_REQUEST_TIMEOUT_MS` | Client-side timeout (ms) for GLM API requests. Z.AI has no hard server-side streaming timeout, so raising this value (e.g. `480000` for 8 minutes) can help when analysing long videos with many frames. | `240000` (4 min) |
 
-### Example Configuration
+### MiMo
+
+| Variable                  | Description                                                                    | Default          |
+| ------------------------- | ------------------------------------------------------------------------------ | ---------------- |
+| `MIMO_REQUEST_TIMEOUT_MS` | Client-side timeout (ms) for MiMo API requests. Default: `240000` (4 minutes). | `240000` (4 min) |
+
+### yt-dlp (Platform Downloads)
+
+| Variable                | Description                                                                                                                                                          | Default |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `YT_DLP_MAX_RESOLUTION` | Max video height (px) for yt-dlp downloads. Free users capped at 720.                                                                                                | `720`   |
+| `YT_DLP_PATH`           | Path to a custom yt-dlp binary. If unset, the server auto-detects common installs first and then uses the bundled binary from `youtube-dl-exec` if it is present.    | —       |
+| `YT_DLP_COOKIES_FILE`   | Path to a Netscape-format cookies file for authenticated downloads (age-restricted, private videos).                                                                 | —       |
+| `YT_DLP_IMPERSONATE`    | Browser to impersonate (e.g. `chrome`, `firefox`). Needed for sites like Udemy that block non-browser user-agents; requires a yt-dlp build with `curl_cffi` support. | —       |
+
+### Pro
+
+| Variable                | Description                                                                                                           | Default |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | ------- |
+| `VIDEO_MCP_LICENSE_KEY` | Pro license key. Unlocks extended frames, platform downloads beyond YouTube, and resolution above 720p. Valid 1 year. | —       |
+
+### Complete Example Config
+
+> **Warning:** This file contains sensitive API keys. **Never commit it to source control.** Make sure `.vscode/mcp.json` is in your `.gitignore`.
 
 ```json
 {
@@ -280,77 +725,215 @@ Ask Copilot Chat:
       "type": "stdio",
       "command": "video-context-mcp",
       "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
         "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
         "MOONSHOT_API_KEY": "your-moonshot-key",
-        "VIDEO_MCP_DEFAULT_PROVIDER": "glm",
-        "VIDEO_MCP_MAX_FRAMES": "20"
+        "MIMO_API_KEY": "your-mimo-key",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key",
+        "VIDEO_MCP_DEFAULT_PROVIDER": "gemini",
+        "AUDIO_MCP_DEFAULT_PROVIDER": "deepgram",
+        "AUDIO_ENHANCE_VIDEO_ANALYSIS": "auto",
+        "VIDEO_MCP_CACHE_TTL_MINUTES": "43200",
+        "VIDEO_MCP_CACHE_MAX_ENTRIES": "100",
+        "VIDEO_MCP_CACHE_MAX_MB": "5120",
+        "VIDEO_MCP_MAX_FRAMES": "50",
+        "YT_DLP_MAX_RESOLUTION": "720",
+        "YT_DLP_PATH": "/usr/local/bin/yt-dlp",
+        "YT_DLP_COOKIES_FILE": "/path/to/cookies.txt",
+        "YT_DLP_IMPERSONATE": "chrome",
+        "AWS_S3_BUCKET": "your-globally-unique-bucket-name",
+        "AWS_ACCESS_KEY_ID": "AKIA...",
+        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
+        "AWS_REGION": "us-east-1",
+        "AWS_S3_RELAY_CLEANUP": "true",
+        "QWEN_BASE_URL": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions",
+        "QWEN_REQUEST_TIMEOUT_MS": "240000",
+        "GLM_REQUEST_TIMEOUT_MS": "240000",
+        "MIMO_REQUEST_TIMEOUT_MS": "240000",
+        "VIDEO_MCP_LICENSE_KEY": "your-license-key"
       }
     }
   }
 }
 ```
 
-## Development
+> Remove or omit any variables you don't need — unset optional vars fall back to their defaults.
+
+<details>
+<summary><strong>Tip: install yt-dlp system-wide for faster startup</strong></summary>
+
+The server first checks `YT_DLP_PATH`, then common system install locations, and then the bundled yt-dlp binary shipped by `youtube-dl-exec`.
+
+If you use platform URLs often, install yt-dlp directly:
 
 ```bash
-# Install dependencies
-npm install
+brew install yt-dlp          # macOS
+winget install yt-dlp        # Windows
+pip install yt-dlp           # cross-platform
+```
 
-# Run in development (auto-restart on changes)
-npm run dev
+Then set `YT_DLP_PATH` to the installed binary. If you installed `video-context-mcp-server` globally and the bundled binary is missing, repair it with:
 
-# Build for production
-npm run build
+```bash
+npm rebuild youtube-dl-exec
+```
 
-# Run type checking
-npm run type-check
+To skip the bundled download at install time:
 
-# Run linter
-npm run lint
+```bash
+YOUTUBE_DL_SKIP_DOWNLOAD=true npm install -g video-context-mcp-server
+```
+
+</details>
+
+<details>
+<summary><strong>Tip: use cookies for age-restricted or private videos</strong></summary>
+
+Some videos require authentication. Export cookies from your browser and point yt-dlp at them.
+
+**Step 1 — Export cookies.** Install [Get cookies.txt LOCALLY](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc) (Chrome/Edge) or [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/) (Firefox). Navigate to the platform while logged in, export in Netscape format, and save the file (e.g. `~/cookies-youtube.txt`).
+
+**Step 2 — Configure.** Add `YT_DLP_COOKIES_FILE` to your MCP config `env` block:
+
+```jsonc
+{
+  "env": {
+    "YT_DLP_COOKIES_FILE": "C:/Users/you/cookies-youtube.txt",
+  },
+}
+```
+
+Restart the MCP server. **Keep your cookies file private** — never commit it to source control.
+
+</details>
+
+---
+
+## Pro
+
+The free tier covers all core functionality. A **pro license** unlocks three power features:
+
+| Feature                                          | Free                | Pro                               |
+| ------------------------------------------------ | ------------------- | --------------------------------- |
+| 🖼️ Extended frame extraction (`summarize_video`) | Capped at 50 frames | Default 100; set `0` for uncapped |
+| 🌐 Platform video downloads                      | YouTube only        | Almost all video platforms        |
+| 📺 Download resolution                           | Capped at 720p      | Uncapped                          |
+
+> Local files and direct `http(s)://` video URLs work for all users — the platform gate only applies to yt-dlp URLs (YouTube, Vimeo, TikTok, Bilibili, etc.).
+
+When a free-tier limit is reached, the tool falls back gracefully with a notice — it **never hard-blocks**.
+
+### Getting a License
+
+License keys are valid for **1 year**.
+
+🚀 LAUNCH PROMO: Get PRO for Free!
+
+For a limited time, you can get a PRO license for free. Just enter 0 in the amount field. If you'd like to support the development, feel free to enter any amount you choose—any contribution is greatly appreciated!
+
+**[Purchase a Pro License on Gumroad](https://jeromekph.gumroad.com/l/video-context-mcp)**
+
+Add `VIDEO_MCP_LICENSE_KEY` to your MCP config `env` block and restart the server:
+
+```json
+{
+  "env": {
+    "VIDEO_MCP_LICENSE_KEY": "<your-license-key>"
+  }
+}
+```
 
-# Run automated tests
-npm run test
+---
 
-# Run tests in watch mode
-npm run test:watch
+## Troubleshooting
 
-# Run tests with coverage
-npm run test:coverage
+- **`video-context-mcp: command not found`** (or `vmcp: command not found`) — Make sure Node.js is installed (`node -v`). Re-run `npm install -g video-context-mcp-server`, or use `npx -y video-context-mcp-server@latest` if global binaries aren't on PATH.
 
-# Format all files
-npm run format
+- **MCP server not appearing** — Restart the client app after config changes. Validate JSON syntax. For Claude Code, verify with `claude mcp list`.
 
-# Check formatting only
-npm run format:check
+- **Missing API key errors** — Set only the keys for providers you use. When a key is missing, tools automatically fall back to the next available provider and include a notice in the response.
 
-# Lint + Type-check + Format + Build
-npm run ltfb
+---
+
+## Development
+
+> This section is for contributors building from source. If you're just using the server, follow the [Quick Start](#quick-start) instead.
+
+### From Source
+
+```bash
+git clone <repo-url> && cd video-mcp
+npm install
+npm run build
 ```
 
-## Architecture
+Use this `.vscode/mcp.json` to run the local build (never commit this file):
 
+```json
+{
+  "servers": {
+    "videoMcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/dist/index.js"],
+      "env": {
+        "GEMINI_API_KEY": "your-gemini-key",
+        "Z_AI_API_KEY": "your-zai-key",
+        "DASHSCOPE_API_KEY": "your-dashscope-key",
+        "MOONSHOT_API_KEY": "your-moonshot-key",
+        "MIMO_API_KEY": "your-mimo-key",
+        "VIDEO_MCP_DEFAULT_PROVIDER": "gemini",
+        "DEEPGRAM_API_KEY": "your-deepgram-key",
+        "ASSEMBLYAI_API_KEY": "your-assemblyai-key",
+        "GROQ_API_KEY": "your-groq-key",
+        "AUDIO_MCP_DEFAULT_PROVIDER": "deepgram",
+        "AUDIO_ENHANCE_VIDEO_ANALYSIS": "auto",
+        "VIDEO_MCP_CACHE_TTL_MINUTES": "43200",
+        "VIDEO_MCP_CACHE_MAX_ENTRIES": "100",
+        "VIDEO_MCP_CACHE_MAX_MB": "5120",
+        "VIDEO_MCP_MAX_FRAMES": "0",
+        "YT_DLP_MAX_RESOLUTION": "720",
+        "YT_DLP_PATH": "/usr/local/bin/yt-dlp",
+        "YT_DLP_COOKIES_FILE": "/path/to/cookies.txt",
+        "YT_DLP_IMPERSONATE": "chrome",
+        "VIDEO_MCP_LICENSE_KEY": "your-license-key"
+      }
+    }
+  }
+}
 ```
-video-mcp/
-├── src/
-│   ├── index.ts              # MCP server entry point
-│   ├── tools/                # MCP tool implementations
-│   ├── services/             # Backend clients (Kimi, GLM, ffmpeg)
-│   └── utils/                # Helpers (temp files, base64)
-├── .vscode/
-│   └── mcp.json              # VS Code MCP configuration
-├── docs/
-│   └── technical/            # Technical documentation
-└── .github/
-    └── copilot-instructions.md  # Copilot AI assistant guidelines
+
+### Debugging in VS Code
+
+Add a `dev` block to `.vscode/mcp.json` for auto-restart and debug integration:
+
+```jsonc
+"dev": {
+  "watch": "src/**/*.ts",
+  "debug": { "type": "node" }
+}
 ```
 
+This causes verbose MCP protocol logs in **Output → MCP: videoMcp** — that's expected. Remove `dev.debug` or the full `dev` block to reduce noise.
+
+---
+
 ## License
 
-MIT
+Proprietary — All Rights Reserved. No part of this software may be copied, modified, distributed, or used without explicit written permission from the author.
 
 ## Credits
 
 - [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) by Anthropic
 - [Kimi K2.5](https://github.com/MoonshotAI/Kimi-K2.5) by Moonshot AI
 - [GLM-4.6V](https://docs.z.ai/guides/vlm/glm-4.6v) by Z.AI
+- [Qwen3.6](https://bailian.console.alibabacloud.com/ap-southeast-1/) by Alibaba Cloud
+- [MiMo-V2 Omni](https://platform.xiaomimimo.com/) by Xiaomi
+- [Deepgram](https://www.deepgram.com/) for audio transcription
+- [AssemblyAI](https://www.assemblyai.com/) for audio transcription
+- [Groq/Whisper](https://console.groq.com/) for audio transcription
+- [Gemini](https://aistudio.google.com/app/apikey) for audio transcription and as a fallback provider
 - [ffmpeg](https://ffmpeg.org/) for video processing