Skip to main content
Glama
Sign In

ChatCut

by io.chatcut
OverviewDiscussionsAdmin

import_media

Import local media. Use action="from_editor" with explicit projectId and timelineId when an authenticated browser on the helper machine is connected. Omit browserProfileId for automatic selection; never ask the user to choose. The visible page and timeline do not change. Serve the file with the plugin's serve-local-media.mjs and pass its assetId, url, filename and sizeBytes. Reuse the same assetId on retries. This imports to the library through the editor pipeline without page scripting or shell upload credentials, using the same large-video upload policy as the editor file picker. Large original video uploads may be deferred until cloud bytes are needed; check browse_assets before waiting for upload. Success means local bytes are persisted and the asset is registered in the editor; cloud upload, server sync and transcription may still be pending. Keep the authenticated browser open. Never use loopback URLs from a remote sandbox.

For multiple loopback files, make ONE call with action="from_editor" and files:[{assetId,url,filename,sizeBytes}, ...] (1–16 entries). Each file may use its own helper address. Do not combine files with the top-level single-file fields. The batch admits at most four imports at a time, matching the normal editor import limit and returns ordered results with each assetId, filename, ok and status/error, plus succeeded/failed counts. Partial success is preserved; retry only failed entries with their SAME assetIds. The single-file top-level form remains supported. Relinking also accepts files, using existing assetIds with action="relink_from_editor".

When no same-machine editor is available or browser local-network access is blocked, use action="create_session" for the upload-helper fallback.

For reference-only imports, use action="create_session" with mediaPoolVisibility:"hidden". This applies to every file uploaded with that session: agents can discover and inspect them, but users cannot see them in their media library. Omit it for user uploads, source footage, and generated deliverables. This flag is not supported for from_editor or relink_from_editor.

To restore missing local bytes for an existing asset, use action="relink_from_editor" with the EXISTING asset's id and the helper's url, filename and sizeBytes. Pass the id exactly as browse_assets or inspect_asset printed it: the compact 10-hex form is accepted here and resolved against this project, as is the full UUID. Do not mint a new id for a relink. This preserves timeline references and uses the editor's normal relink pipeline. Supply the corresponding original media, not a different edit or replacement clip. Success returns status="locally_relinked" after local persistence; upload and transcription may still be pending. Relink requires a compatible authenticated browser and does not create another asset. The editor fetches the helper URL from the browser showing it, so an agent in-app browser that blocks loopback requests (ERR_BLOCKED_BY_CLIENT) fails every attempt: do not retry, and tell the user to relink in their normal browser or in ChatCut Desktop, since relink has no upload-based fallback.

For the upload fallback, call this once with action="create_session", then run the plugin helper with at most four files. For more files, create a fresh session for each batch of four. The helper uploads frontend-aligned bytes straight to storage, keeping them off the ChatCut backend, and prints registered assetIds. Registered assetIds are usable for timeline placement, rough cuts, organization, and transcript-driven planning. For most editing tasks, wait only for target:"transcription" before transcript/caption/script-aware work. Do not wait for target:"upload" preemptively: an open editor can inspect local/blob frames, and Desktop-local preview and export do not require cloud upload. Check target:"upload" only after the next operation explicitly says it needs a cloud-readable remoteUrl, such as request_asset_download or a cloud-only render path. If the upload helper fails, give the user the returned userUploadFallback.url so they can upload into this project in their browser. Do not manually construct metadata.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "import_media"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNo
filesNoBatch loopback import/relink. Use instead of the top-level assetId, url, filename and sizeBytes.
actionYes
assetIdNoFor action="from_editor", a fresh UUID you mint and reuse on retry. For action="relink_from_editor", the existing asset's id from browse_assets, full or 10-hex.
filenameNo
projectIdNoFull project UUID. Required for external browser work; internal agents may omit. Execution/explicit-timeline calls never change later calls' target.
sizeBytesNo
timelineIdNoFull timeline UUID, not a prefix. Required for browser work, even unplaced assets. Get it from read_project or manage_timelines action="list". Never switches visible timeline.
idempotencyKeyNoStable key for this browser execution. Reuse only with identical scope and parameters after a lost acknowledgement; applies only to this call.
browserProfileIdNoOptional browser profile override. Omit to select automatically; do not ask the user to choose.
mediaPoolVisibilityNocreate_session only: reference-only assets hidden from the user's media library, still available to agents by ID. Applies to the entire session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly=false, destructive=false), the description discloses that the visible page and timeline do not change, that local bytes persist but cloud upload/transcription may remain pending, that large video uploads may be deferred, and that relinking preserves timeline references. It also explains batch limits, partial success, helper/fallback behavior, and the fact that loopback URLs must not be used from a remote sandbox. These are substantive behavioral traits an agent could not infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a dense wall of prose spanning many paragraphs, with repeated instructions about retrying with the same assetId, not changing the visible timeline, and success semantics. The opening is front-loaded and the content is relevant for an 11-parameter, three-action tool, but the repetition and lack of structural grouping make it harder to scan than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-action tool with no output schema, the description explains batch return fields (assetId, filename, ok, status/error, succeeded/failed counts), key status values such as 'locally_relinked', and asynchronous follow-up states like pending upload or transcription. It does not fully specify the create_session return shape or every possible result, but it is substantially complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 64%, so several top-level parameters (url, filename, sizeBytes) rely on the description for meaning, and the description supplies it in the from_editor/relink context. It adds significant value beyond the schema for files (1–16 entries, do not combine with top-level single-file fields, at most four concurrent imports), assetId (fresh UUID for import vs existing id for relink, 10-hex accepted), and mediaPoolVisibility (hidden applies to every file in the session). Some details, such as sizeBytes expectations, remain only in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Import local media' states a specific verb and resource, and the description immediately enumerates its three actions (from_editor, create_session, relink_from_editor), so an agent can tell what it does. It also names relevant siblings such as browse_assets and request_asset_download in context. The name 'import_media' is slightly imprecise for the relink action, but the description clarifies this.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance for every mode: from_editor when an authenticated browser is connected, create_session when no same-machine editor or local-network access is blocked, relink for restoring missing bytes, and mediaPoolVisibility hidden for reference-only imports. It also states exclusions and failure handling, including not retrying ERR_BLOCKED_BY_CLIENT and not waiting for upload unless a cloud-readable URL is explicitly needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ChatCut toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources