video-context-mcp-server 0.52.1-beta → 0.52.3-beta

package/README.md

@@ -353,53 +353,205 @@ Set `VIDEO_MCP_DEFAULT_PROVIDER=gemini`, `qwen`, `kimi`, or `mimo` to change the
 
 **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 it works**: GLM, Qwen, and MiMo require the server to serve `Content-Length` and `Content-Type` headers alongside the video. AWS S3 provides these automatically.
+#### Why S3 works
 
-**One-time setup**
+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
-# 1. Create a bucket
-aws s3 mb s3://my-video-analysis
+aws configure
+```
+
+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:
 
-# 2. Add AWS_S3_BUCKET to your .vscode/mcp.json env block
+```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": "video-context-mcp",
+      "env": {
+        "AWS_S3_BUCKET": "your-globally-unique-bucket-name",
+        "GEMINI_API_KEY": "your-gemini-key"
+      }
+    }
+  }
+}
 ```
 
-AWS credentials are resolved automatically in this order:
+---
+
+#### AWS Credential Resolution
+
+The server resolves AWS credentials in this order — you only need to configure one:
 
-1. **Environment variables** — add these to your `mcp.json` env block (no AWS CLI required):
+1. **Environment variables** — add directly to your MCP `env` block (no AWS CLI needed):
    ```jsonc
-   // .vscode/mcp.json — env section
-   {
-     "AWS_S3_BUCKET": "my-video-analysis",
-     "AWS_ACCESS_KEY_ID": "AKIA...",
-     "AWS_SECRET_ACCESS_KEY": "your-secret-key",
-     "AWS_REGION": "us-east-1",
-   }
+   "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 you have the AWS CLI configured, credentials are picked up automatically; only `AWS_S3_BUCKET` is needed:
+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
-   // .vscode/mcp.json — env section
-   {
-     "AWS_S3_BUCKET": "my-video-analysis",
-   }
+   "AWS_S3_BUCKET": "your-globally-unique-bucket-name"
    ```
 3. **IAM instance role / ECS task role** — for AWS-hosted environments.
 
-That's it. Every time you analyze a local video (or a YouTube/Bilibili download) with GLM or Qwen, the server uploads it to S3, uses the presigned URL, and leaves the object in the bucket for reuse.
+---
+
+#### How it works at runtime
+
+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/<hash>/<filename>`.
+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):
 
-**Cleanup:** Relayed S3 objects are deleted automatically when the MCP server session ends and orphaned objects are swept at startup. Set `AWS_S3_RELAY_CLEANUP=false` to keep objects in the bucket for reuse across sessions.
+```jsonc
+"AWS_S3_RELAY_CLEANUP": "false"
+```
+
+**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.
+
+---
 
-**Cost**: AWS S3 free tier covers 5 GB storage + 20K GET requests/month for 12 months. After the free tier, storage is roughly $0.023/GB/month.
+#### Manual presigned URLs (alternative)
 
-**Still want direct URLs?** Pass a presigned URL manually:
+You can also pass a presigned URL directly to any tool without configuring the relay:
 
 ```bash
-aws s3 cp my-video.mp4 s3://my-video-analysis/my-video.mp4
-aws s3 presign s3://my-video-analysis/my-video.mp4 --expires-in 3600
-# returns: https://my-video-analysis.s3.amazonaws.com/my-video.mp4?X-Amz-...
+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-...
 ```
 
-Then pass the URL directly to `analyze_video` or `summarize_video`.
+Then pass the URL directly to `analyze_video`, `summarize_video`, or any other tool.
 
 </details>
 
@@ -592,7 +744,7 @@ vmcp cache clear:all --yes   # skip confirmation
         "YT_DLP_PATH": "/usr/local/bin/yt-dlp",
         "YT_DLP_COOKIES_FILE": "/path/to/cookies.txt",
         "YT_DLP_IMPERSONATE": "chrome",
-        "AWS_S3_BUCKET": "my-video-analysis",
+        "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",

package/dist/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.52.1-beta";
+export declare const VERSION = "0.52.3-beta";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/sync-version.ts — do not edit
-export const VERSION = '0.52.1-beta';
+export const VERSION = '0.52.3-beta';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "video-context-mcp-server",
-  "version": "0.52.1-beta",
+  "version": "0.52.3-beta",
   "description": "A Model Context Protocol server that gives GitHub Copilot the ability to understand and analyze video content",
   "type": "module",
   "main": "dist/index.js",