Name: 视频平台MCP服务器
Author: BlendVision

使用说明

BlendVision MCP Server

Model Context Protocol (MCP) server for BlendVision One API. This server enables AI assistants to interact with BlendVision's video platform services including VOD, live streaming, chatrooms, and analytics.

Features

Supported API Categories

Video On Demand (VOD): Create, manage, and query video content
Live Streaming: Manage live channels and streaming sessions
Library & File Management: Upload, update, download, and manage files in BlendVision library
Clips & Auto-tagging: Create and manage video clips with AI-powered auto-tagging
Meeting: Create and manage video meetings
Chatroom: Create and manage real-time chat experiences
Account & Organization: Access account information and organization details
Playback: Generate playback tokens and manage access codes
Analytics: Retrieve analytics, CDN usage, and streaming metrics

Available Tools

VOD Tools

list_videos - List all videos with filtering options
get_video - Get video details by ID
create_video - Create a new video (needs a profile_set_id from list_profile_sets)
update_video - Update video metadata
delete_video - Delete a video
update_vod_subtitles - Update subtitles for a VOD video
create_vod_download - Trigger a VOD rendition download as MP4
get_vod_download - Get status of a VOD download job
list_vod_downloads - List all download jobs for a VOD

API Tools

search_api - Find endpoints by keyword (one line per match)
describe_api - Show one endpoint's parameters and schema
call_api - Call an endpoint directly

Reaching endpoints that have no dedicated tool

The REST API has a few hundred endpoints. A tool per endpoint would put the whole catalogue in tools/list, which is sent on every conversation — around 36k tokens of tool definitions before any work happens. These three tools carry the long tail instead: a search costs ~200 tokens, and one endpoint's schema ~2k, paid only when actually used.

search_api   { "query": "library upload" }
describe_api { "path": "/bv/cms/v1/library/files:upload", "method": "POST" }
call_api     { "method": "GET", "path": "/bv/cms/v1/vods/{id}", "pathParams": { "id": "abc123" } }

call_api validates the method and path against the index first, so a misremembered endpoint fails with a searchable message instead of an opaque 404.

Endpoints under /cxm/ are read-only unless the server sets BLENDVISION_ALLOW_CXM_WRITES=1; a mutating call is refused before any request is made. /bv/ is deliberately unguarded — it is a published contract whose own authorization callers already rely on. CXM is guarded because the platform cannot express read-only for it: its RBAC permissions are one undifferentiated group, and no read-only role is granted them at all, so a token that can read CXM may also attempt every CXM write.

Read and write are told apart by each operation's declared action, not by the HTTP method — 28 CXM operations are POST with ACTION_READ (batch-get, report generation, aggregation) and a method-based rule would refuse all of them. That requires an index built with --actions; without it, anything other than GET counts as mutating. Response schemas are summarised to their field names unless you pass includeResponses: true — expanded, a single VOD endpoint runs to 60k characters.

Prefer a dedicated tool where one exists. They encode work these cannot: upload_file drives a three-step upload and PUTs bytes to presigned URLs, which no generic call can express.

Choosing which endpoints are reachable

The server searches a compiled index, not the live API, and the repo ships two:

Index	Built from	Operations
`data/api-index.json`	the public (`BV_EXTERNAL`) spec	324, reads and writes
`data/api-index-cxm.json`	`scripts/cxm-storefront-reads.txt`	36, three of them writes

Both load by default. The CXM one is a curated list because CXM is not part of the published contract — all 342 of its storefront operations are BV_INTERNAL, so the endpoints an agent may reach are named one by one in scripts/cxm-storefront-reads.txt (courses, content, spaces, assigned learning, and the asker's own learning record) rather than compiled wholesale. One entry is not CXM's at all: the org-unit listing, which is BV_INTERNAL too and so in neither index by default, and without which a task can only be assigned by naming every person in a department one by one.

Three entries are writes — POST …/programs, POST …/tasks and PUT …/tasks/{task.id}, so an agent can create a course, assign it, and change the assignment afterwards — and being listed is not permission. call_api refuses a mutating /cxm/ call unless that exact "METHOD path" appears in BLENDVISION_CXM_WRITES (a comma-separated list; * for all of them, and the older boolean BLENDVISION_ALLOW_CXM_WRITES still means *). A deployment that sets nothing is read-only even with the write indexed.

Per operation rather than a single switch, because "let the agent create a course" and "let the agent delete every course" are different decisions — one is undoable by hand and the other is not. Note what stays out of the index entirely: PUT/DELETE on a program, permission updates, deleting or terminating a task, and every licensed-content write.

The task update is a full replace — contents and assignee sources are rewritten from the body, and a manual end is cleared — so a caller must read the whole task and send it back with only the asked-for change. It is indexed for agent-server's propose_task_update, which builds that body in code; a deployment with no such caller should leave it out of BLENDVISION_CXM_WRITES.

Set BLENDVISION_API_INDEX to a comma-separated list to replace both — with the /bv file alone to drop CXM entirely, or with your own slice:

npm run build:api-index -- path/to/spec.swagger.yaml \
  --actions path/to/proto-dir \
  --include @my-endpoints.txt \
  -o /etc/bv/api-index.json
BLENDVISION_API_INDEX=/etc/bv/api-index.json node build/connector.js

--actions reads each operation's declared action from the .proto sources; the OpenAPI generator drops it. Pass it whenever the index covers /cxm/, or the write guard falls back to judging by HTTP method. --include takes a regex matched against "METHOD path", or @file naming the operations one per line; definitions is pruned to what the kept operations reference, so a slice of a wide spec stays small (the CXM slice is 171KB of a 5MB spec).

To check a deployment end to end — discovery, a real read, and that writes are refused — against a live environment:

BLENDVISION_API_TOKEN=... BLENDVISION_ORG_ID=... \
BLENDVISION_BASE_URL=https://api.one-dev.blendvision.io \
node scripts/smoke-test-cxm.mjs

It never writes: it asserts that mutating calls are refused, and refuses to run at all with BLENDVISION_ALLOW_CXM_WRITES set, since the flag would invalidate what it is checking. CXM checks are skipped, not failed, when the index has no CXM operations.

Because the endpoint list is data rather than code, a deployment can reach a wider surface than the published package describes — useful for APIs that are not part of the public contract. Note that this is only about discovery: what a token may actually call is decided by the API's own authorization, not here.

Encoding Configuration Tools

list_profile_sets - List encoding profile sets (where a profile_set_id comes from)
get_profile_set - Get one profile set and its renditions

Live Streaming Tools

list_live_channels - List all live channels
get_live_channel - Get channel details by ID
create_live_channel - Create a new live channel
update_live_channel - Update channel settings
delete_live_channel - Delete a channel
start_live - Start live streaming
stop_live - Stop live streaming
cancel_live_channel - Cancel and archive a live stream
archive_live_channel - Archive a live stream permanently

Library & File Tools

upload_file - Upload a file (whole upload in one call), or just open a session and get presigned URLs
complete_file_upload - Complete file upload session after uploading parts
cancel_file_upload - Cancel an in-progress file upload session
get_file - Get file details by ID
update_file - Update file details (name, metadata, attributes)
delete_file - Delete a file from library
download_file - Get a download link for a file

Uploading

An upload is three steps: open a session, PUT the bytes straight to storage, then complete with each part's ETag. Pass filePath or sourceUrl and upload_file runs all three, which is the only form an agent can drive — it has no way to PUT binary itself:

// local file (stdio server / CLI)
{ "filePath": "/Users/me/clips/demo.mp4" }

// from a URL (also works on the remote connector; the URL must answer HEAD with Content-Length)
{ "sourceUrl": "https://example.com/demo.mp4", "name": "demo.mp4" }

type is inferred from the extension (.mp4/.m4v/.mxf infer as video — pass type: "FILE_TYPE_AUDIO" if that is what you meant), and extension and size limits are checked before the first request. If a part fails, the session is cancelled rather than left dangling. The returned file.id is the library file id — what create_video takes as source.library.video.id.

Passing neither filePath nor sourceUrl keeps the original behaviour: the session is opened and the presigned URLs come back, and you PUT the parts and call complete_file_upload yourself.

Requirements: the API token's account needs a role with library write access (owner / admin / video admin), the organization needs one of the BV_GENERAL, CONTENT or ORG_USER_PERSONAL features, and x-bv-org-id must be set (via BLENDVISION_ORG_ID or the orgId parameter). filePath is rejected by the remote connector, which cannot read your filesystem.

From uploaded file to playable VOD

An uploaded file sits in the library until it is encoded. Two more calls get it playable:

// 1. pick an encoding profile set (preset ones are BlendVision's built-ins)
list_profile_sets { "preset": "PRESET_ONLY" }

// 2. create the VOD from the library file
create_video {
  "name": "demo.mp4",
  "profile_set_id": "<id from step 1>",
  "source": { "type": "SOURCE_TYPE_LIBRARY", "library": { "video": { "id": "<file.id from upload_file>" } } }
}

queue, security and schedule are required by the API but default here to the standard queue, public playback and no schedule, so a plain VOD needs nothing more than the three fields above. Anything you pass explicitly wins. Encoding is asynchronous — poll get_video until status reaches VOD_STATUS_READY.

Clips & Auto-tagging Tools

list_clips - List video clips from a specific source
get_clip - Get clip details by ID
create_clip - Create a new video clip
update_clip - Update clip metadata
delete_clip - Delete a video clip
get_auto_tagging - Get auto-tagging results for a video source
create_auto_tagging - Create auto-tagging for a VOD video

Meeting Tools

create_meeting - Create a new meeting with schedule configuration
get_meeting - Get meeting details by ID
get_meeting_session_info - Get meeting session info and participant tokens
archive_meeting - Archive a meeting

Chatroom Tools

list_chatrooms - List all chatrooms
get_chatroom - Get chatroom details
create_chatroom - Create a new chatroom
send_chatroom_message - Send a message to a chatroom

Account & Organization Tools

get_account - Get current account information
list_organizations - List accessible organizations
list_hierarchical_sub_organizations - List hierarchical sub-organizations

Playback Tools

generate_playback_token - Generate tokens for content access
list_playback_codes - List playback codes for a resource

Analytics Tools

get_analytics - Retrieve analytics reports
get_cdn_usage_report - Get CDN usage report for bandwidth and traffic
query_default_usage_charts - Query default usage charts with time range
get_user_access_chart - Get user access analytics chart
query_usage_summary - Query usage summary analytics

Quick Start

Step 1: Install

# Using npx (no installation required)
npx @blendvision/mcp-server

# Or install globally
npm install -g @blendvision/mcp-server

Step 2: Configure Claude Desktop

Edit your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json):

Using npx (recommended - always uses latest version):

{
  "mcpServers": {
    "blendvision": {
      "command": "npx",
      "args": ["-y", "@blendvision/mcp-server"],
      "env": {
        "BLENDVISION_API_TOKEN": "your_token_here"
      }
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "blendvision": {
      "command": "blendvision-mcp",
      "env": {
        "BLENDVISION_API_TOKEN": "your_token_here"
      }
    }
  }
}

Step 3: Configure Claude Code

Add manually via command line:

claude mcp add --transport stdio --scope user blendvision \
  -- npx -y @blendvision/mcp-server

Then set your API token as an environment variable:

export BLENDVISION_API_TOKEN="your_token_here"

Example Queries

Once connected to an MCP client like Claude, you can ask:

"List all my videos"
"Create a new live channel called 'Product Launch'"
"Generate a playback token for video ID abc123"
"Show me analytics for the last 7 days"
"Start the live stream on channel xyz789"

Running it as a shared server

Beyond the stdio server each user runs locally, the same tools are served over HTTP by build/connector.js, which is what the Docker image runs. It is stateless and carries no credential — every request brings the caller's own API token in Authorization: Bearer — so it scales as plain replicas and needs no Secret:

cd deploy/k8s && kubectl apply -k .

See deploy/k8s/README.md for images, ingress and scaling. Plain Docker works the same way — docker build -t blendvision-mcp . && docker run -p 3000:3000 blendvision-mcp — and answers GET /health.

API Reference

This MCP server wraps the BlendVision One API. For detailed API documentation, visit: https://developers.blendvision.com/docs/category/bv-one-api

License

MIT

Contact Us

To obtain your API Token or if you have any questions, please reach out to us:

Email: support@blendvision.com
Website: https://www.blendvision.com
API Documentation: https://developers.blendvision.com