@morshoto/framekit 0.1.5 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/framekit.mjs +2 -1
- package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
- package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
- package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
- package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
- package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
- package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
- package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
- package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
- package/dist-package/apps/mcp-server/src/main.js +73 -17
- package/dist-package/apps/mcp-server/src/routing.js +242 -39
- package/dist-package/apps/mcp-server/src/server.js +677 -89
- package/dist-package/apps/mcp-server/src/version.js +109 -1
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
- package/dist-package/packages/runtime/src/application/project-service.js +46 -7
- package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
- package/dist-package/packages/runtime/src/capabilities.js +62 -9
- package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
- package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
- package/dist-package/packages/runtime/src/domain/context.js +14 -1
- package/dist-package/packages/runtime/src/domain/editing.js +27 -1
- package/dist-package/packages/runtime/src/domain/index.js +1 -0
- package/dist-package/packages/runtime/src/domain/skills.js +2 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
- package/dist-package/packages/runtime/src/editing/intent.js +178 -2
- package/dist-package/packages/runtime/src/index.js +1 -0
- package/dist-package/packages/runtime/src/runtime.js +2 -2
- package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
- package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
- package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
- package/dist-package/packages/runtime/src/verification/verification.js +81 -4
- package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
- package/package.json +12 -2
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
2
|
import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
3
|
+
import { resolve as resolvePath } from "node:path";
|
|
3
4
|
import { z } from "zod";
|
|
4
|
-
import { createCapabilityPreflight, resolveEditingIntent, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
5
|
+
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
|
|
6
|
+
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
7
|
+
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
8
|
+
import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
|
|
7
9
|
const revisionValueSchema = z.object({
|
|
8
10
|
id: z.string(),
|
|
9
11
|
sequence: z.number().int().nonnegative(),
|
|
@@ -62,6 +64,39 @@ const markerSchema = z.object({
|
|
|
62
64
|
duration: z.number().nonnegative(),
|
|
63
65
|
name: z.string().min(1),
|
|
64
66
|
});
|
|
67
|
+
const maskBoundsSchema = z.object({
|
|
68
|
+
x: z.number().finite().min(0).max(1),
|
|
69
|
+
y: z.number().finite().min(0).max(1),
|
|
70
|
+
width: z.number().finite().positive().max(1),
|
|
71
|
+
height: z.number().finite().positive().max(1),
|
|
72
|
+
}).strict().superRefine((bounds, context) => {
|
|
73
|
+
if (bounds.x + bounds.width > 1) {
|
|
74
|
+
context.addIssue({ code: z.ZodIssueCode.custom, path: ["width"], message: "x plus width must fit within the frame" });
|
|
75
|
+
}
|
|
76
|
+
if (bounds.y + bounds.height > 1) {
|
|
77
|
+
context.addIssue({ code: z.ZodIssueCode.custom, path: ["height"], message: "y plus height must fit within the frame" });
|
|
78
|
+
}
|
|
79
|
+
});
|
|
80
|
+
const maskSchema = z.discriminatedUnion("mode", [
|
|
81
|
+
z.object({
|
|
82
|
+
mode: z.literal("rectangle"),
|
|
83
|
+
bounds: maskBoundsSchema,
|
|
84
|
+
inverted: z.boolean().optional(),
|
|
85
|
+
}).strict(),
|
|
86
|
+
z.object({
|
|
87
|
+
mode: z.literal("supplied-alpha"),
|
|
88
|
+
alphaMediaId: z.string().trim().min(1),
|
|
89
|
+
bounds: maskBoundsSchema.optional(),
|
|
90
|
+
inverted: z.boolean().optional(),
|
|
91
|
+
}).strict(),
|
|
92
|
+
z.object({
|
|
93
|
+
mode: z.literal("person-cutout"),
|
|
94
|
+
}).strict(),
|
|
95
|
+
]);
|
|
96
|
+
const nativeMaskSchema = z.object({
|
|
97
|
+
mode: z.literal("rectangle"),
|
|
98
|
+
bounds: maskBoundsSchema,
|
|
99
|
+
}).strict();
|
|
65
100
|
const renameClipSchema = z.object({ type: z.literal("rename-clip"), clipId: z.string().min(1), name: z.string().min(1), baseRevision: revisionSchema });
|
|
66
101
|
const trimClipSchema = z.object({
|
|
67
102
|
type: z.literal("trim-clip"),
|
|
@@ -265,6 +300,10 @@ const artifactPublishInputSchema = z.object({
|
|
|
265
300
|
transactionId: z.string().min(1),
|
|
266
301
|
confirm: z.boolean(),
|
|
267
302
|
}).strict();
|
|
303
|
+
const artifactTransactionInputSchema = z.object({
|
|
304
|
+
artifactPath: z.string().trim().min(1),
|
|
305
|
+
transactionId: z.string().min(1),
|
|
306
|
+
}).strict();
|
|
268
307
|
const workflowOperationSchema = z.discriminatedUnion("type", [
|
|
269
308
|
renameClipSchema,
|
|
270
309
|
trimClipSchema,
|
|
@@ -290,6 +329,28 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
|
|
|
290
329
|
duration: z.number().positive(),
|
|
291
330
|
targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
|
|
292
331
|
}),
|
|
332
|
+
z.object({
|
|
333
|
+
type: z.literal("timeline.picture-in-picture.add"),
|
|
334
|
+
occurrenceId: z.string().min(1),
|
|
335
|
+
mediaId: z.string().min(1),
|
|
336
|
+
attachedTo: z.string().min(1),
|
|
337
|
+
start: z.number().finite().nonnegative(),
|
|
338
|
+
duration: z.number().finite().positive(),
|
|
339
|
+
targetLane: z.number().int().refine((lane) => lane !== 0, "PIP requires a connected non-primary lane"),
|
|
340
|
+
position: z.object({ x: z.number().finite(), y: z.number().finite() }),
|
|
341
|
+
scale: z.number().finite().positive(),
|
|
342
|
+
crop: z.object({
|
|
343
|
+
top: z.number().finite().min(0).lt(1),
|
|
344
|
+
right: z.number().finite().min(0).lt(1),
|
|
345
|
+
bottom: z.number().finite().min(0).lt(1),
|
|
346
|
+
left: z.number().finite().min(0).lt(1),
|
|
347
|
+
}).optional(),
|
|
348
|
+
frame: z.object({
|
|
349
|
+
style: z.literal("solid"),
|
|
350
|
+
color: z.string().regex(/^#[0-9a-f]{6}$/i),
|
|
351
|
+
width: z.number().finite().nonnegative(),
|
|
352
|
+
}).optional(),
|
|
353
|
+
}),
|
|
293
354
|
z.object({
|
|
294
355
|
type: z.literal("timeline.audio.fades"),
|
|
295
356
|
clipId: z.string().min(1),
|
|
@@ -344,6 +405,11 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
|
|
|
344
405
|
fadeIn: z.number().nonnegative().optional(),
|
|
345
406
|
fadeOut: z.number().nonnegative().optional(),
|
|
346
407
|
}),
|
|
408
|
+
z.object({
|
|
409
|
+
type: z.literal("timeline.mask.add"),
|
|
410
|
+
occurrenceId: z.string().min(1),
|
|
411
|
+
mask: maskSchema,
|
|
412
|
+
}),
|
|
347
413
|
]);
|
|
348
414
|
const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
|
|
349
415
|
operations.forEach((operation, index) => {
|
|
@@ -359,6 +425,11 @@ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRe
|
|
|
359
425
|
&& (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
|
|
360
426
|
context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "audio requires an explicit non-primary lane" });
|
|
361
427
|
}
|
|
428
|
+
if (operation.type === "timeline.picture-in-picture.add"
|
|
429
|
+
&& operation.crop
|
|
430
|
+
&& (operation.crop.left + operation.crop.right >= 1 || operation.crop.top + operation.crop.bottom >= 1)) {
|
|
431
|
+
context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "crop"], message: "PIP crop must leave a positive source rectangle" });
|
|
432
|
+
}
|
|
362
433
|
if (operation.type === "timeline.audio.mix"
|
|
363
434
|
&& operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
|
|
364
435
|
context.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: "audio mix requires a gain or fade change" });
|
|
@@ -470,6 +541,37 @@ const nativeTransitionPreviewSchema = {
|
|
|
470
541
|
afterOccurrenceHandle: z.string().min(1),
|
|
471
542
|
duration: rationalTimeSchema,
|
|
472
543
|
};
|
|
544
|
+
const nativePictureInPicturePreviewSchema = {
|
|
545
|
+
mediaHandle: z.string().min(1),
|
|
546
|
+
anchorOccurrenceHandle: z.string().min(1),
|
|
547
|
+
start: rationalTimeSchema,
|
|
548
|
+
duration: rationalTimeSchema,
|
|
549
|
+
position: z.object({ x: z.number().finite(), y: z.number().finite() }),
|
|
550
|
+
scale: z.number().finite().positive(),
|
|
551
|
+
crop: z.object({
|
|
552
|
+
top: z.number().finite().min(0).lt(1),
|
|
553
|
+
right: z.number().finite().min(0).lt(1),
|
|
554
|
+
bottom: z.number().finite().min(0).lt(1),
|
|
555
|
+
left: z.number().finite().min(0).lt(1),
|
|
556
|
+
}).optional(),
|
|
557
|
+
frame: z.object({
|
|
558
|
+
style: z.literal("solid"),
|
|
559
|
+
color: z.string().regex(/^#[0-9a-f]{6}$/i),
|
|
560
|
+
width: z.number().finite().nonnegative(),
|
|
561
|
+
}).optional(),
|
|
562
|
+
};
|
|
563
|
+
const nativeMaskPreviewSchema = {
|
|
564
|
+
occurrenceHandle: z.string().trim().min(1),
|
|
565
|
+
mask: nativeMaskSchema,
|
|
566
|
+
};
|
|
567
|
+
const timelineMaskInputSchema = {
|
|
568
|
+
projectId: z.string().trim().min(1),
|
|
569
|
+
sequenceId: z.string().trim().min(1),
|
|
570
|
+
baseRevision: revisionValueSchema,
|
|
571
|
+
occurrenceId: z.string().trim().min(1),
|
|
572
|
+
mask: maskSchema,
|
|
573
|
+
verification: verificationPolicySchema.optional(),
|
|
574
|
+
};
|
|
473
575
|
const exportAssertionSchema = z.discriminatedUnion("type", [
|
|
474
576
|
z.object({
|
|
475
577
|
type: z.literal("audio-audibility"),
|
|
@@ -526,11 +628,83 @@ const nativeEditToolInputSchema = z.object({
|
|
|
526
628
|
gainDb: z.number().finite().optional(),
|
|
527
629
|
duration: z.number().nonnegative().optional(),
|
|
528
630
|
}).strict();
|
|
631
|
+
const nativeOperationSessionSubmitSchema = z.object({
|
|
632
|
+
operation: z.literal("disposable.rename-clip"),
|
|
633
|
+
previewToken: z.string().trim().min(1),
|
|
634
|
+
projectId: z.string().trim().min(1),
|
|
635
|
+
sequenceId: z.string().trim().min(1),
|
|
636
|
+
targetIdentity: z.string().trim().min(1),
|
|
637
|
+
baseRevision: revisionValueSchema,
|
|
638
|
+
idempotencyKey: z.string().trim().min(1),
|
|
639
|
+
}).strict();
|
|
640
|
+
const nativeOperationSessionJobSchema = {
|
|
641
|
+
jobId: z.string().trim().min(1),
|
|
642
|
+
};
|
|
529
643
|
function jsonResult(value) {
|
|
530
644
|
return {
|
|
531
645
|
content: [{ type: "text", text: JSON.stringify(value) }],
|
|
532
646
|
};
|
|
533
647
|
}
|
|
648
|
+
function capabilityErrorResult(operation, capabilityName, capability) {
|
|
649
|
+
return {
|
|
650
|
+
isError: true,
|
|
651
|
+
content: [{
|
|
652
|
+
type: "text",
|
|
653
|
+
text: JSON.stringify({
|
|
654
|
+
code: "CAPABILITY_UNAVAILABLE",
|
|
655
|
+
message: `${operation} requires ${capabilityName}`,
|
|
656
|
+
operation,
|
|
657
|
+
capability: capabilityName,
|
|
658
|
+
available: false,
|
|
659
|
+
backend: capability.backend,
|
|
660
|
+
guarantee: capability.guarantee,
|
|
661
|
+
unavailableReason: capability.unavailableReason,
|
|
662
|
+
}),
|
|
663
|
+
}],
|
|
664
|
+
};
|
|
665
|
+
}
|
|
666
|
+
function nativeMediaImportErrorResult(error) {
|
|
667
|
+
const serialized = serializeNativeFinalCutMediaImportError(error);
|
|
668
|
+
if (serialized) {
|
|
669
|
+
return {
|
|
670
|
+
isError: true,
|
|
671
|
+
content: [{ type: "text", text: JSON.stringify(serialized) }],
|
|
672
|
+
};
|
|
673
|
+
}
|
|
674
|
+
if (!isDirectoryMediaImportError(error))
|
|
675
|
+
throw error;
|
|
676
|
+
return {
|
|
677
|
+
isError: true,
|
|
678
|
+
content: [{
|
|
679
|
+
type: "text",
|
|
680
|
+
text: JSON.stringify({
|
|
681
|
+
code: error.code,
|
|
682
|
+
message: error.message,
|
|
683
|
+
guidance: error.guidance,
|
|
684
|
+
}),
|
|
685
|
+
}],
|
|
686
|
+
};
|
|
687
|
+
}
|
|
688
|
+
function capabilityUnavailableErrorResult(error) {
|
|
689
|
+
const serialized = serializeCapabilityUnavailableError(error);
|
|
690
|
+
if (!serialized)
|
|
691
|
+
throw error;
|
|
692
|
+
return {
|
|
693
|
+
isError: true,
|
|
694
|
+
content: [{ type: "text", text: JSON.stringify(serialized) }],
|
|
695
|
+
};
|
|
696
|
+
}
|
|
697
|
+
function isDirectoryMediaImportError(error) {
|
|
698
|
+
if (!error || typeof error !== "object")
|
|
699
|
+
return false;
|
|
700
|
+
const value = error;
|
|
701
|
+
const guidance = value.guidance;
|
|
702
|
+
return value.code === NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE
|
|
703
|
+
&& Boolean(guidance)
|
|
704
|
+
&& typeof guidance === "object"
|
|
705
|
+
&& typeof guidance.previewTool === "string"
|
|
706
|
+
&& typeof guidance.executeTool === "string";
|
|
707
|
+
}
|
|
534
708
|
function skillErrorResult(error) {
|
|
535
709
|
const value = error && typeof error === "object" ? error : {};
|
|
536
710
|
const message = error instanceof Error ? error.message : String(error);
|
|
@@ -569,10 +743,20 @@ function normalizeConnectionStatus(value) {
|
|
|
569
743
|
const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
|
|
570
744
|
return {
|
|
571
745
|
...status,
|
|
572
|
-
capabilities: withCapabilityFamilies(status.capabilities, {
|
|
746
|
+
capabilities: withCanonicalTimelineMode(withCapabilityFamilies(status.capabilities, {
|
|
573
747
|
...(backend ? { backend, connectionBackend: backend } : {}),
|
|
574
748
|
connection: status.state === "ready",
|
|
575
|
-
}),
|
|
749
|
+
})),
|
|
750
|
+
};
|
|
751
|
+
}
|
|
752
|
+
function nativeMediaIntentCapabilities(nativeEditor) {
|
|
753
|
+
const capabilities = nativeEditor?.capabilities();
|
|
754
|
+
return {
|
|
755
|
+
"native.mediaImport": Boolean(capabilities?.mediaImport),
|
|
756
|
+
"native.mediaSelection": Boolean(capabilities?.mediaSelection),
|
|
757
|
+
"native.mediaAppendSelected": Boolean(capabilities?.mediaAppendSelected),
|
|
758
|
+
"native.mediaAppend": Boolean(capabilities?.mediaAppend),
|
|
759
|
+
"native.mediaInsert": Boolean(capabilities?.mediaInsert),
|
|
576
760
|
};
|
|
577
761
|
}
|
|
578
762
|
function isRuntimeCapabilities(value) {
|
|
@@ -606,7 +790,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
606
790
|
server.registerTool("connection.status", {
|
|
607
791
|
description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
|
|
608
792
|
inputSchema: {},
|
|
609
|
-
}, async () => jsonResult(
|
|
793
|
+
}, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
|
|
610
794
|
server.registerTool("skill.list", {
|
|
611
795
|
description: "List registered versioned Framekit Skills with current capability availability.",
|
|
612
796
|
inputSchema: {},
|
|
@@ -670,22 +854,55 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
670
854
|
});
|
|
671
855
|
server.registerTool("project.inspect", {
|
|
672
856
|
description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
|
|
673
|
-
}, async () =>
|
|
857
|
+
}, async () => {
|
|
858
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
859
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
860
|
+
if (!capability.available) {
|
|
861
|
+
return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
|
|
862
|
+
}
|
|
863
|
+
try {
|
|
864
|
+
return jsonResult(await runtime.inspectProject());
|
|
865
|
+
}
|
|
866
|
+
catch (error) {
|
|
867
|
+
return capabilityUnavailableErrorResult(error);
|
|
868
|
+
}
|
|
869
|
+
});
|
|
674
870
|
server.registerTool("artifact.inspect", {
|
|
675
|
-
description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
|
|
871
|
+
description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
|
|
676
872
|
inputSchema: {},
|
|
677
873
|
}, async () => jsonResult(await runtime.inspectArtifact()));
|
|
678
874
|
server.registerTool("project.list", {
|
|
679
875
|
description: "List projects and their stable Final Cut sequence identities, including the active target.",
|
|
680
876
|
inputSchema: {},
|
|
681
|
-
}, async () =>
|
|
877
|
+
}, async () => {
|
|
878
|
+
try {
|
|
879
|
+
return jsonResult(await runtime.listProjects());
|
|
880
|
+
}
|
|
881
|
+
catch (error) {
|
|
882
|
+
const inspectionError = serializeFinalCutLibraryInspectionError(error);
|
|
883
|
+
if (inspectionError) {
|
|
884
|
+
return {
|
|
885
|
+
isError: true,
|
|
886
|
+
content: [{ type: "text", text: JSON.stringify(inspectionError) }],
|
|
887
|
+
};
|
|
888
|
+
}
|
|
889
|
+
return capabilityUnavailableErrorResult(error);
|
|
890
|
+
}
|
|
891
|
+
});
|
|
682
892
|
server.registerTool("project.select", {
|
|
683
893
|
description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
|
|
684
894
|
inputSchema: {
|
|
685
895
|
projectId: z.string().min(1),
|
|
686
896
|
sequenceId: z.string().min(1).optional(),
|
|
687
897
|
},
|
|
688
|
-
}, async ({ projectId, sequenceId }) =>
|
|
898
|
+
}, async ({ projectId, sequenceId }) => {
|
|
899
|
+
try {
|
|
900
|
+
return jsonResult(await runtime.selectProject({ projectId, sequenceId }));
|
|
901
|
+
}
|
|
902
|
+
catch (error) {
|
|
903
|
+
return capabilityUnavailableErrorResult(error);
|
|
904
|
+
}
|
|
905
|
+
});
|
|
689
906
|
server.registerTool("editor.inspect", {
|
|
690
907
|
description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
|
|
691
908
|
}, async () => {
|
|
@@ -705,13 +922,23 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
705
922
|
server.registerTool("editing.intent.resolve", {
|
|
706
923
|
description: "Map a supported natural-language editing request to one explicit operation without executing it.",
|
|
707
924
|
inputSchema: { request: z.string().trim().min(1) },
|
|
708
|
-
}, async ({ request }) => jsonResult(resolveEditingIntent(request
|
|
925
|
+
}, async ({ request }) => jsonResult(resolveEditingIntent(request, {
|
|
926
|
+
availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
|
|
927
|
+
})));
|
|
709
928
|
server.registerTool("editing.route", {
|
|
710
929
|
description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
|
|
711
930
|
inputSchema: {
|
|
712
931
|
operation: z.enum([
|
|
932
|
+
"project.list",
|
|
933
|
+
"project.select",
|
|
934
|
+
"project.inspect",
|
|
935
|
+
"timeline.inspect",
|
|
936
|
+
"editor.live.inspect",
|
|
713
937
|
"timeline.edit",
|
|
938
|
+
"artifact.edit",
|
|
939
|
+
"timeline.mask.add",
|
|
714
940
|
"editor.native.edit",
|
|
941
|
+
"editor.native.picture-in-picture",
|
|
715
942
|
"timeline.publish.new-project",
|
|
716
943
|
"timeline.export",
|
|
717
944
|
]),
|
|
@@ -728,31 +955,52 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
728
955
|
server.registerTool("editor.native.inspect", {
|
|
729
956
|
description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
|
|
730
957
|
inputSchema: {},
|
|
731
|
-
}, async () => jsonResult(options.nativeEditor
|
|
732
|
-
? await options.nativeEditor.inspect()
|
|
958
|
+
}, async (_args, extra) => jsonResult(options.nativeEditor
|
|
959
|
+
? await options.nativeEditor.inspect({ signal: extra.signal })
|
|
733
960
|
: { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
|
|
734
961
|
server.registerTool("editor.native.focus", {
|
|
735
962
|
description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
|
|
736
963
|
inputSchema: {},
|
|
737
|
-
}, async () => jsonResult(options.nativeEditor
|
|
738
|
-
? await options.nativeEditor.focusTimeline()
|
|
964
|
+
}, async (_args, extra) => jsonResult(options.nativeEditor
|
|
965
|
+
? await options.nativeEditor.focusTimeline({ signal: extra.signal })
|
|
739
966
|
: { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
|
|
740
967
|
server.registerTool("editor.native.media.import", {
|
|
741
968
|
description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
|
|
742
969
|
inputSchema: { path: z.string().min(1) },
|
|
743
|
-
}, async ({ path }) => {
|
|
970
|
+
}, async ({ path }, extra) => {
|
|
971
|
+
if (!options.nativeEditor)
|
|
972
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
973
|
+
try {
|
|
974
|
+
return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
|
|
975
|
+
}
|
|
976
|
+
catch (error) {
|
|
977
|
+
return nativeMediaImportErrorResult(error);
|
|
978
|
+
}
|
|
979
|
+
});
|
|
980
|
+
server.registerTool("editor.native.media.directory.preview", {
|
|
981
|
+
description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
|
|
982
|
+
inputSchema: { path: z.string().trim().min(1) },
|
|
983
|
+
}, async ({ path }, extra) => {
|
|
984
|
+
if (!options.nativeEditor)
|
|
985
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
986
|
+
return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
|
|
987
|
+
});
|
|
988
|
+
server.registerTool("editor.native.media.directory.execute", {
|
|
989
|
+
description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
|
|
990
|
+
inputSchema: { previewToken: z.string().min(1), confirm: z.literal(true) },
|
|
991
|
+
}, async ({ previewToken, confirm }, extra) => {
|
|
744
992
|
if (!options.nativeEditor)
|
|
745
993
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
746
|
-
return jsonResult(await options.nativeEditor.
|
|
994
|
+
return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
|
|
747
995
|
});
|
|
748
996
|
server.registerTool("editor.native.edit", {
|
|
749
997
|
description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
|
|
750
998
|
inputSchema: nativeEditToolInputSchema,
|
|
751
|
-
}, async (input) => {
|
|
999
|
+
}, async (input, extra) => {
|
|
752
1000
|
if (!options.nativeEditor)
|
|
753
1001
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
|
|
754
1002
|
const operation = nativeEditSchema.parse(input);
|
|
755
|
-
return jsonResult(await options.nativeEditor.edit(operation));
|
|
1003
|
+
return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
|
|
756
1004
|
});
|
|
757
1005
|
server.registerTool("editor.native.disposable.preview", {
|
|
758
1006
|
description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
|
|
@@ -765,7 +1013,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
765
1013
|
server.registerTool("editor.native.disposable.execute", {
|
|
766
1014
|
description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
|
|
767
1015
|
inputSchema: { previewToken: z.string().min(1) },
|
|
768
|
-
}, async ({ previewToken }) => {
|
|
1016
|
+
}, async ({ previewToken }, extra) => {
|
|
769
1017
|
if (!options.disposableNative)
|
|
770
1018
|
throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
|
|
771
1019
|
return jsonResult(await options.disposableNative.execute(previewToken));
|
|
@@ -778,30 +1026,80 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
778
1026
|
throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
|
|
779
1027
|
return jsonResult(await options.disposableNative.undo(operationId));
|
|
780
1028
|
});
|
|
1029
|
+
server.registerTool("editor.native.operation.submit", {
|
|
1030
|
+
description: "Accept a previewed native Final Cut operation as a resumable job without waiting for headed readiness.",
|
|
1031
|
+
inputSchema: nativeOperationSessionSubmitSchema,
|
|
1032
|
+
}, async (request) => {
|
|
1033
|
+
if (!options.nativeOperationSession)
|
|
1034
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1035
|
+
return jsonResult(await options.nativeOperationSession.submit(request));
|
|
1036
|
+
});
|
|
1037
|
+
server.registerTool("editor.native.operation.status", {
|
|
1038
|
+
description: "Poll a resumable native Final Cut operation for readiness, completion, verification, and restoration evidence.",
|
|
1039
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1040
|
+
}, async ({ jobId }) => {
|
|
1041
|
+
if (!options.nativeOperationSession)
|
|
1042
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1043
|
+
return jsonResult(options.nativeOperationSession.status(jobId));
|
|
1044
|
+
});
|
|
1045
|
+
server.registerTool("editor.native.operation.retry", {
|
|
1046
|
+
description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
|
|
1047
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1048
|
+
}, async ({ jobId }) => {
|
|
1049
|
+
if (!options.nativeOperationSession)
|
|
1050
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1051
|
+
return jsonResult(await options.nativeOperationSession.retry(jobId));
|
|
1052
|
+
});
|
|
1053
|
+
server.registerTool("editor.native.operation.cancel", {
|
|
1054
|
+
description: "Cancel a pending native Final Cut operation or report recovery when mutation has already started.",
|
|
1055
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1056
|
+
}, async ({ jobId }) => {
|
|
1057
|
+
if (!options.nativeOperationSession)
|
|
1058
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1059
|
+
return jsonResult(await options.nativeOperationSession.cancel(jobId));
|
|
1060
|
+
});
|
|
781
1061
|
server.registerTool("editor.native.title.add.preview", {
|
|
782
1062
|
description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
|
|
783
1063
|
inputSchema: nativeTitlePreviewSchema,
|
|
784
|
-
}, async ({ assetId, text, start, duration }) => {
|
|
1064
|
+
}, async ({ assetId, text, start, duration }, extra) => {
|
|
785
1065
|
if (!options.nativeEditor)
|
|
786
1066
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
|
|
787
1067
|
const asset = await resolveNativeTitleAsset(runtime, assetId);
|
|
788
|
-
return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
|
|
1068
|
+
return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }, { signal: extra.signal }));
|
|
789
1069
|
});
|
|
790
1070
|
server.registerTool("editor.native.title.add.execute", {
|
|
791
1071
|
description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
|
|
792
1072
|
inputSchema: { previewToken: z.string().min(1) },
|
|
793
|
-
}, async ({ previewToken }) => {
|
|
1073
|
+
}, async ({ previewToken }, extra) => {
|
|
794
1074
|
if (!options.nativeEditor)
|
|
795
1075
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
|
|
796
|
-
return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
|
|
1076
|
+
return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
|
|
1077
|
+
});
|
|
1078
|
+
server.registerTool("editor.native.picture-in-picture.preview", {
|
|
1079
|
+
description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
|
|
1080
|
+
inputSchema: nativePictureInPicturePreviewSchema,
|
|
1081
|
+
}, async (request, extra) => {
|
|
1082
|
+
if (!options.nativeEditor)
|
|
1083
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
|
|
1084
|
+
await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
|
|
1085
|
+
return jsonResult(await options.nativeEditor.previewPictureInPicture(request, { signal: extra.signal }));
|
|
1086
|
+
});
|
|
1087
|
+
server.registerTool("editor.native.picture-in-picture.execute", {
|
|
1088
|
+
description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
|
|
1089
|
+
inputSchema: { previewToken: z.string().min(1) },
|
|
1090
|
+
}, async ({ previewToken }, extra) => {
|
|
1091
|
+
if (!options.nativeEditor)
|
|
1092
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
|
|
1093
|
+
await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
|
|
1094
|
+
return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
|
|
797
1095
|
});
|
|
798
1096
|
server.registerTool("editor.native.transition.search", {
|
|
799
1097
|
description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
|
|
800
1098
|
inputSchema: { query: z.string().trim().min(1) },
|
|
801
|
-
}, async ({ query }) => {
|
|
1099
|
+
}, async ({ query }, extra) => {
|
|
802
1100
|
if (!options.nativeEditor)
|
|
803
1101
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
|
|
804
|
-
const matches = await options.nativeEditor.searchTransitions(query);
|
|
1102
|
+
const matches = await options.nativeEditor.searchTransitions(query, { signal: extra.signal });
|
|
805
1103
|
for (const match of matches) {
|
|
806
1104
|
nativeTransitionAssets.set(match.id, match);
|
|
807
1105
|
nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
|
|
@@ -811,160 +1109,220 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
811
1109
|
server.registerTool("editor.native.transition.add.preview", {
|
|
812
1110
|
description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
|
|
813
1111
|
inputSchema: nativeTransitionPreviewSchema,
|
|
814
|
-
}, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
|
|
1112
|
+
}, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }, extra) => {
|
|
815
1113
|
if (!options.nativeEditor)
|
|
816
1114
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
|
|
817
|
-
const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
|
|
1115
|
+
const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets, extra.signal);
|
|
818
1116
|
return jsonResult(await options.nativeEditor.previewTransitionAdd({
|
|
819
1117
|
asset,
|
|
820
1118
|
beforeOccurrenceHandle,
|
|
821
1119
|
afterOccurrenceHandle,
|
|
822
1120
|
duration,
|
|
823
|
-
}));
|
|
1121
|
+
}, { signal: extra.signal }));
|
|
824
1122
|
});
|
|
825
1123
|
server.registerTool("editor.native.transition.add.execute", {
|
|
826
1124
|
description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
|
|
827
1125
|
inputSchema: { previewToken: z.string().min(1) },
|
|
828
|
-
}, async ({ previewToken }) => {
|
|
1126
|
+
}, async ({ previewToken }, extra) => {
|
|
829
1127
|
if (!options.nativeEditor)
|
|
830
1128
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
|
|
831
|
-
return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
|
|
1129
|
+
return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
|
|
1130
|
+
});
|
|
1131
|
+
server.registerTool("editor.native.mask.preview", {
|
|
1132
|
+
description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
|
|
1133
|
+
inputSchema: nativeMaskPreviewSchema,
|
|
1134
|
+
}, async ({ occurrenceHandle, mask }, extra) => {
|
|
1135
|
+
if (!options.nativeEditor)
|
|
1136
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
|
|
1137
|
+
return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }, { signal: extra.signal }));
|
|
1138
|
+
});
|
|
1139
|
+
server.registerTool("editor.native.mask.execute", {
|
|
1140
|
+
description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
|
|
1141
|
+
inputSchema: { previewToken: z.string().trim().min(1) },
|
|
1142
|
+
}, async ({ previewToken }, extra) => {
|
|
1143
|
+
if (!options.nativeEditor)
|
|
1144
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
|
|
1145
|
+
return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
|
|
832
1146
|
});
|
|
833
1147
|
server.registerTool("editor.native.undo", {
|
|
834
1148
|
description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
|
|
835
1149
|
inputSchema: { operationId: z.string().min(1) },
|
|
836
|
-
}, async ({ operationId }) => {
|
|
1150
|
+
}, async ({ operationId }, extra) => {
|
|
837
1151
|
if (!options.nativeEditor)
|
|
838
1152
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
|
|
839
|
-
return jsonResult(await options.nativeEditor.undo(operationId));
|
|
1153
|
+
return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
|
|
840
1154
|
});
|
|
841
1155
|
server.registerTool("editor.native.media.search", {
|
|
842
1156
|
description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
|
|
843
1157
|
inputSchema: { query: z.string().min(1) },
|
|
844
|
-
}, async ({ query }) => {
|
|
1158
|
+
}, async ({ query }, extra) => {
|
|
845
1159
|
if (!options.nativeEditor)
|
|
846
1160
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
|
|
847
|
-
return jsonResult(await options.nativeEditor.searchMedia(query));
|
|
1161
|
+
return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
|
|
848
1162
|
});
|
|
849
1163
|
server.registerTool("editor.native.media.select", {
|
|
850
1164
|
description: "Select one live Final Cut Browser media result using its short-lived handle.",
|
|
851
1165
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
852
|
-
}, async ({ mediaHandle }) => {
|
|
1166
|
+
}, async ({ mediaHandle }, extra) => {
|
|
853
1167
|
if (!options.nativeEditor)
|
|
854
1168
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
|
|
855
|
-
return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
|
|
1169
|
+
return jsonResult(await options.nativeEditor.selectMedia(mediaHandle, { signal: extra.signal }));
|
|
856
1170
|
});
|
|
857
1171
|
server.registerTool("editor.native.media.append.preview", {
|
|
858
1172
|
description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
|
|
859
1173
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
860
|
-
}, async ({ mediaHandle }) => {
|
|
1174
|
+
}, async ({ mediaHandle }, extra) => {
|
|
861
1175
|
if (!options.nativeEditor)
|
|
862
1176
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
|
|
863
|
-
return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
|
|
1177
|
+
return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle, { signal: extra.signal }));
|
|
864
1178
|
});
|
|
865
1179
|
server.registerTool("editor.native.media.append.execute", {
|
|
866
1180
|
description: "Execute a previously previewed append of selected Final Cut Browser media.",
|
|
867
1181
|
inputSchema: { previewToken: z.string().min(1) },
|
|
868
|
-
}, async ({ previewToken }) => {
|
|
1182
|
+
}, async ({ previewToken }, extra) => {
|
|
869
1183
|
if (!options.nativeEditor)
|
|
870
1184
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
|
|
871
|
-
return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
|
|
1185
|
+
return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
|
|
872
1186
|
});
|
|
873
1187
|
server.registerTool("editor.native.media.append.selected.preview", {
|
|
874
1188
|
description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
|
|
875
1189
|
inputSchema: {},
|
|
876
|
-
}, async () => {
|
|
1190
|
+
}, async (_args, extra) => {
|
|
877
1191
|
if (!options.nativeEditor)
|
|
878
1192
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
|
|
879
|
-
return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
|
|
1193
|
+
return jsonResult(await options.nativeEditor.previewAppendSelectedMedia({ signal: extra.signal }));
|
|
880
1194
|
});
|
|
881
1195
|
server.registerTool("editor.native.media.append.selected.execute", {
|
|
882
1196
|
description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
|
|
883
1197
|
inputSchema: { previewToken: z.string().min(1) },
|
|
884
|
-
}, async ({ previewToken }) => {
|
|
1198
|
+
}, async ({ previewToken }, extra) => {
|
|
885
1199
|
if (!options.nativeEditor)
|
|
886
1200
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
|
|
887
|
-
return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
|
|
1201
|
+
return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
|
|
888
1202
|
});
|
|
889
1203
|
server.registerTool("editor.native.media.insert.preview", {
|
|
890
1204
|
description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
|
|
891
1205
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
892
|
-
}, async ({ mediaHandle }) => {
|
|
1206
|
+
}, async ({ mediaHandle }, extra) => {
|
|
893
1207
|
if (!options.nativeEditor)
|
|
894
1208
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
|
|
895
|
-
return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
|
|
1209
|
+
return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle, { signal: extra.signal }));
|
|
896
1210
|
});
|
|
897
1211
|
server.registerTool("editor.native.media.insert.execute", {
|
|
898
1212
|
description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
|
|
899
1213
|
inputSchema: { previewToken: z.string().min(1) },
|
|
900
|
-
}, async ({ previewToken }) => {
|
|
1214
|
+
}, async ({ previewToken }, extra) => {
|
|
901
1215
|
if (!options.nativeEditor)
|
|
902
1216
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
|
|
903
|
-
return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
|
|
1217
|
+
return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
|
|
904
1218
|
});
|
|
905
1219
|
server.registerTool("editor.native.timeline.locate", {
|
|
906
1220
|
description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
|
|
907
1221
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
908
|
-
}, async ({ mediaHandle }) => {
|
|
1222
|
+
}, async ({ mediaHandle }, extra) => {
|
|
909
1223
|
if (!options.nativeEditor)
|
|
910
1224
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
|
|
911
|
-
return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
|
|
1225
|
+
return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle, { signal: extra.signal }));
|
|
912
1226
|
});
|
|
913
1227
|
server.registerTool("editor.native.media.target", {
|
|
914
1228
|
description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
|
|
915
1229
|
inputSchema: { query: z.string().min(1) },
|
|
916
|
-
}, async ({ query }) => {
|
|
1230
|
+
}, async ({ query }, extra) => {
|
|
917
1231
|
if (!options.nativeEditor)
|
|
918
1232
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
|
|
919
|
-
return jsonResult(await options.nativeEditor.targetMedia(query));
|
|
1233
|
+
return jsonResult(await options.nativeEditor.targetMedia(query, { signal: extra.signal }));
|
|
920
1234
|
});
|
|
921
1235
|
server.registerTool("editor.native.blade.preview", {
|
|
922
1236
|
description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
|
|
923
1237
|
inputSchema: { occurrenceHandle: z.string().min(1) },
|
|
924
|
-
}, async ({ occurrenceHandle }) => {
|
|
1238
|
+
}, async ({ occurrenceHandle }, extra) => {
|
|
925
1239
|
if (!options.nativeEditor)
|
|
926
1240
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
|
|
927
|
-
return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
|
|
1241
|
+
return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle, { signal: extra.signal }));
|
|
928
1242
|
});
|
|
929
1243
|
server.registerTool("editor.native.blade.execute", {
|
|
930
1244
|
description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
|
|
931
1245
|
inputSchema: { previewToken: z.string().min(1) },
|
|
932
|
-
}, async ({ previewToken }) => {
|
|
1246
|
+
}, async ({ previewToken }, extra) => {
|
|
933
1247
|
if (!options.nativeEditor)
|
|
934
1248
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
|
|
935
|
-
return jsonResult(await options.nativeEditor.executeBlade(previewToken));
|
|
1249
|
+
return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
|
|
936
1250
|
});
|
|
937
1251
|
server.registerTool("editor.native.delete-range.preview", {
|
|
938
1252
|
description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
|
|
939
1253
|
inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
|
|
940
|
-
}, async ({ start, end }) => {
|
|
1254
|
+
}, async ({ start, end }, extra) => {
|
|
941
1255
|
if (!options.nativeEditor)
|
|
942
1256
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
|
|
943
|
-
return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
|
|
1257
|
+
return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }, { signal: extra.signal }));
|
|
944
1258
|
});
|
|
945
1259
|
server.registerTool("editor.native.delete-range.execute", {
|
|
946
1260
|
description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
|
|
947
1261
|
inputSchema: { previewToken: z.string().min(1) },
|
|
948
|
-
}, async ({ previewToken }) => {
|
|
1262
|
+
}, async ({ previewToken }, extra) => {
|
|
949
1263
|
if (!options.nativeEditor)
|
|
950
1264
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
|
|
951
|
-
return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
|
|
1265
|
+
return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
|
|
952
1266
|
});
|
|
953
1267
|
server.registerTool("editor.native.trim-to-duration.preview", {
|
|
954
1268
|
description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
|
|
955
1269
|
inputSchema: { duration: rationalTimeSchema },
|
|
956
|
-
}, async ({ duration }) => {
|
|
1270
|
+
}, async ({ duration }, extra) => {
|
|
957
1271
|
if (!options.nativeEditor)
|
|
958
1272
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
|
|
959
|
-
return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
|
|
1273
|
+
return jsonResult(await options.nativeEditor.previewTrimToDuration(duration, { signal: extra.signal }));
|
|
960
1274
|
});
|
|
961
1275
|
server.registerTool("editor.native.trim-to-duration.execute", {
|
|
962
1276
|
description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
|
|
963
1277
|
inputSchema: { previewToken: z.string().min(1) },
|
|
964
|
-
}, async ({ previewToken }) => {
|
|
1278
|
+
}, async ({ previewToken }, extra) => {
|
|
965
1279
|
if (!options.nativeEditor)
|
|
966
1280
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
|
|
967
|
-
return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
|
|
1281
|
+
return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
|
|
1282
|
+
});
|
|
1283
|
+
server.registerTool("artifact.publish.preview", {
|
|
1284
|
+
description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
|
|
1285
|
+
inputSchema: {
|
|
1286
|
+
artifactPath: z.string().trim().min(1),
|
|
1287
|
+
transactionId: z.string().min(1),
|
|
1288
|
+
},
|
|
1289
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1290
|
+
if (!options.projectPublisher)
|
|
1291
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1292
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1293
|
+
if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
|
|
1294
|
+
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
|
|
1295
|
+
}
|
|
1296
|
+
if (!transaction.artifactDigest) {
|
|
1297
|
+
throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
|
|
1298
|
+
}
|
|
1299
|
+
const verification = await runtime.verifyTransaction(transactionId);
|
|
1300
|
+
if (!verification.passed)
|
|
1301
|
+
throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
|
|
1302
|
+
return jsonResult(await options.projectPublisher.preparePublish({
|
|
1303
|
+
sourceTransactionId: transactionId,
|
|
1304
|
+
artifactPath,
|
|
1305
|
+
artifactDigest: transaction.artifactDigest,
|
|
1306
|
+
}));
|
|
1307
|
+
});
|
|
1308
|
+
server.registerTool("artifact.publish.execute", {
|
|
1309
|
+
description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
|
|
1310
|
+
inputSchema: {
|
|
1311
|
+
jobId: z.string().trim().min(1),
|
|
1312
|
+
confirm: z.literal(true),
|
|
1313
|
+
},
|
|
1314
|
+
}, async ({ jobId, confirm }) => {
|
|
1315
|
+
if (!options.projectPublisher)
|
|
1316
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1317
|
+
return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
|
|
1318
|
+
});
|
|
1319
|
+
server.registerTool("artifact.publish.status", {
|
|
1320
|
+
description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
|
|
1321
|
+
inputSchema: { jobId: z.string().trim().min(1) },
|
|
1322
|
+
}, async ({ jobId }) => {
|
|
1323
|
+
if (!options.projectPublisher)
|
|
1324
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1325
|
+
return jsonResult(options.projectPublisher.getPublishJob(jobId));
|
|
968
1326
|
});
|
|
969
1327
|
server.registerTool("artifact.publish", {
|
|
970
1328
|
description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
|
|
@@ -1089,9 +1447,21 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1089
1447
|
timestamp: new Date(sequence).toISOString(),
|
|
1090
1448
|
}, waitMs ?? 0)));
|
|
1091
1449
|
server.registerTool("editor.live.inspect", {
|
|
1092
|
-
description: "Read live Final Cut
|
|
1450
|
+
description: "Read observed live Final Cut state without requiring canonical timeline snapshot capability.",
|
|
1093
1451
|
inputSchema: {},
|
|
1094
|
-
}, async () =>
|
|
1452
|
+
}, async () => {
|
|
1453
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1454
|
+
const capability = inspected.capabilities.families.observation.timeline;
|
|
1455
|
+
if (!capability.available) {
|
|
1456
|
+
return capabilityErrorResult("editor.live.inspect", "observation.timeline", capability);
|
|
1457
|
+
}
|
|
1458
|
+
try {
|
|
1459
|
+
return jsonResult(await runtime.inspectLiveEditor());
|
|
1460
|
+
}
|
|
1461
|
+
catch (error) {
|
|
1462
|
+
return capabilityUnavailableErrorResult(error);
|
|
1463
|
+
}
|
|
1464
|
+
});
|
|
1095
1465
|
server.registerTool("editor.live.changes", {
|
|
1096
1466
|
description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
|
|
1097
1467
|
inputSchema: {
|
|
@@ -1104,8 +1474,20 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1104
1474
|
timestamp: new Date(sequence).toISOString(),
|
|
1105
1475
|
}, waitMs ?? 0)));
|
|
1106
1476
|
server.registerTool("timeline.inspect", {
|
|
1107
|
-
description: "Read the current canonical timeline snapshot.",
|
|
1108
|
-
}, async () =>
|
|
1477
|
+
description: "Read the current canonical timeline snapshot after canonical capability checks.",
|
|
1478
|
+
}, async () => {
|
|
1479
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1480
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1481
|
+
if (!capability.available) {
|
|
1482
|
+
return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
|
|
1483
|
+
}
|
|
1484
|
+
try {
|
|
1485
|
+
return jsonResult(await runtime.inspectTimeline());
|
|
1486
|
+
}
|
|
1487
|
+
catch (error) {
|
|
1488
|
+
return capabilityUnavailableErrorResult(error);
|
|
1489
|
+
}
|
|
1490
|
+
});
|
|
1109
1491
|
server.registerTool("timeline.frame.capture", {
|
|
1110
1492
|
description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
|
|
1111
1493
|
inputSchema: {
|
|
@@ -1120,7 +1502,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1120
1502
|
server.registerTool("media.search", {
|
|
1121
1503
|
description: "Search normalized media references by id or source path.",
|
|
1122
1504
|
inputSchema: { query: z.string() },
|
|
1123
|
-
}, async ({ query }) =>
|
|
1505
|
+
}, async ({ query }) => {
|
|
1506
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1507
|
+
const capability = inspected.capabilities.families.observation.media;
|
|
1508
|
+
if (!capability.available) {
|
|
1509
|
+
return capabilityErrorResult("media.search", "observation.media", capability);
|
|
1510
|
+
}
|
|
1511
|
+
try {
|
|
1512
|
+
return jsonResult(await runtime.searchMedia(query));
|
|
1513
|
+
}
|
|
1514
|
+
catch (error) {
|
|
1515
|
+
return capabilityUnavailableErrorResult(error);
|
|
1516
|
+
}
|
|
1517
|
+
});
|
|
1124
1518
|
server.registerTool("media.index", {
|
|
1125
1519
|
description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
|
|
1126
1520
|
inputSchema: mediaIndexQuerySchema.shape,
|
|
@@ -1141,11 +1535,12 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1141
1535
|
inputSchema: roughCutPlanSchema.shape,
|
|
1142
1536
|
}, async (request) => jsonResult(await runtime.planRoughCut(request)));
|
|
1143
1537
|
server.registerTool("editor.assets", {
|
|
1144
|
-
description: "Search
|
|
1538
|
+
description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
|
|
1145
1539
|
inputSchema: {
|
|
1146
1540
|
query: z.string().optional(),
|
|
1147
1541
|
kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
|
|
1148
1542
|
vendor: z.string().optional(),
|
|
1543
|
+
discovery: z.enum(["background", "native", "all"]).optional().default("background"),
|
|
1149
1544
|
},
|
|
1150
1545
|
}, async (query) => jsonResult(await runtime.listAssets(query)));
|
|
1151
1546
|
server.registerTool("timeline.changes", {
|
|
@@ -1175,16 +1570,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1175
1570
|
inputSchema: roughCutConstructionPlanInputSchema,
|
|
1176
1571
|
}, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
|
|
1177
1572
|
server.registerTool("artifact.edit", {
|
|
1178
|
-
description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
|
|
1573
|
+
description: "Edit the identified managed FCPXML artifact in the background and return its artifact target, new revision, read-after-write, and diff.",
|
|
1179
1574
|
inputSchema: artifactEditToolInputSchema,
|
|
1180
1575
|
}, async (input) => {
|
|
1576
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1181
1577
|
const { artifactPath, verification, ...operation } = input;
|
|
1182
|
-
|
|
1578
|
+
const transaction = await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {});
|
|
1579
|
+
return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
|
|
1183
1580
|
});
|
|
1184
1581
|
server.registerTool("editor.timeline.edit", {
|
|
1185
1582
|
description: "Edit the active Final Cut project and sequence identified by IDs and base revision; return the live timeline target, read-after-write, and diff.",
|
|
1186
1583
|
inputSchema: editorTimelineEditToolInputSchema,
|
|
1187
1584
|
}, async (input) => {
|
|
1585
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1188
1586
|
const { projectId, sequenceId, verification, ...operation } = input;
|
|
1189
1587
|
return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
|
|
1190
1588
|
});
|
|
@@ -1211,15 +1609,29 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1211
1609
|
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1212
1610
|
return jsonResult(await runtime.previewEdit(request));
|
|
1213
1611
|
});
|
|
1612
|
+
server.registerTool("timeline.mask.add.preview", {
|
|
1613
|
+
description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
|
|
1614
|
+
inputSchema: timelineMaskInputSchema,
|
|
1615
|
+
}, async ({ projectId, sequenceId, baseRevision, occurrenceId, mask, verification }) => {
|
|
1616
|
+
await requireEditingRoute(runtime, options, "timeline.mask.add");
|
|
1617
|
+
return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, {
|
|
1618
|
+
baseRevision,
|
|
1619
|
+
operations: [{ type: "timeline.mask.add", occurrenceId, mask }],
|
|
1620
|
+
...(verification ? { verification } : {}),
|
|
1621
|
+
}));
|
|
1622
|
+
});
|
|
1214
1623
|
server.registerTool("artifact.edit.preview", {
|
|
1215
|
-
description: "Validate and preview an ordered artifact edit
|
|
1624
|
+
description: "Validate and preview an ordered background FCPXML artifact edit without mutating it or the open Final Cut timeline.",
|
|
1216
1625
|
inputSchema: {
|
|
1217
1626
|
artifactPath: z.string().trim().min(1),
|
|
1218
1627
|
baseRevision: revisionValueSchema,
|
|
1219
1628
|
operations: workflowOperationsSchema,
|
|
1220
1629
|
verification: verificationPolicySchema.optional(),
|
|
1221
1630
|
},
|
|
1222
|
-
}, async ({ artifactPath, baseRevision, operations, verification }) =>
|
|
1631
|
+
}, async ({ artifactPath, baseRevision, operations, verification }) => {
|
|
1632
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1633
|
+
return jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) }).then(withArtifactPreviewProvenance));
|
|
1634
|
+
});
|
|
1223
1635
|
server.registerTool("editor.timeline.edit.preview", {
|
|
1224
1636
|
description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
|
|
1225
1637
|
inputSchema: {
|
|
@@ -1229,15 +1641,51 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1229
1641
|
operations: workflowOperationsSchema,
|
|
1230
1642
|
verification: verificationPolicySchema.optional(),
|
|
1231
1643
|
},
|
|
1232
|
-
}, async ({ projectId, sequenceId, baseRevision, operations, verification }) =>
|
|
1644
|
+
}, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
|
|
1645
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1646
|
+
return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
|
|
1647
|
+
});
|
|
1233
1648
|
server.registerTool("artifact.edit.execute", {
|
|
1234
|
-
description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
|
|
1649
|
+
description: "Execute one short-lived background artifact edit preview token exactly once and verify the FCPXML artifact transaction.",
|
|
1235
1650
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1236
|
-
}, async ({ previewToken }) =>
|
|
1651
|
+
}, async ({ previewToken }) => {
|
|
1652
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1653
|
+
const transaction = await runtime.executeEdit(previewToken);
|
|
1654
|
+
return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
|
|
1655
|
+
});
|
|
1656
|
+
server.registerTool("artifact.edit.diff", {
|
|
1657
|
+
description: "Read the deterministic diff for a background FCPXML artifact transaction.",
|
|
1658
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1659
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1660
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1661
|
+
return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
|
|
1662
|
+
});
|
|
1663
|
+
server.registerTool("artifact.edit.verify", {
|
|
1664
|
+
description: "Read verification checks for a background FCPXML artifact transaction.",
|
|
1665
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1666
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1667
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1668
|
+
return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
|
|
1669
|
+
});
|
|
1670
|
+
server.registerTool("artifact.edit.undo", {
|
|
1671
|
+
description: "Restore a background FCPXML artifact transaction without changing the open Final Cut timeline.",
|
|
1672
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1673
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1674
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1675
|
+
const restored = await runtime.undo(transactionId);
|
|
1676
|
+
const artifact = await runtime.inspectArtifact();
|
|
1677
|
+
return jsonResult({
|
|
1678
|
+
...restored,
|
|
1679
|
+
...withTransactionProvenance(transaction, restored.revision, artifact.digest),
|
|
1680
|
+
});
|
|
1681
|
+
});
|
|
1237
1682
|
server.registerTool("editor.timeline.edit.execute", {
|
|
1238
1683
|
description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
|
|
1239
1684
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1240
|
-
}, async ({ previewToken }) =>
|
|
1685
|
+
}, async ({ previewToken }) => {
|
|
1686
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1687
|
+
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1688
|
+
});
|
|
1241
1689
|
server.registerTool("timeline.edit.execute", {
|
|
1242
1690
|
description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
|
|
1243
1691
|
inputSchema: { previewToken: z.string().min(1) },
|
|
@@ -1245,6 +1693,13 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1245
1693
|
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1246
1694
|
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1247
1695
|
});
|
|
1696
|
+
server.registerTool("timeline.mask.add.execute", {
|
|
1697
|
+
description: "Execute one short-lived mask preview token after capability and revision checks, then verify the mask state.",
|
|
1698
|
+
inputSchema: { previewToken: z.string().trim().min(1) },
|
|
1699
|
+
}, async ({ previewToken }) => {
|
|
1700
|
+
await requireEditingRoute(runtime, options, "timeline.mask.add");
|
|
1701
|
+
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1702
|
+
});
|
|
1248
1703
|
server.registerTool("speech.analyze", {
|
|
1249
1704
|
description: "Analyze speech words, filler markers, and optional VAD for one media item or source range.",
|
|
1250
1705
|
inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
|
|
@@ -1298,18 +1753,81 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1298
1753
|
server.registerTool("edit.diff", {
|
|
1299
1754
|
description: "Read the deterministic diff for a completed edit transaction.",
|
|
1300
1755
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1301
|
-
}, async ({ transactionId }) =>
|
|
1756
|
+
}, async ({ transactionId }) => {
|
|
1757
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1758
|
+
return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
|
|
1759
|
+
});
|
|
1302
1760
|
server.registerTool("edit.verify", {
|
|
1303
1761
|
description: "Read verification checks for a completed transaction.",
|
|
1304
1762
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1305
|
-
}, async ({ transactionId }) =>
|
|
1763
|
+
}, async ({ transactionId }) => {
|
|
1764
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1765
|
+
return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
|
|
1766
|
+
});
|
|
1306
1767
|
server.registerTool("edit.undo", {
|
|
1307
1768
|
description: "Restore the pre-edit snapshot for a completed transaction.",
|
|
1308
1769
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1309
|
-
}, async ({ transactionId }) =>
|
|
1770
|
+
}, async ({ transactionId }) => {
|
|
1771
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1772
|
+
const restored = await runtime.undo(transactionId);
|
|
1773
|
+
const artifact = transaction.target?.kind === "artifact" ? await runtime.inspectArtifact() : undefined;
|
|
1774
|
+
return jsonResult({
|
|
1775
|
+
...restored,
|
|
1776
|
+
...withTransactionProvenance(transaction, restored.revision, artifact?.digest),
|
|
1777
|
+
});
|
|
1778
|
+
});
|
|
1310
1779
|
installMcpSchemaCompatibility(server);
|
|
1311
1780
|
return server;
|
|
1312
1781
|
}
|
|
1782
|
+
function withTransactionProvenance(transaction, revision = transaction.after.revision, digest = transaction.artifactDigest) {
|
|
1783
|
+
const target = transaction.target;
|
|
1784
|
+
const artifact = target?.kind === "artifact"
|
|
1785
|
+
? {
|
|
1786
|
+
mode: "background-artifact",
|
|
1787
|
+
path: target.artifactPath,
|
|
1788
|
+
revisionScope: "artifact",
|
|
1789
|
+
revision: structuredClone(revision),
|
|
1790
|
+
...(digest ? { digest } : {}),
|
|
1791
|
+
mutatesOpenTimeline: false,
|
|
1792
|
+
}
|
|
1793
|
+
: undefined;
|
|
1794
|
+
return {
|
|
1795
|
+
...(target ? { target: structuredClone(target) } : {}),
|
|
1796
|
+
...(artifact ? { artifact } : {}),
|
|
1797
|
+
provenance: {
|
|
1798
|
+
surface: target?.kind === "artifact" ? "artifact" : "live-timeline",
|
|
1799
|
+
revisionScope: target?.kind === "artifact" ? "artifact" : "live-timeline",
|
|
1800
|
+
revision: structuredClone(revision),
|
|
1801
|
+
...(target?.kind === "artifact" && digest ? { digest } : {}),
|
|
1802
|
+
mutatesOpenTimeline: target?.kind !== "artifact",
|
|
1803
|
+
},
|
|
1804
|
+
};
|
|
1805
|
+
}
|
|
1806
|
+
function withArtifactPreviewProvenance(preview) {
|
|
1807
|
+
const target = preview.target;
|
|
1808
|
+
if (target.kind !== "artifact") {
|
|
1809
|
+
throw new Error("INVALID_ARTIFACT_TARGET: preview is not bound to an artifact");
|
|
1810
|
+
}
|
|
1811
|
+
const artifact = {
|
|
1812
|
+
mode: "background-artifact",
|
|
1813
|
+
path: target.artifactPath,
|
|
1814
|
+
revisionScope: "artifact",
|
|
1815
|
+
revision: structuredClone(preview.baseRevision),
|
|
1816
|
+
...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
|
|
1817
|
+
mutatesOpenTimeline: false,
|
|
1818
|
+
};
|
|
1819
|
+
return {
|
|
1820
|
+
...preview,
|
|
1821
|
+
artifact,
|
|
1822
|
+
provenance: {
|
|
1823
|
+
surface: "artifact",
|
|
1824
|
+
revisionScope: "artifact",
|
|
1825
|
+
revision: structuredClone(preview.baseRevision),
|
|
1826
|
+
...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
|
|
1827
|
+
mutatesOpenTimeline: false,
|
|
1828
|
+
},
|
|
1829
|
+
};
|
|
1830
|
+
}
|
|
1313
1831
|
async function resolveNativeTitleAsset(runtime, assetId) {
|
|
1314
1832
|
const assets = await runtime.listAssets();
|
|
1315
1833
|
const asset = assets.find((candidate) => candidate.id === assetId);
|
|
@@ -1319,7 +1837,7 @@ async function resolveNativeTitleAsset(runtime, assetId) {
|
|
|
1319
1837
|
throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
|
|
1320
1838
|
return asset;
|
|
1321
1839
|
}
|
|
1322
|
-
async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
|
|
1840
|
+
async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map(), signal) {
|
|
1323
1841
|
const cachedAsset = nativeTransitionAssets.get(assetId);
|
|
1324
1842
|
if (cachedAsset)
|
|
1325
1843
|
return cachedAsset;
|
|
@@ -1336,7 +1854,7 @@ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nati
|
|
|
1336
1854
|
// transition placement must use the stable identity returned by Final Cut's
|
|
1337
1855
|
// Transitions browser. Resolve registry assets back through native discovery
|
|
1338
1856
|
// instead of fabricating a native identity from the registry id.
|
|
1339
|
-
const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
|
|
1857
|
+
const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId, { signal });
|
|
1340
1858
|
const matchingNativeMatches = asset
|
|
1341
1859
|
? nativeMatches.filter((candidate) => candidate.name === asset.name)
|
|
1342
1860
|
: nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
|
|
@@ -1357,18 +1875,52 @@ async function connectionStatus(options) {
|
|
|
1357
1875
|
capabilities: null,
|
|
1358
1876
|
};
|
|
1359
1877
|
}
|
|
1878
|
+
async function effectiveConnectionStatus(runtime, options) {
|
|
1879
|
+
const status = await connectionStatus(options);
|
|
1880
|
+
const hasConnectionCapabilities = isRuntimeCapabilities(status.capabilities);
|
|
1881
|
+
if (status.state !== "ready" || (options.connectionStatus && !hasConnectionCapabilities)) {
|
|
1882
|
+
return normalizeConnectionStatus(status);
|
|
1883
|
+
}
|
|
1884
|
+
try {
|
|
1885
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1886
|
+
return {
|
|
1887
|
+
...status,
|
|
1888
|
+
identity: inspected.identity,
|
|
1889
|
+
capabilities: inspected.capabilities,
|
|
1890
|
+
preflight: inspected.preflight,
|
|
1891
|
+
};
|
|
1892
|
+
}
|
|
1893
|
+
catch (error) {
|
|
1894
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
1895
|
+
return normalizeConnectionStatus({
|
|
1896
|
+
...status,
|
|
1897
|
+
state: "unavailable",
|
|
1898
|
+
lastError: {
|
|
1899
|
+
code: "CAPABILITY_UNAVAILABLE",
|
|
1900
|
+
message: `effective runtime capability inspection failed: ${message}`,
|
|
1901
|
+
},
|
|
1902
|
+
identity: undefined,
|
|
1903
|
+
capabilities: undefined,
|
|
1904
|
+
preflight: undefined,
|
|
1905
|
+
});
|
|
1906
|
+
}
|
|
1907
|
+
}
|
|
1360
1908
|
async function inspectMcpEditor(runtime, options) {
|
|
1361
1909
|
const inspected = await runtime.inspectEditor();
|
|
1362
1910
|
const native = options.nativeEditor?.capabilities();
|
|
1363
1911
|
const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
|
|
1364
1912
|
const exportAvailable = Boolean(options.videoExporter?.isAvailable());
|
|
1913
|
+
const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
|
|
1365
1914
|
const capabilities = withCapabilityFamilies({
|
|
1366
1915
|
...inspected.capabilities,
|
|
1367
1916
|
editor: {
|
|
1368
1917
|
...inspected.capabilities.editor,
|
|
1369
1918
|
artifactPublish: publishingAvailable,
|
|
1919
|
+
artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
|
|
1370
1920
|
...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
|
|
1371
1921
|
videoExport: exportAvailable,
|
|
1922
|
+
backgroundRender: backgroundExportAvailable,
|
|
1923
|
+
externalRender: false,
|
|
1372
1924
|
},
|
|
1373
1925
|
}, {
|
|
1374
1926
|
backend: inspected.identity.backend,
|
|
@@ -1387,8 +1939,11 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
1387
1939
|
mediaAppend: Boolean(native?.mediaAppend),
|
|
1388
1940
|
mediaInsert: Boolean(native?.mediaInsert),
|
|
1389
1941
|
titlePlacement: Boolean(native?.titlePlacement),
|
|
1942
|
+
titleDiscovery: Boolean(native?.titleDiscovery),
|
|
1943
|
+
pictureInPicture: Boolean(native?.pictureInPicture),
|
|
1390
1944
|
transitionDiscovery: Boolean(native?.transitionDiscovery),
|
|
1391
1945
|
transitionPlacement: Boolean(native?.transitionPlacement),
|
|
1946
|
+
masking: Boolean(native?.masking),
|
|
1392
1947
|
timelineFocus: Boolean(native?.timelineFocus),
|
|
1393
1948
|
projectCreation: false,
|
|
1394
1949
|
clipInsertion: false,
|
|
@@ -1398,17 +1953,50 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
1398
1953
|
publishingBackend: "fcpxml-publisher",
|
|
1399
1954
|
export: exportAvailable,
|
|
1400
1955
|
exportBackend: "final-cut-native-export",
|
|
1956
|
+
backgroundExport: {
|
|
1957
|
+
available: backgroundExportAvailable,
|
|
1958
|
+
backend: "external-renderer",
|
|
1959
|
+
guarantee: backgroundExportAvailable ? "verified" : "none",
|
|
1960
|
+
...(backgroundExportAvailable ? { evidenceTier: "artifact-rendered" } : { unavailableReason: "background rendering is unavailable" }),
|
|
1961
|
+
},
|
|
1962
|
+
backgroundExportBackend: "external-renderer",
|
|
1963
|
+
externalExport: {
|
|
1964
|
+
available: false,
|
|
1965
|
+
backend: "external-renderer",
|
|
1966
|
+
guarantee: "none",
|
|
1967
|
+
unavailableReason: "external rendering is unavailable",
|
|
1968
|
+
},
|
|
1969
|
+
externalExportBackend: "external-renderer",
|
|
1401
1970
|
});
|
|
1402
1971
|
return {
|
|
1403
1972
|
...inspected,
|
|
1404
1973
|
capabilities,
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1974
|
+
workflows: {
|
|
1975
|
+
artifact: {
|
|
1976
|
+
mode: "background-artifact",
|
|
1977
|
+
tools: [...BACKGROUND_ARTIFACT_WORKFLOW],
|
|
1978
|
+
requiresFinalCutFrontmost: false,
|
|
1979
|
+
changesOpenTimeline: false,
|
|
1980
|
+
},
|
|
1981
|
+
},
|
|
1982
|
+
preflight: {
|
|
1983
|
+
...createCapabilityPreflight(inspected.identity, capabilities, {
|
|
1984
|
+
processMode: options.processMode ?? (native ? "headed" : "headless"),
|
|
1985
|
+
nativeWrite: Boolean(native?.selectionEdit),
|
|
1986
|
+
}),
|
|
1987
|
+
fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
|
|
1988
|
+
},
|
|
1409
1989
|
...(native ? { native } : {}),
|
|
1410
1990
|
};
|
|
1411
1991
|
}
|
|
1992
|
+
function requireArtifactTransaction(runtime, transactionId, artifactPath) {
|
|
1993
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1994
|
+
const target = transaction.target;
|
|
1995
|
+
if (target?.kind !== "artifact" || resolvePath(target.artifactPath) !== resolvePath(artifactPath.trim())) {
|
|
1996
|
+
throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not bound to artifact ${artifactPath}`);
|
|
1997
|
+
}
|
|
1998
|
+
return transaction;
|
|
1999
|
+
}
|
|
1412
2000
|
async function requireEditingRoute(runtime, options, operation) {
|
|
1413
2001
|
const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
|
|
1414
2002
|
if (route.status !== "editor-selected") {
|
|
@@ -1416,7 +2004,7 @@ async function requireEditingRoute(runtime, options, operation) {
|
|
|
1416
2004
|
}
|
|
1417
2005
|
}
|
|
1418
2006
|
async function editingRouteContext(runtime, options) {
|
|
1419
|
-
const connection = await
|
|
2007
|
+
const connection = await effectiveConnectionStatus(runtime, options);
|
|
1420
2008
|
let editor;
|
|
1421
2009
|
try {
|
|
1422
2010
|
editor = await inspectMcpEditor(runtime, options);
|