Annotate
media_annotateWrites notes, comments and marked areas into local PDFs, video, audio and images so annotations persist across sessions and stay visible to humans. Creates real PDF objects plus sidecar JSON/VTT files.
Instructions
Write annotations (notes, comments, sticky notes, marked areas) into a local media file so they survive across sessions and are visible to humans in the file itself: real PDF annotation objects for a PDF, a sidecar VTT for video/audio, and a sidecar JSON for every supported media type. (写入批注 / 注释 / 评论 / 标注：PDF 原地写真正的批注对象；视频、音频写同名 .mmgrep.annotation.vtt；所有类型都写 .mmgrep.annotation.json 侧车。 中文触发词：批注、注释、评论、标注、annotate、comment、note。)
The sidecar ".mmgrep.annotation.json" is the single source of truth. The first write (no sidecar yet) imports every note-like annotation of a PDF — Text, FreeText, Square, Circle, Line, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret and Ink, in page order — as n1…nN, including its raw geometry and original author, then applies this call. Link annotations, form widgets and popups are never imported or touched. Entries are anchored per media type:
PDF: page (1-based PHYSICAL page) + type ("text" = sticky note, "square" = rectangle area; "square" also needs rect {x,y,width,height} as fractions 0..1 of the page). Other annotation types cannot be created in this version, but imported ones are kept verbatim (including raw geometry) and can be updated (note) or removed.
video/audio: start (seconds, < duration) and optional end (default start + 5 s, clipped to the end of the media). No page, no rect, no type.
image: rect only (fractions of the image); no page, start/end or type.
every entry: note (plain text, 1..4000 characters, newlines allowed) and, for PDF, type.
Ids are n1, n2, …; new ids are max+1 and are never reused by this call; update keeps the id. One call can mix add / remove / update; they are applied remove → update → add, all-or-nothing: if anything is invalid, nothing is written and every problem is listed at once (unknown id, bad field, page/time out of range, duplicate ids, malformed entry, …).
The author is resolved once per call: the "author" argument, else the MCP client's name, else "MultiMediaGrep". The model name is never used. Imported annotations keep their original author; update never changes it.
WARNING — this tool modifies files:
A PDF is modified IN PLACE: annotation objects are written into the PDF file itself, no copy is made (the page content is not rewritten). Video and audio files are never modified — only the VTT is written.
Files are written NEXT TO the source: a .mmgrep. sidecar for every media type, plus *.mmgrep.annotation.vtt for video/audio. They are not written into the cache directory.
When a sidecar already exists, external edits to the file's own annotations are OVERWRITTEN on the next write. To change an annotation, use update; the sidecar wins over the file.
Protect your originals with git (or a backup) before calling this tool.
The result lists every written annotation in the same shape the read side uses ("n1 (p.12): note", "n1 (00:12:34–00:12:39): note"), plus the sidecar path, the embed target, and every check result. (批注 / 注释 / 评论 / 标注 / annotate / comment / note)
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": {
"path": "<path>"
},
"name": "media_annotate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Annotations to add. Each gets a new id (max+1); do not pass "id". (新增批注：note + type/page（PDF）或 start/end（视频/音频）或 rect（图片）) | |
| path | Yes | Absolute path to a LOCAL file: video, audio recording, or document. URLs and relative paths are rejected — this server never downloads anything. (本地文件绝对路径) | |
| author | No | Who is writing these annotations (stored in the sidecar and, for PDF, in the annotation). Defaults to the MCP client's name, then "MultiMediaGrep". Imported annotations keep their original author; update never changes it. (批注作者) | |
| remove | No | Annotation ids to remove, e.g. ["n2"]. Unknown or duplicate ids are errors and nothing is written. (删除批注：n1、n2 …) | |
| update | No | Annotations to update: pass "id" plus at least one of note / type / page / rect / start / end. The id and the author never change. (更新批注：保留 id，只改内容 / 位置) |