proofcut

Overview Schema Source Related Servers Discussions Admin

import_media

Idempotent

Register media into a project, probing with ffprobe and returning a clip record with clip_id and audio stream count. Handle multi-audio containers by mixing or selecting a stream, and strip chapter lists.

Instructions

Links the media by default rather than copying it. Returns the clip record, including the clip_id every other tool takes, and audio_streams — how many the container holds, since every other audio field on the record describes only the first.

A container with more than one audio stream is refused rather than registered as if the first were the recording: whisper picks a stream of its own and MLT picks again at render, so the others would be missing from the film with every check clean. mix=True sums them into one track (two mics of one performance); audio_stream=k keeps one, numbered from 0 in ffmpeg's own audio ordering. Either writes a derived copy under cache/mixed/ that every later op reads without knowing it.

A chapter list or the data/text track it rides on — a movie rip's own inherited from its parent film — is stripped unconditionally, with no flag to opt out: there is no legitimate choice to offer, unlike the audio-stream one. strip/stripped on the record say so when it happened; duration is corrected from the real video/audio streams either way it was detected.

sheet=True by default: a contact_sheet of the clip's first ten seconds rides along on the returned record — cached frames from thumbnail(), so the clip's own opening (credits, black, a slate) is seen before it is cued to a shot rather than discovered after. Pass sheet=False to skip it. --no-sheet on the CLI.

Input Schema

TableJSON Schema

Name	Required	Description
`mix`	No	Sum a container's audio streams into one track, for two mics on one performance. It writes a derived copy every later op reads without knowing it.
`copy`	No	Copy the media into the project instead of referencing it where it sits. Off by default — a reference costs no disk, and it is also the fallback where symlinks are rejected.
`path`	No	The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing.
`sheet`	No	Draw a contact sheet of the clip's first ten seconds onto the returned record. On by default, because a first look that has to be asked for is one nobody takes.
`source`	Yes	The media file to register. A file argument rather than a project selector, so it is deliberately left unconfined — footage usually lives outside the project.
`clip_id`	No	The id every later tool addresses this clip by. Unset, one is derived from the filename. Keep it short: it becomes part of cache paths, and a stock Windows measures those against 248 characters.
`audio_stream`	No	Keep one of a container's audio streams and drop the rest, numbered from 0 in ffmpeg's own audio ordering — not the container's absolute stream index, which is a different number once there is video.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedv0.25.0Sep 16, 2026

removedInput schema / properties / audio_stream / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / audio_stream / description

Added value: +"Keep one of a container's audio streams and drop the rest, numbered from 0 in ffmpeg's own audio ordering — not the container's absolute stream index, which is a different number once there is video."

removedInput schema / properties / audio_stream / title
```
Removed value: -"Audio Stream"
```
addedInput schema / properties / audio_stream / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

removedInput schema / properties / clip_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / clip_id / description

Added value: +"The id every later tool addresses this clip by. Unset, one is derived from the filename. Keep it short: it becomes part of cache paths, and a stock Windows measures those against 248 characters."

removedInput schema / properties / clip_id / title
```
Removed value: -"Clip Id"
```
addedInput schema / properties / clip_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedInput schema / properties / copy / description

Added value: +"Copy the media into the project instead of referencing it where it sits. Off by default — a reference costs no disk, and it is also the fallback where symlinks are rejected."

removedInput schema / properties / copy / title
```
Removed value: -"Copy"
```

addedInput schema / properties / mix / description

Added value: +"Sum a container's audio streams into one track, for two mics on one performance. It writes a derived copy every later op reads without knowing it."

removedInput schema / properties / mix / title
```
Removed value: -"Mix"
```

removedInput schema / properties / path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / path / description

Added value: +"The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing."

removedInput schema / properties / path / title
```
Removed value: -"Path"
```

addedInput schema / properties / path / type

Added value: +[
+  "string",
+  "null"
+]

addedInput schema / properties / sheet / description

Added value: +"Draw a contact sheet of the clip's first ten seconds onto the returned record. On by default, because a first look that has to be asked for is one nobody takes."

removedInput schema / properties / sheet / title
```
Removed value: -"Sheet"
```

addedInput schema / properties / source / description

Added value: +"The media file to register. A file argument rather than a project selector, so it is deliberately left unconfined — footage usually lives outside the project."

removedInput schema / properties / source / title
```
Removed value: -"Source"
```
removedInput schema / title
```
Removed value: -"import_mediaArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations indicate idempotentHint=true, but description explains that it refuses multi-audio-stream containers unless mix or audio_stream is set, which is a critical behavioral detail. It also discloses that it strips chapter lists and data/text tracks unconditionally, with no opt-out flag, which is a significant side effect beyond the schema. While readOnlyHint=false and destructiveHint=false are consistent, the description elaborates on the derived copy creation and the contact sheet behavior, adding valuable context. It does not contradict annotations, and it goes beyond them in explaining refusal conditions and side effects.

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

Conciseness4/5

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

The description is long but well-structured, with each paragraph covering a distinct topic: basic registration, audio stream handling, stripping, and contact sheet. It front-loads the core purpose and clip_id return, which is the most frequently needed information. However, some redundancy exists with the schema descriptions (e.g., mix, sheet), and it could be slightly more concise without losing essential context. It is not verbose to the point of obscuring key points.

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

Completeness5/5

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

Given the tool's complexity (7 parameters, multiple edge cases like multi-audio streams and stripping), the description is remarkably complete. It explains the rationale behind default behaviors, refusal conditions, and derived copies. The output schema exists, so it doesn't need to describe return values, but it does mention the clip_id and contact_sheet. The description covers all necessary operational details an agent would need to correctly invoke this tool, including caveats about file paths and cache limits.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds some value by explaining the default linking vs copying behavior and the audio stream handling rationale, which goes beyond the schema. However, it doesn't significantly extend the meaning of parameters like 'path' or 'source' that are already well-described in the schema. It does clarify 'mix' and 'audio_stream' usage in context, but overall it's a moderate addition over the schema.

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

Purpose5/5

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

The description clearly states the tool's verb ('Register'), resource ('a media file with the project'), and method ('probing it with ffprobe'). It distinguishes itself from sibling tools like 'import_edit' and 'list_media' by specifying it creates a clip record and returns a clip_id. The purpose is unambiguous and specific, not a tautology.

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?

The description explicitly states when to use this tool versus alternatives: it mentions 'every other tool takes' the clip_id, and it explains the default linking behavior. It also provides clear conditions for using optional parameters like 'mix=True' for multiple audio streams and 'audio_stream=k' for keeping one. It implies this is the entry point for adding media, unlike 'list_media' which likely just lists. There is explicit guidance on when to use the tool and when not to (e.g., refusing multi-audio-stream containers unless mix or audio_stream is specified).

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

Deploy Server