@morshoto/framekit 0.1.6 → 0.1.11
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 +157 -35
- package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
- package/dist-package/adapters/final-cut/typescript/src/connection.js +55 -17
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
- package/dist-package/adapters/final-cut/typescript/src/index.js +10 -0
- package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +16 -6
- 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 +1192 -364
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
- package/dist-package/adapters/final-cut/typescript/src/session.js +163 -17
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +120 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
- package/dist-package/apps/mcp-server/src/main.js +41 -8
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
- package/dist-package/apps/mcp-server/src/routing.js +227 -39
- package/dist-package/apps/mcp-server/src/server.js +642 -97
- package/dist-package/apps/mcp-server/src/version.js +109 -1
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
- package/dist-package/packages/runtime/src/application/project-service.js +46 -7
- package/dist-package/packages/runtime/src/capabilities.js +55 -7
- 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/index.js +1 -0
- package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
- package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
- package/dist-package/packages/runtime/src/editing/intent.js +178 -2
- package/dist-package/packages/runtime/src/index.js +3 -0
- package/dist-package/packages/runtime/src/runtime.js +2 -2
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
- package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
- package/package.json +12 -6
|
@@ -1,9 +1,13 @@
|
|
|
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";
|
|
9
|
+
import { EditingSessionRepository } from "./headless-sessions.js";
|
|
10
|
+
import { SessionMaterializationJobs, } from "./materialization-jobs.js";
|
|
7
11
|
const revisionValueSchema = z.object({
|
|
8
12
|
id: z.string(),
|
|
9
13
|
sequence: z.number().int().nonnegative(),
|
|
@@ -298,6 +302,10 @@ const artifactPublishInputSchema = z.object({
|
|
|
298
302
|
transactionId: z.string().min(1),
|
|
299
303
|
confirm: z.boolean(),
|
|
300
304
|
}).strict();
|
|
305
|
+
const artifactTransactionInputSchema = z.object({
|
|
306
|
+
artifactPath: z.string().trim().min(1),
|
|
307
|
+
transactionId: z.string().min(1),
|
|
308
|
+
}).strict();
|
|
301
309
|
const workflowOperationSchema = z.discriminatedUnion("type", [
|
|
302
310
|
renameClipSchema,
|
|
303
311
|
trimClipSchema,
|
|
@@ -622,11 +630,98 @@ const nativeEditToolInputSchema = z.object({
|
|
|
622
630
|
gainDb: z.number().finite().optional(),
|
|
623
631
|
duration: z.number().nonnegative().optional(),
|
|
624
632
|
}).strict();
|
|
633
|
+
const nativeOperationSessionSubmitSchema = z.object({
|
|
634
|
+
operation: z.literal("disposable.rename-clip"),
|
|
635
|
+
previewToken: z.string().trim().min(1),
|
|
636
|
+
projectId: z.string().trim().min(1),
|
|
637
|
+
sequenceId: z.string().trim().min(1),
|
|
638
|
+
targetIdentity: z.string().trim().min(1),
|
|
639
|
+
baseRevision: revisionValueSchema,
|
|
640
|
+
idempotencyKey: z.string().trim().min(1),
|
|
641
|
+
}).strict();
|
|
642
|
+
const nativeOperationSessionJobSchema = {
|
|
643
|
+
jobId: z.string().trim().min(1),
|
|
644
|
+
};
|
|
625
645
|
function jsonResult(value) {
|
|
626
646
|
return {
|
|
627
647
|
content: [{ type: "text", text: JSON.stringify(value) }],
|
|
628
648
|
};
|
|
629
649
|
}
|
|
650
|
+
async function sessionResult(action) {
|
|
651
|
+
try {
|
|
652
|
+
return jsonResult(await action());
|
|
653
|
+
}
|
|
654
|
+
catch (error) {
|
|
655
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
656
|
+
return {
|
|
657
|
+
isError: true,
|
|
658
|
+
content: [{
|
|
659
|
+
type: "text",
|
|
660
|
+
text: JSON.stringify({ code: message.split(":", 1)[0] || "SESSION_ERROR", message }),
|
|
661
|
+
}],
|
|
662
|
+
};
|
|
663
|
+
}
|
|
664
|
+
}
|
|
665
|
+
function capabilityErrorResult(operation, capabilityName, capability) {
|
|
666
|
+
return {
|
|
667
|
+
isError: true,
|
|
668
|
+
content: [{
|
|
669
|
+
type: "text",
|
|
670
|
+
text: JSON.stringify({
|
|
671
|
+
code: "CAPABILITY_UNAVAILABLE",
|
|
672
|
+
message: `${operation} requires ${capabilityName}`,
|
|
673
|
+
operation,
|
|
674
|
+
capability: capabilityName,
|
|
675
|
+
available: false,
|
|
676
|
+
backend: capability.backend,
|
|
677
|
+
guarantee: capability.guarantee,
|
|
678
|
+
unavailableReason: capability.unavailableReason,
|
|
679
|
+
}),
|
|
680
|
+
}],
|
|
681
|
+
};
|
|
682
|
+
}
|
|
683
|
+
function nativeMediaImportErrorResult(error) {
|
|
684
|
+
const serialized = serializeNativeFinalCutMediaImportError(error);
|
|
685
|
+
if (serialized) {
|
|
686
|
+
return {
|
|
687
|
+
isError: true,
|
|
688
|
+
content: [{ type: "text", text: JSON.stringify(serialized) }],
|
|
689
|
+
};
|
|
690
|
+
}
|
|
691
|
+
if (!isDirectoryMediaImportError(error))
|
|
692
|
+
throw error;
|
|
693
|
+
return {
|
|
694
|
+
isError: true,
|
|
695
|
+
content: [{
|
|
696
|
+
type: "text",
|
|
697
|
+
text: JSON.stringify({
|
|
698
|
+
code: error.code,
|
|
699
|
+
message: error.message,
|
|
700
|
+
guidance: error.guidance,
|
|
701
|
+
}),
|
|
702
|
+
}],
|
|
703
|
+
};
|
|
704
|
+
}
|
|
705
|
+
function capabilityUnavailableErrorResult(error) {
|
|
706
|
+
const serialized = serializeCapabilityUnavailableError(error);
|
|
707
|
+
if (!serialized)
|
|
708
|
+
throw error;
|
|
709
|
+
return {
|
|
710
|
+
isError: true,
|
|
711
|
+
content: [{ type: "text", text: JSON.stringify(serialized) }],
|
|
712
|
+
};
|
|
713
|
+
}
|
|
714
|
+
function isDirectoryMediaImportError(error) {
|
|
715
|
+
if (!error || typeof error !== "object")
|
|
716
|
+
return false;
|
|
717
|
+
const value = error;
|
|
718
|
+
const guidance = value.guidance;
|
|
719
|
+
return value.code === NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE
|
|
720
|
+
&& Boolean(guidance)
|
|
721
|
+
&& typeof guidance === "object"
|
|
722
|
+
&& typeof guidance.previewTool === "string"
|
|
723
|
+
&& typeof guidance.executeTool === "string";
|
|
724
|
+
}
|
|
630
725
|
function skillErrorResult(error) {
|
|
631
726
|
const value = error && typeof error === "object" ? error : {};
|
|
632
727
|
const message = error instanceof Error ? error.message : String(error);
|
|
@@ -665,10 +760,20 @@ function normalizeConnectionStatus(value) {
|
|
|
665
760
|
const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
|
|
666
761
|
return {
|
|
667
762
|
...status,
|
|
668
|
-
capabilities: withCapabilityFamilies(status.capabilities, {
|
|
763
|
+
capabilities: withCanonicalTimelineMode(withCapabilityFamilies(status.capabilities, {
|
|
669
764
|
...(backend ? { backend, connectionBackend: backend } : {}),
|
|
670
765
|
connection: status.state === "ready",
|
|
671
|
-
}),
|
|
766
|
+
})),
|
|
767
|
+
};
|
|
768
|
+
}
|
|
769
|
+
function nativeMediaIntentCapabilities(nativeEditor) {
|
|
770
|
+
const capabilities = nativeEditor?.capabilities();
|
|
771
|
+
return {
|
|
772
|
+
"native.mediaImport": Boolean(capabilities?.mediaImport),
|
|
773
|
+
"native.mediaSelection": Boolean(capabilities?.mediaSelection),
|
|
774
|
+
"native.mediaAppendSelected": Boolean(capabilities?.mediaAppendSelected),
|
|
775
|
+
"native.mediaAppend": Boolean(capabilities?.mediaAppend),
|
|
776
|
+
"native.mediaInsert": Boolean(capabilities?.mediaInsert),
|
|
672
777
|
};
|
|
673
778
|
}
|
|
674
779
|
function isRuntimeCapabilities(value) {
|
|
@@ -699,10 +804,103 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
699
804
|
runtime.registerBuiltinSkills();
|
|
700
805
|
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
701
806
|
const nativeTransitionAssets = new Map();
|
|
807
|
+
const sessions = options.sessionDirectory ? new EditingSessionRepository(options.sessionDirectory) : undefined;
|
|
808
|
+
const materializations = sessions && options.materializationDirectory
|
|
809
|
+
? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
|
|
810
|
+
: undefined;
|
|
811
|
+
const requireSessions = () => {
|
|
812
|
+
if (!sessions)
|
|
813
|
+
throw new Error("SESSION_STORAGE_UNAVAILABLE: configure a session directory");
|
|
814
|
+
return sessions;
|
|
815
|
+
};
|
|
816
|
+
const requireMaterializations = () => {
|
|
817
|
+
if (!materializations)
|
|
818
|
+
throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
|
|
819
|
+
return materializations;
|
|
820
|
+
};
|
|
821
|
+
const sessionOperationSchema = z.array(z.unknown());
|
|
822
|
+
server.registerTool("session.create", {
|
|
823
|
+
description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
|
|
824
|
+
inputSchema: {
|
|
825
|
+
sessionId: z.string().min(1).optional(),
|
|
826
|
+
provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }).optional(),
|
|
827
|
+
base: z.unknown(),
|
|
828
|
+
},
|
|
829
|
+
}, async ({ sessionId, provider, base }) => sessionResult(async () => requireSessions().create({
|
|
830
|
+
...(sessionId ? { sessionId } : {}),
|
|
831
|
+
...(provider ? { provider } : {}),
|
|
832
|
+
base: base,
|
|
833
|
+
})));
|
|
834
|
+
server.registerTool("session.inspect", {
|
|
835
|
+
description: "Inspect a persisted editing session and its exact base and desired Timeline IR.",
|
|
836
|
+
inputSchema: { sessionId: z.string().min(1) },
|
|
837
|
+
}, async ({ sessionId }) => sessionResult(async () => requireSessions().inspect(sessionId)));
|
|
838
|
+
server.registerTool("session.edit.preview", {
|
|
839
|
+
description: "Preview provider-neutral session edits without persisting or mutating Final Cut.",
|
|
840
|
+
inputSchema: {
|
|
841
|
+
sessionId: z.string().min(1),
|
|
842
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
843
|
+
operations: sessionOperationSchema,
|
|
844
|
+
},
|
|
845
|
+
}, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().preview(sessionId, operations, expectedRevision)));
|
|
846
|
+
server.registerTool("session.edit.execute", {
|
|
847
|
+
description: "Apply edits only to a persisted session's desired Timeline IR.",
|
|
848
|
+
inputSchema: {
|
|
849
|
+
sessionId: z.string().min(1),
|
|
850
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
851
|
+
operations: sessionOperationSchema,
|
|
852
|
+
},
|
|
853
|
+
}, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().execute(sessionId, operations, expectedRevision)));
|
|
854
|
+
server.registerTool("session.status", {
|
|
855
|
+
description: "Read editing-session readiness, provider binding, and revisions.",
|
|
856
|
+
inputSchema: { sessionId: z.string().min(1) },
|
|
857
|
+
}, async ({ sessionId }) => sessionResult(async () => requireSessions().status(sessionId)));
|
|
858
|
+
server.registerTool("session.reconcile", {
|
|
859
|
+
description: "Reconcile a fresh provider Timeline IR with the session base and desired state.",
|
|
860
|
+
inputSchema: {
|
|
861
|
+
sessionId: z.string().min(1),
|
|
862
|
+
provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }),
|
|
863
|
+
providerState: z.unknown(),
|
|
864
|
+
},
|
|
865
|
+
}, async ({ sessionId, provider, providerState }) => sessionResult(async () => requireSessions().reconcile(sessionId, provider, providerState)));
|
|
866
|
+
server.registerTool("session.observe", {
|
|
867
|
+
description: "Bind read-only non-canonical Final Cut SQLite evidence to session freshness.",
|
|
868
|
+
inputSchema: { sessionId: z.string().min(1), sourcePath: z.string().min(1) },
|
|
869
|
+
}, async ({ sessionId, sourcePath }) => sessionResult(async () => {
|
|
870
|
+
if (!options.sqliteObservationProvider) {
|
|
871
|
+
throw new Error("FINAL_CUT_SQLITE_INSPECTION_UNAVAILABLE: no read-only observation provider is configured");
|
|
872
|
+
}
|
|
873
|
+
return requireSessions().observe(sessionId, sourcePath, options.sqliteObservationProvider);
|
|
874
|
+
}));
|
|
875
|
+
const sessionMaterializationTargetSchema = z.object({
|
|
876
|
+
provider: z.literal("final-cut"),
|
|
877
|
+
libraryUid: z.string().min(1),
|
|
878
|
+
eventUid: z.string().min(1),
|
|
879
|
+
projectUid: z.string().min(1),
|
|
880
|
+
sequenceUid: z.string().min(1),
|
|
881
|
+
eventName: z.string().min(1).optional(),
|
|
882
|
+
materialization: z.literal("versioned").optional(),
|
|
883
|
+
}).strict();
|
|
884
|
+
server.registerTool("session.materialize.preview", {
|
|
885
|
+
description: "Preview deterministic versioned FCPXML materialization without staging or publishing it.",
|
|
886
|
+
inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema },
|
|
887
|
+
}, async ({ sessionId, target }) => sessionResult(async () => requireMaterializations().preview(sessionId, target)));
|
|
888
|
+
server.registerTool("session.materialize.execute", {
|
|
889
|
+
description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
|
|
890
|
+
inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
|
|
891
|
+
}, async ({ sessionId, target, confirm }) => sessionResult(async () => requireMaterializations().execute(sessionId, target, confirm)));
|
|
892
|
+
server.registerTool("session.materialize.status", {
|
|
893
|
+
description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
|
|
894
|
+
inputSchema: { jobId: z.string().min(1) },
|
|
895
|
+
}, async ({ jobId }) => sessionResult(async () => requireMaterializations().status(jobId)));
|
|
896
|
+
server.registerTool("session.materialize.retry", {
|
|
897
|
+
description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
|
|
898
|
+
inputSchema: { jobId: z.string().min(1) },
|
|
899
|
+
}, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
|
|
702
900
|
server.registerTool("connection.status", {
|
|
703
901
|
description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
|
|
704
902
|
inputSchema: {},
|
|
705
|
-
}, async () => jsonResult(
|
|
903
|
+
}, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
|
|
706
904
|
server.registerTool("skill.list", {
|
|
707
905
|
description: "List registered versioned Framekit Skills with current capability availability.",
|
|
708
906
|
inputSchema: {},
|
|
@@ -766,22 +964,55 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
766
964
|
});
|
|
767
965
|
server.registerTool("project.inspect", {
|
|
768
966
|
description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
|
|
769
|
-
}, async () =>
|
|
967
|
+
}, async () => {
|
|
968
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
969
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
970
|
+
if (!capability.available) {
|
|
971
|
+
return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
|
|
972
|
+
}
|
|
973
|
+
try {
|
|
974
|
+
return jsonResult(await runtime.inspectProject());
|
|
975
|
+
}
|
|
976
|
+
catch (error) {
|
|
977
|
+
return capabilityUnavailableErrorResult(error);
|
|
978
|
+
}
|
|
979
|
+
});
|
|
770
980
|
server.registerTool("artifact.inspect", {
|
|
771
|
-
description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
|
|
981
|
+
description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
|
|
772
982
|
inputSchema: {},
|
|
773
983
|
}, async () => jsonResult(await runtime.inspectArtifact()));
|
|
774
984
|
server.registerTool("project.list", {
|
|
775
985
|
description: "List projects and their stable Final Cut sequence identities, including the active target.",
|
|
776
986
|
inputSchema: {},
|
|
777
|
-
}, async () =>
|
|
987
|
+
}, async () => {
|
|
988
|
+
try {
|
|
989
|
+
return jsonResult(await runtime.listProjects());
|
|
990
|
+
}
|
|
991
|
+
catch (error) {
|
|
992
|
+
const inspectionError = serializeFinalCutLibraryInspectionError(error);
|
|
993
|
+
if (inspectionError) {
|
|
994
|
+
return {
|
|
995
|
+
isError: true,
|
|
996
|
+
content: [{ type: "text", text: JSON.stringify(inspectionError) }],
|
|
997
|
+
};
|
|
998
|
+
}
|
|
999
|
+
return capabilityUnavailableErrorResult(error);
|
|
1000
|
+
}
|
|
1001
|
+
});
|
|
778
1002
|
server.registerTool("project.select", {
|
|
779
1003
|
description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
|
|
780
1004
|
inputSchema: {
|
|
781
1005
|
projectId: z.string().min(1),
|
|
782
1006
|
sequenceId: z.string().min(1).optional(),
|
|
783
1007
|
},
|
|
784
|
-
}, async ({ projectId, sequenceId }) =>
|
|
1008
|
+
}, async ({ projectId, sequenceId }) => {
|
|
1009
|
+
try {
|
|
1010
|
+
return jsonResult(await runtime.selectProject({ projectId, sequenceId }));
|
|
1011
|
+
}
|
|
1012
|
+
catch (error) {
|
|
1013
|
+
return capabilityUnavailableErrorResult(error);
|
|
1014
|
+
}
|
|
1015
|
+
});
|
|
785
1016
|
server.registerTool("editor.inspect", {
|
|
786
1017
|
description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
|
|
787
1018
|
}, async () => {
|
|
@@ -801,12 +1032,20 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
801
1032
|
server.registerTool("editing.intent.resolve", {
|
|
802
1033
|
description: "Map a supported natural-language editing request to one explicit operation without executing it.",
|
|
803
1034
|
inputSchema: { request: z.string().trim().min(1) },
|
|
804
|
-
}, async ({ request }) => jsonResult(resolveEditingIntent(request
|
|
1035
|
+
}, async ({ request }) => jsonResult(resolveEditingIntent(request, {
|
|
1036
|
+
availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
|
|
1037
|
+
})));
|
|
805
1038
|
server.registerTool("editing.route", {
|
|
806
1039
|
description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
|
|
807
1040
|
inputSchema: {
|
|
808
1041
|
operation: z.enum([
|
|
1042
|
+
"project.list",
|
|
1043
|
+
"project.select",
|
|
1044
|
+
"project.inspect",
|
|
1045
|
+
"timeline.inspect",
|
|
1046
|
+
"editor.live.inspect",
|
|
809
1047
|
"timeline.edit",
|
|
1048
|
+
"artifact.edit",
|
|
810
1049
|
"timeline.mask.add",
|
|
811
1050
|
"editor.native.edit",
|
|
812
1051
|
"editor.native.picture-in-picture",
|
|
@@ -826,31 +1065,52 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
826
1065
|
server.registerTool("editor.native.inspect", {
|
|
827
1066
|
description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
|
|
828
1067
|
inputSchema: {},
|
|
829
|
-
}, async () => jsonResult(options.nativeEditor
|
|
830
|
-
? await options.nativeEditor.inspect()
|
|
1068
|
+
}, async (_args, extra) => jsonResult(options.nativeEditor
|
|
1069
|
+
? await options.nativeEditor.inspect({ signal: extra.signal })
|
|
831
1070
|
: { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
|
|
832
1071
|
server.registerTool("editor.native.focus", {
|
|
833
1072
|
description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
|
|
834
1073
|
inputSchema: {},
|
|
835
|
-
}, async () => jsonResult(options.nativeEditor
|
|
836
|
-
? await options.nativeEditor.focusTimeline()
|
|
1074
|
+
}, async (_args, extra) => jsonResult(options.nativeEditor
|
|
1075
|
+
? await options.nativeEditor.focusTimeline({ signal: extra.signal })
|
|
837
1076
|
: { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
|
|
838
1077
|
server.registerTool("editor.native.media.import", {
|
|
839
1078
|
description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
|
|
840
1079
|
inputSchema: { path: z.string().min(1) },
|
|
841
|
-
}, async ({ path }) => {
|
|
1080
|
+
}, async ({ path }, extra) => {
|
|
1081
|
+
if (!options.nativeEditor)
|
|
1082
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
1083
|
+
try {
|
|
1084
|
+
return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
|
|
1085
|
+
}
|
|
1086
|
+
catch (error) {
|
|
1087
|
+
return nativeMediaImportErrorResult(error);
|
|
1088
|
+
}
|
|
1089
|
+
});
|
|
1090
|
+
server.registerTool("editor.native.media.directory.preview", {
|
|
1091
|
+
description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
|
|
1092
|
+
inputSchema: { path: z.string().trim().min(1) },
|
|
1093
|
+
}, async ({ path }, extra) => {
|
|
842
1094
|
if (!options.nativeEditor)
|
|
843
1095
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
844
|
-
return jsonResult(await options.nativeEditor.
|
|
1096
|
+
return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
|
|
1097
|
+
});
|
|
1098
|
+
server.registerTool("editor.native.media.directory.execute", {
|
|
1099
|
+
description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
|
|
1100
|
+
inputSchema: { previewToken: z.string().min(1), confirm: z.literal(true) },
|
|
1101
|
+
}, async ({ previewToken, confirm }, extra) => {
|
|
1102
|
+
if (!options.nativeEditor)
|
|
1103
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
|
|
1104
|
+
return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
|
|
845
1105
|
});
|
|
846
1106
|
server.registerTool("editor.native.edit", {
|
|
847
1107
|
description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
|
|
848
1108
|
inputSchema: nativeEditToolInputSchema,
|
|
849
|
-
}, async (input) => {
|
|
1109
|
+
}, async (input, extra) => {
|
|
850
1110
|
if (!options.nativeEditor)
|
|
851
1111
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
|
|
852
1112
|
const operation = nativeEditSchema.parse(input);
|
|
853
|
-
return jsonResult(await options.nativeEditor.edit(operation));
|
|
1113
|
+
return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
|
|
854
1114
|
});
|
|
855
1115
|
server.registerTool("editor.native.disposable.preview", {
|
|
856
1116
|
description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
|
|
@@ -863,7 +1123,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
863
1123
|
server.registerTool("editor.native.disposable.execute", {
|
|
864
1124
|
description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
|
|
865
1125
|
inputSchema: { previewToken: z.string().min(1) },
|
|
866
|
-
}, async ({ previewToken }) => {
|
|
1126
|
+
}, async ({ previewToken }, extra) => {
|
|
867
1127
|
if (!options.disposableNative)
|
|
868
1128
|
throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
|
|
869
1129
|
return jsonResult(await options.disposableNative.execute(previewToken));
|
|
@@ -876,48 +1136,80 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
876
1136
|
throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
|
|
877
1137
|
return jsonResult(await options.disposableNative.undo(operationId));
|
|
878
1138
|
});
|
|
1139
|
+
server.registerTool("editor.native.operation.submit", {
|
|
1140
|
+
description: "Accept a previewed native Final Cut operation as a resumable job without waiting for headed readiness.",
|
|
1141
|
+
inputSchema: nativeOperationSessionSubmitSchema,
|
|
1142
|
+
}, async (request) => {
|
|
1143
|
+
if (!options.nativeOperationSession)
|
|
1144
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1145
|
+
return jsonResult(await options.nativeOperationSession.submit(request));
|
|
1146
|
+
});
|
|
1147
|
+
server.registerTool("editor.native.operation.status", {
|
|
1148
|
+
description: "Poll a resumable native Final Cut operation for readiness, completion, verification, and restoration evidence.",
|
|
1149
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1150
|
+
}, async ({ jobId }) => {
|
|
1151
|
+
if (!options.nativeOperationSession)
|
|
1152
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1153
|
+
return jsonResult(options.nativeOperationSession.status(jobId));
|
|
1154
|
+
});
|
|
1155
|
+
server.registerTool("editor.native.operation.retry", {
|
|
1156
|
+
description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
|
|
1157
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1158
|
+
}, async ({ jobId }) => {
|
|
1159
|
+
if (!options.nativeOperationSession)
|
|
1160
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1161
|
+
return jsonResult(await options.nativeOperationSession.retry(jobId));
|
|
1162
|
+
});
|
|
1163
|
+
server.registerTool("editor.native.operation.cancel", {
|
|
1164
|
+
description: "Cancel a pending native Final Cut operation or report recovery when mutation has already started.",
|
|
1165
|
+
inputSchema: nativeOperationSessionJobSchema,
|
|
1166
|
+
}, async ({ jobId }) => {
|
|
1167
|
+
if (!options.nativeOperationSession)
|
|
1168
|
+
throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
|
|
1169
|
+
return jsonResult(await options.nativeOperationSession.cancel(jobId));
|
|
1170
|
+
});
|
|
879
1171
|
server.registerTool("editor.native.title.add.preview", {
|
|
880
1172
|
description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
|
|
881
1173
|
inputSchema: nativeTitlePreviewSchema,
|
|
882
|
-
}, async ({ assetId, text, start, duration }) => {
|
|
1174
|
+
}, async ({ assetId, text, start, duration }, extra) => {
|
|
883
1175
|
if (!options.nativeEditor)
|
|
884
1176
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
|
|
885
1177
|
const asset = await resolveNativeTitleAsset(runtime, assetId);
|
|
886
|
-
return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
|
|
1178
|
+
return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }, { signal: extra.signal }));
|
|
887
1179
|
});
|
|
888
1180
|
server.registerTool("editor.native.title.add.execute", {
|
|
889
1181
|
description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
|
|
890
1182
|
inputSchema: { previewToken: z.string().min(1) },
|
|
891
|
-
}, async ({ previewToken }) => {
|
|
1183
|
+
}, async ({ previewToken }, extra) => {
|
|
892
1184
|
if (!options.nativeEditor)
|
|
893
1185
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
|
|
894
|
-
return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
|
|
1186
|
+
return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
|
|
895
1187
|
});
|
|
896
1188
|
server.registerTool("editor.native.picture-in-picture.preview", {
|
|
897
1189
|
description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
|
|
898
1190
|
inputSchema: nativePictureInPicturePreviewSchema,
|
|
899
|
-
}, async (request) => {
|
|
1191
|
+
}, async (request, extra) => {
|
|
900
1192
|
if (!options.nativeEditor)
|
|
901
1193
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
|
|
902
1194
|
await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
|
|
903
|
-
return jsonResult(await options.nativeEditor.previewPictureInPicture(request));
|
|
1195
|
+
return jsonResult(await options.nativeEditor.previewPictureInPicture(request, { signal: extra.signal }));
|
|
904
1196
|
});
|
|
905
1197
|
server.registerTool("editor.native.picture-in-picture.execute", {
|
|
906
1198
|
description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
|
|
907
1199
|
inputSchema: { previewToken: z.string().min(1) },
|
|
908
|
-
}, async ({ previewToken }) => {
|
|
1200
|
+
}, async ({ previewToken }, extra) => {
|
|
909
1201
|
if (!options.nativeEditor)
|
|
910
1202
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
|
|
911
1203
|
await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
|
|
912
|
-
return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken));
|
|
1204
|
+
return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
|
|
913
1205
|
});
|
|
914
1206
|
server.registerTool("editor.native.transition.search", {
|
|
915
1207
|
description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
|
|
916
1208
|
inputSchema: { query: z.string().trim().min(1) },
|
|
917
|
-
}, async ({ query }) => {
|
|
1209
|
+
}, async ({ query }, extra) => {
|
|
918
1210
|
if (!options.nativeEditor)
|
|
919
1211
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
|
|
920
|
-
const matches = await options.nativeEditor.searchTransitions(query);
|
|
1212
|
+
const matches = await options.nativeEditor.searchTransitions(query, { signal: extra.signal });
|
|
921
1213
|
for (const match of matches) {
|
|
922
1214
|
nativeTransitionAssets.set(match.id, match);
|
|
923
1215
|
nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
|
|
@@ -927,176 +1219,220 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
927
1219
|
server.registerTool("editor.native.transition.add.preview", {
|
|
928
1220
|
description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
|
|
929
1221
|
inputSchema: nativeTransitionPreviewSchema,
|
|
930
|
-
}, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
|
|
1222
|
+
}, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }, extra) => {
|
|
931
1223
|
if (!options.nativeEditor)
|
|
932
1224
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
|
|
933
|
-
const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
|
|
1225
|
+
const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets, extra.signal);
|
|
934
1226
|
return jsonResult(await options.nativeEditor.previewTransitionAdd({
|
|
935
1227
|
asset,
|
|
936
1228
|
beforeOccurrenceHandle,
|
|
937
1229
|
afterOccurrenceHandle,
|
|
938
1230
|
duration,
|
|
939
|
-
}));
|
|
1231
|
+
}, { signal: extra.signal }));
|
|
940
1232
|
});
|
|
941
1233
|
server.registerTool("editor.native.transition.add.execute", {
|
|
942
1234
|
description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
|
|
943
1235
|
inputSchema: { previewToken: z.string().min(1) },
|
|
944
|
-
}, async ({ previewToken }) => {
|
|
1236
|
+
}, async ({ previewToken }, extra) => {
|
|
945
1237
|
if (!options.nativeEditor)
|
|
946
1238
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
|
|
947
|
-
return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
|
|
1239
|
+
return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
|
|
948
1240
|
});
|
|
949
1241
|
server.registerTool("editor.native.mask.preview", {
|
|
950
1242
|
description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
|
|
951
1243
|
inputSchema: nativeMaskPreviewSchema,
|
|
952
|
-
}, async ({ occurrenceHandle, mask }) => {
|
|
1244
|
+
}, async ({ occurrenceHandle, mask }, extra) => {
|
|
953
1245
|
if (!options.nativeEditor)
|
|
954
1246
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
|
|
955
|
-
return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }));
|
|
1247
|
+
return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }, { signal: extra.signal }));
|
|
956
1248
|
});
|
|
957
1249
|
server.registerTool("editor.native.mask.execute", {
|
|
958
1250
|
description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
|
|
959
1251
|
inputSchema: { previewToken: z.string().trim().min(1) },
|
|
960
|
-
}, async ({ previewToken }) => {
|
|
1252
|
+
}, async ({ previewToken }, extra) => {
|
|
961
1253
|
if (!options.nativeEditor)
|
|
962
1254
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
|
|
963
|
-
return jsonResult(await options.nativeEditor.executeMask(previewToken));
|
|
1255
|
+
return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
|
|
964
1256
|
});
|
|
965
1257
|
server.registerTool("editor.native.undo", {
|
|
966
1258
|
description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
|
|
967
1259
|
inputSchema: { operationId: z.string().min(1) },
|
|
968
|
-
}, async ({ operationId }) => {
|
|
1260
|
+
}, async ({ operationId }, extra) => {
|
|
969
1261
|
if (!options.nativeEditor)
|
|
970
1262
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
|
|
971
|
-
return jsonResult(await options.nativeEditor.undo(operationId));
|
|
1263
|
+
return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
|
|
972
1264
|
});
|
|
973
1265
|
server.registerTool("editor.native.media.search", {
|
|
974
1266
|
description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
|
|
975
1267
|
inputSchema: { query: z.string().min(1) },
|
|
976
|
-
}, async ({ query }) => {
|
|
1268
|
+
}, async ({ query }, extra) => {
|
|
977
1269
|
if (!options.nativeEditor)
|
|
978
1270
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
|
|
979
|
-
return jsonResult(await options.nativeEditor.searchMedia(query));
|
|
1271
|
+
return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
|
|
980
1272
|
});
|
|
981
1273
|
server.registerTool("editor.native.media.select", {
|
|
982
1274
|
description: "Select one live Final Cut Browser media result using its short-lived handle.",
|
|
983
1275
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
984
|
-
}, async ({ mediaHandle }) => {
|
|
1276
|
+
}, async ({ mediaHandle }, extra) => {
|
|
985
1277
|
if (!options.nativeEditor)
|
|
986
1278
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
|
|
987
|
-
return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
|
|
1279
|
+
return jsonResult(await options.nativeEditor.selectMedia(mediaHandle, { signal: extra.signal }));
|
|
988
1280
|
});
|
|
989
1281
|
server.registerTool("editor.native.media.append.preview", {
|
|
990
1282
|
description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
|
|
991
1283
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
992
|
-
}, async ({ mediaHandle }) => {
|
|
1284
|
+
}, async ({ mediaHandle }, extra) => {
|
|
993
1285
|
if (!options.nativeEditor)
|
|
994
1286
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
|
|
995
|
-
return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
|
|
1287
|
+
return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle, { signal: extra.signal }));
|
|
996
1288
|
});
|
|
997
1289
|
server.registerTool("editor.native.media.append.execute", {
|
|
998
1290
|
description: "Execute a previously previewed append of selected Final Cut Browser media.",
|
|
999
1291
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1000
|
-
}, async ({ previewToken }) => {
|
|
1292
|
+
}, async ({ previewToken }, extra) => {
|
|
1001
1293
|
if (!options.nativeEditor)
|
|
1002
1294
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
|
|
1003
|
-
return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
|
|
1295
|
+
return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
|
|
1004
1296
|
});
|
|
1005
1297
|
server.registerTool("editor.native.media.append.selected.preview", {
|
|
1006
1298
|
description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
|
|
1007
1299
|
inputSchema: {},
|
|
1008
|
-
}, async () => {
|
|
1300
|
+
}, async (_args, extra) => {
|
|
1009
1301
|
if (!options.nativeEditor)
|
|
1010
1302
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
|
|
1011
|
-
return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
|
|
1303
|
+
return jsonResult(await options.nativeEditor.previewAppendSelectedMedia({ signal: extra.signal }));
|
|
1012
1304
|
});
|
|
1013
1305
|
server.registerTool("editor.native.media.append.selected.execute", {
|
|
1014
1306
|
description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
|
|
1015
1307
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1016
|
-
}, async ({ previewToken }) => {
|
|
1308
|
+
}, async ({ previewToken }, extra) => {
|
|
1017
1309
|
if (!options.nativeEditor)
|
|
1018
1310
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
|
|
1019
|
-
return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
|
|
1311
|
+
return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
|
|
1020
1312
|
});
|
|
1021
1313
|
server.registerTool("editor.native.media.insert.preview", {
|
|
1022
1314
|
description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
|
|
1023
1315
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
1024
|
-
}, async ({ mediaHandle }) => {
|
|
1316
|
+
}, async ({ mediaHandle }, extra) => {
|
|
1025
1317
|
if (!options.nativeEditor)
|
|
1026
1318
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
|
|
1027
|
-
return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
|
|
1319
|
+
return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle, { signal: extra.signal }));
|
|
1028
1320
|
});
|
|
1029
1321
|
server.registerTool("editor.native.media.insert.execute", {
|
|
1030
1322
|
description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
|
|
1031
1323
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1032
|
-
}, async ({ previewToken }) => {
|
|
1324
|
+
}, async ({ previewToken }, extra) => {
|
|
1033
1325
|
if (!options.nativeEditor)
|
|
1034
1326
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
|
|
1035
|
-
return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
|
|
1327
|
+
return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
|
|
1036
1328
|
});
|
|
1037
1329
|
server.registerTool("editor.native.timeline.locate", {
|
|
1038
1330
|
description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
|
|
1039
1331
|
inputSchema: { mediaHandle: z.string().min(1) },
|
|
1040
|
-
}, async ({ mediaHandle }) => {
|
|
1332
|
+
}, async ({ mediaHandle }, extra) => {
|
|
1041
1333
|
if (!options.nativeEditor)
|
|
1042
1334
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
|
|
1043
|
-
return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
|
|
1335
|
+
return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle, { signal: extra.signal }));
|
|
1044
1336
|
});
|
|
1045
1337
|
server.registerTool("editor.native.media.target", {
|
|
1046
1338
|
description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
|
|
1047
1339
|
inputSchema: { query: z.string().min(1) },
|
|
1048
|
-
}, async ({ query }) => {
|
|
1340
|
+
}, async ({ query }, extra) => {
|
|
1049
1341
|
if (!options.nativeEditor)
|
|
1050
1342
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
|
|
1051
|
-
return jsonResult(await options.nativeEditor.targetMedia(query));
|
|
1343
|
+
return jsonResult(await options.nativeEditor.targetMedia(query, { signal: extra.signal }));
|
|
1052
1344
|
});
|
|
1053
1345
|
server.registerTool("editor.native.blade.preview", {
|
|
1054
1346
|
description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
|
|
1055
1347
|
inputSchema: { occurrenceHandle: z.string().min(1) },
|
|
1056
|
-
}, async ({ occurrenceHandle }) => {
|
|
1348
|
+
}, async ({ occurrenceHandle }, extra) => {
|
|
1057
1349
|
if (!options.nativeEditor)
|
|
1058
1350
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
|
|
1059
|
-
return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
|
|
1351
|
+
return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle, { signal: extra.signal }));
|
|
1060
1352
|
});
|
|
1061
1353
|
server.registerTool("editor.native.blade.execute", {
|
|
1062
1354
|
description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
|
|
1063
1355
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1064
|
-
}, async ({ previewToken }) => {
|
|
1356
|
+
}, async ({ previewToken }, extra) => {
|
|
1065
1357
|
if (!options.nativeEditor)
|
|
1066
1358
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
|
|
1067
|
-
return jsonResult(await options.nativeEditor.executeBlade(previewToken));
|
|
1359
|
+
return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
|
|
1068
1360
|
});
|
|
1069
1361
|
server.registerTool("editor.native.delete-range.preview", {
|
|
1070
1362
|
description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
|
|
1071
1363
|
inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
|
|
1072
|
-
}, async ({ start, end }) => {
|
|
1364
|
+
}, async ({ start, end }, extra) => {
|
|
1073
1365
|
if (!options.nativeEditor)
|
|
1074
1366
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
|
|
1075
|
-
return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
|
|
1367
|
+
return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }, { signal: extra.signal }));
|
|
1076
1368
|
});
|
|
1077
1369
|
server.registerTool("editor.native.delete-range.execute", {
|
|
1078
1370
|
description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
|
|
1079
1371
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1080
|
-
}, async ({ previewToken }) => {
|
|
1372
|
+
}, async ({ previewToken }, extra) => {
|
|
1081
1373
|
if (!options.nativeEditor)
|
|
1082
1374
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
|
|
1083
|
-
return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
|
|
1375
|
+
return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
|
|
1084
1376
|
});
|
|
1085
1377
|
server.registerTool("editor.native.trim-to-duration.preview", {
|
|
1086
1378
|
description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
|
|
1087
1379
|
inputSchema: { duration: rationalTimeSchema },
|
|
1088
|
-
}, async ({ duration }) => {
|
|
1380
|
+
}, async ({ duration }, extra) => {
|
|
1089
1381
|
if (!options.nativeEditor)
|
|
1090
1382
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
|
|
1091
|
-
return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
|
|
1383
|
+
return jsonResult(await options.nativeEditor.previewTrimToDuration(duration, { signal: extra.signal }));
|
|
1092
1384
|
});
|
|
1093
1385
|
server.registerTool("editor.native.trim-to-duration.execute", {
|
|
1094
1386
|
description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
|
|
1095
1387
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1096
|
-
}, async ({ previewToken }) => {
|
|
1388
|
+
}, async ({ previewToken }, extra) => {
|
|
1097
1389
|
if (!options.nativeEditor)
|
|
1098
1390
|
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
|
|
1099
|
-
return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
|
|
1391
|
+
return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
|
|
1392
|
+
});
|
|
1393
|
+
server.registerTool("artifact.publish.preview", {
|
|
1394
|
+
description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
|
|
1395
|
+
inputSchema: {
|
|
1396
|
+
artifactPath: z.string().trim().min(1),
|
|
1397
|
+
transactionId: z.string().min(1),
|
|
1398
|
+
},
|
|
1399
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1400
|
+
if (!options.projectPublisher)
|
|
1401
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1402
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1403
|
+
if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
|
|
1404
|
+
throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
|
|
1405
|
+
}
|
|
1406
|
+
if (!transaction.artifactDigest) {
|
|
1407
|
+
throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
|
|
1408
|
+
}
|
|
1409
|
+
const verification = await runtime.verifyTransaction(transactionId);
|
|
1410
|
+
if (!verification.passed)
|
|
1411
|
+
throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
|
|
1412
|
+
return jsonResult(await options.projectPublisher.preparePublish({
|
|
1413
|
+
sourceTransactionId: transactionId,
|
|
1414
|
+
artifactPath,
|
|
1415
|
+
artifactDigest: transaction.artifactDigest,
|
|
1416
|
+
}));
|
|
1417
|
+
});
|
|
1418
|
+
server.registerTool("artifact.publish.execute", {
|
|
1419
|
+
description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
|
|
1420
|
+
inputSchema: {
|
|
1421
|
+
jobId: z.string().trim().min(1),
|
|
1422
|
+
confirm: z.literal(true),
|
|
1423
|
+
},
|
|
1424
|
+
}, async ({ jobId, confirm }) => {
|
|
1425
|
+
if (!options.projectPublisher)
|
|
1426
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1427
|
+
return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
|
|
1428
|
+
});
|
|
1429
|
+
server.registerTool("artifact.publish.status", {
|
|
1430
|
+
description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
|
|
1431
|
+
inputSchema: { jobId: z.string().trim().min(1) },
|
|
1432
|
+
}, async ({ jobId }) => {
|
|
1433
|
+
if (!options.projectPublisher)
|
|
1434
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
|
|
1435
|
+
return jsonResult(options.projectPublisher.getPublishJob(jobId));
|
|
1100
1436
|
});
|
|
1101
1437
|
server.registerTool("artifact.publish", {
|
|
1102
1438
|
description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
|
|
@@ -1221,9 +1557,21 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1221
1557
|
timestamp: new Date(sequence).toISOString(),
|
|
1222
1558
|
}, waitMs ?? 0)));
|
|
1223
1559
|
server.registerTool("editor.live.inspect", {
|
|
1224
|
-
description: "Read live Final Cut
|
|
1560
|
+
description: "Read observed live Final Cut state without requiring canonical timeline snapshot capability.",
|
|
1225
1561
|
inputSchema: {},
|
|
1226
|
-
}, async () =>
|
|
1562
|
+
}, async () => {
|
|
1563
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1564
|
+
const capability = inspected.capabilities.families.observation.timeline;
|
|
1565
|
+
if (!capability.available) {
|
|
1566
|
+
return capabilityErrorResult("editor.live.inspect", "observation.timeline", capability);
|
|
1567
|
+
}
|
|
1568
|
+
try {
|
|
1569
|
+
return jsonResult(await runtime.inspectLiveEditor());
|
|
1570
|
+
}
|
|
1571
|
+
catch (error) {
|
|
1572
|
+
return capabilityUnavailableErrorResult(error);
|
|
1573
|
+
}
|
|
1574
|
+
});
|
|
1227
1575
|
server.registerTool("editor.live.changes", {
|
|
1228
1576
|
description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
|
|
1229
1577
|
inputSchema: {
|
|
@@ -1236,8 +1584,20 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1236
1584
|
timestamp: new Date(sequence).toISOString(),
|
|
1237
1585
|
}, waitMs ?? 0)));
|
|
1238
1586
|
server.registerTool("timeline.inspect", {
|
|
1239
|
-
description: "Read the current canonical timeline snapshot.",
|
|
1240
|
-
}, async () =>
|
|
1587
|
+
description: "Read the current canonical timeline snapshot after canonical capability checks.",
|
|
1588
|
+
}, async () => {
|
|
1589
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1590
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1591
|
+
if (!capability.available) {
|
|
1592
|
+
return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
|
|
1593
|
+
}
|
|
1594
|
+
try {
|
|
1595
|
+
return jsonResult(await runtime.inspectTimeline());
|
|
1596
|
+
}
|
|
1597
|
+
catch (error) {
|
|
1598
|
+
return capabilityUnavailableErrorResult(error);
|
|
1599
|
+
}
|
|
1600
|
+
});
|
|
1241
1601
|
server.registerTool("timeline.frame.capture", {
|
|
1242
1602
|
description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
|
|
1243
1603
|
inputSchema: {
|
|
@@ -1252,7 +1612,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1252
1612
|
server.registerTool("media.search", {
|
|
1253
1613
|
description: "Search normalized media references by id or source path.",
|
|
1254
1614
|
inputSchema: { query: z.string() },
|
|
1255
|
-
}, async ({ query }) =>
|
|
1615
|
+
}, async ({ query }) => {
|
|
1616
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1617
|
+
const capability = inspected.capabilities.families.observation.media;
|
|
1618
|
+
if (!capability.available) {
|
|
1619
|
+
return capabilityErrorResult("media.search", "observation.media", capability);
|
|
1620
|
+
}
|
|
1621
|
+
try {
|
|
1622
|
+
return jsonResult(await runtime.searchMedia(query));
|
|
1623
|
+
}
|
|
1624
|
+
catch (error) {
|
|
1625
|
+
return capabilityUnavailableErrorResult(error);
|
|
1626
|
+
}
|
|
1627
|
+
});
|
|
1256
1628
|
server.registerTool("media.index", {
|
|
1257
1629
|
description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
|
|
1258
1630
|
inputSchema: mediaIndexQuerySchema.shape,
|
|
@@ -1273,11 +1645,12 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1273
1645
|
inputSchema: roughCutPlanSchema.shape,
|
|
1274
1646
|
}, async (request) => jsonResult(await runtime.planRoughCut(request)));
|
|
1275
1647
|
server.registerTool("editor.assets", {
|
|
1276
|
-
description: "Search
|
|
1648
|
+
description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
|
|
1277
1649
|
inputSchema: {
|
|
1278
1650
|
query: z.string().optional(),
|
|
1279
1651
|
kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
|
|
1280
1652
|
vendor: z.string().optional(),
|
|
1653
|
+
discovery: z.enum(["background", "native", "all"]).optional().default("background"),
|
|
1281
1654
|
},
|
|
1282
1655
|
}, async (query) => jsonResult(await runtime.listAssets(query)));
|
|
1283
1656
|
server.registerTool("timeline.changes", {
|
|
@@ -1307,16 +1680,19 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1307
1680
|
inputSchema: roughCutConstructionPlanInputSchema,
|
|
1308
1681
|
}, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
|
|
1309
1682
|
server.registerTool("artifact.edit", {
|
|
1310
|
-
description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
|
|
1683
|
+
description: "Edit the identified managed FCPXML artifact in the background and return its artifact target, new revision, read-after-write, and diff.",
|
|
1311
1684
|
inputSchema: artifactEditToolInputSchema,
|
|
1312
1685
|
}, async (input) => {
|
|
1686
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1313
1687
|
const { artifactPath, verification, ...operation } = input;
|
|
1314
|
-
|
|
1688
|
+
const transaction = await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {});
|
|
1689
|
+
return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
|
|
1315
1690
|
});
|
|
1316
1691
|
server.registerTool("editor.timeline.edit", {
|
|
1317
1692
|
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.",
|
|
1318
1693
|
inputSchema: editorTimelineEditToolInputSchema,
|
|
1319
1694
|
}, async (input) => {
|
|
1695
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1320
1696
|
const { projectId, sequenceId, verification, ...operation } = input;
|
|
1321
1697
|
return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
|
|
1322
1698
|
});
|
|
@@ -1355,14 +1731,17 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1355
1731
|
}));
|
|
1356
1732
|
});
|
|
1357
1733
|
server.registerTool("artifact.edit.preview", {
|
|
1358
|
-
description: "Validate and preview an ordered artifact edit
|
|
1734
|
+
description: "Validate and preview an ordered background FCPXML artifact edit without mutating it or the open Final Cut timeline.",
|
|
1359
1735
|
inputSchema: {
|
|
1360
1736
|
artifactPath: z.string().trim().min(1),
|
|
1361
1737
|
baseRevision: revisionValueSchema,
|
|
1362
1738
|
operations: workflowOperationsSchema,
|
|
1363
1739
|
verification: verificationPolicySchema.optional(),
|
|
1364
1740
|
},
|
|
1365
|
-
}, async ({ artifactPath, baseRevision, operations, verification }) =>
|
|
1741
|
+
}, async ({ artifactPath, baseRevision, operations, verification }) => {
|
|
1742
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1743
|
+
return jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) }).then(withArtifactPreviewProvenance));
|
|
1744
|
+
});
|
|
1366
1745
|
server.registerTool("editor.timeline.edit.preview", {
|
|
1367
1746
|
description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
|
|
1368
1747
|
inputSchema: {
|
|
@@ -1372,15 +1751,51 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1372
1751
|
operations: workflowOperationsSchema,
|
|
1373
1752
|
verification: verificationPolicySchema.optional(),
|
|
1374
1753
|
},
|
|
1375
|
-
}, async ({ projectId, sequenceId, baseRevision, operations, verification }) =>
|
|
1754
|
+
}, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
|
|
1755
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1756
|
+
return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
|
|
1757
|
+
});
|
|
1376
1758
|
server.registerTool("artifact.edit.execute", {
|
|
1377
|
-
description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
|
|
1759
|
+
description: "Execute one short-lived background artifact edit preview token exactly once and verify the FCPXML artifact transaction.",
|
|
1378
1760
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1379
|
-
}, async ({ previewToken }) =>
|
|
1761
|
+
}, async ({ previewToken }) => {
|
|
1762
|
+
await requireEditingRoute(runtime, options, "artifact.edit");
|
|
1763
|
+
const transaction = await runtime.executeEdit(previewToken);
|
|
1764
|
+
return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
|
|
1765
|
+
});
|
|
1766
|
+
server.registerTool("artifact.edit.diff", {
|
|
1767
|
+
description: "Read the deterministic diff for a background FCPXML artifact transaction.",
|
|
1768
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1769
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1770
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1771
|
+
return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
|
|
1772
|
+
});
|
|
1773
|
+
server.registerTool("artifact.edit.verify", {
|
|
1774
|
+
description: "Read verification checks for a background FCPXML artifact transaction.",
|
|
1775
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1776
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1777
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1778
|
+
return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
|
|
1779
|
+
});
|
|
1780
|
+
server.registerTool("artifact.edit.undo", {
|
|
1781
|
+
description: "Restore a background FCPXML artifact transaction without changing the open Final Cut timeline.",
|
|
1782
|
+
inputSchema: artifactTransactionInputSchema,
|
|
1783
|
+
}, async ({ artifactPath, transactionId }) => {
|
|
1784
|
+
const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
|
|
1785
|
+
const restored = await runtime.undo(transactionId);
|
|
1786
|
+
const artifact = await runtime.inspectArtifact();
|
|
1787
|
+
return jsonResult({
|
|
1788
|
+
...restored,
|
|
1789
|
+
...withTransactionProvenance(transaction, restored.revision, artifact.digest),
|
|
1790
|
+
});
|
|
1791
|
+
});
|
|
1380
1792
|
server.registerTool("editor.timeline.edit.execute", {
|
|
1381
1793
|
description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
|
|
1382
1794
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1383
|
-
}, async ({ previewToken }) =>
|
|
1795
|
+
}, async ({ previewToken }) => {
|
|
1796
|
+
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
1797
|
+
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1798
|
+
});
|
|
1384
1799
|
server.registerTool("timeline.edit.execute", {
|
|
1385
1800
|
description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
|
|
1386
1801
|
inputSchema: { previewToken: z.string().min(1) },
|
|
@@ -1448,18 +1863,81 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1448
1863
|
server.registerTool("edit.diff", {
|
|
1449
1864
|
description: "Read the deterministic diff for a completed edit transaction.",
|
|
1450
1865
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1451
|
-
}, async ({ transactionId }) =>
|
|
1866
|
+
}, async ({ transactionId }) => {
|
|
1867
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1868
|
+
return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
|
|
1869
|
+
});
|
|
1452
1870
|
server.registerTool("edit.verify", {
|
|
1453
1871
|
description: "Read verification checks for a completed transaction.",
|
|
1454
1872
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1455
|
-
}, async ({ transactionId }) =>
|
|
1873
|
+
}, async ({ transactionId }) => {
|
|
1874
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1875
|
+
return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
|
|
1876
|
+
});
|
|
1456
1877
|
server.registerTool("edit.undo", {
|
|
1457
1878
|
description: "Restore the pre-edit snapshot for a completed transaction.",
|
|
1458
1879
|
inputSchema: { transactionId: z.string().min(1) },
|
|
1459
|
-
}, async ({ transactionId }) =>
|
|
1880
|
+
}, async ({ transactionId }) => {
|
|
1881
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
1882
|
+
const restored = await runtime.undo(transactionId);
|
|
1883
|
+
const artifact = transaction.target?.kind === "artifact" ? await runtime.inspectArtifact() : undefined;
|
|
1884
|
+
return jsonResult({
|
|
1885
|
+
...restored,
|
|
1886
|
+
...withTransactionProvenance(transaction, restored.revision, artifact?.digest),
|
|
1887
|
+
});
|
|
1888
|
+
});
|
|
1460
1889
|
installMcpSchemaCompatibility(server);
|
|
1461
1890
|
return server;
|
|
1462
1891
|
}
|
|
1892
|
+
function withTransactionProvenance(transaction, revision = transaction.after.revision, digest = transaction.artifactDigest) {
|
|
1893
|
+
const target = transaction.target;
|
|
1894
|
+
const artifact = target?.kind === "artifact"
|
|
1895
|
+
? {
|
|
1896
|
+
mode: "background-artifact",
|
|
1897
|
+
path: target.artifactPath,
|
|
1898
|
+
revisionScope: "artifact",
|
|
1899
|
+
revision: structuredClone(revision),
|
|
1900
|
+
...(digest ? { digest } : {}),
|
|
1901
|
+
mutatesOpenTimeline: false,
|
|
1902
|
+
}
|
|
1903
|
+
: undefined;
|
|
1904
|
+
return {
|
|
1905
|
+
...(target ? { target: structuredClone(target) } : {}),
|
|
1906
|
+
...(artifact ? { artifact } : {}),
|
|
1907
|
+
provenance: {
|
|
1908
|
+
surface: target?.kind === "artifact" ? "artifact" : "live-timeline",
|
|
1909
|
+
revisionScope: target?.kind === "artifact" ? "artifact" : "live-timeline",
|
|
1910
|
+
revision: structuredClone(revision),
|
|
1911
|
+
...(target?.kind === "artifact" && digest ? { digest } : {}),
|
|
1912
|
+
mutatesOpenTimeline: target?.kind !== "artifact",
|
|
1913
|
+
},
|
|
1914
|
+
};
|
|
1915
|
+
}
|
|
1916
|
+
function withArtifactPreviewProvenance(preview) {
|
|
1917
|
+
const target = preview.target;
|
|
1918
|
+
if (target.kind !== "artifact") {
|
|
1919
|
+
throw new Error("INVALID_ARTIFACT_TARGET: preview is not bound to an artifact");
|
|
1920
|
+
}
|
|
1921
|
+
const artifact = {
|
|
1922
|
+
mode: "background-artifact",
|
|
1923
|
+
path: target.artifactPath,
|
|
1924
|
+
revisionScope: "artifact",
|
|
1925
|
+
revision: structuredClone(preview.baseRevision),
|
|
1926
|
+
...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
|
|
1927
|
+
mutatesOpenTimeline: false,
|
|
1928
|
+
};
|
|
1929
|
+
return {
|
|
1930
|
+
...preview,
|
|
1931
|
+
artifact,
|
|
1932
|
+
provenance: {
|
|
1933
|
+
surface: "artifact",
|
|
1934
|
+
revisionScope: "artifact",
|
|
1935
|
+
revision: structuredClone(preview.baseRevision),
|
|
1936
|
+
...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
|
|
1937
|
+
mutatesOpenTimeline: false,
|
|
1938
|
+
},
|
|
1939
|
+
};
|
|
1940
|
+
}
|
|
1463
1941
|
async function resolveNativeTitleAsset(runtime, assetId) {
|
|
1464
1942
|
const assets = await runtime.listAssets();
|
|
1465
1943
|
const asset = assets.find((candidate) => candidate.id === assetId);
|
|
@@ -1469,7 +1947,7 @@ async function resolveNativeTitleAsset(runtime, assetId) {
|
|
|
1469
1947
|
throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
|
|
1470
1948
|
return asset;
|
|
1471
1949
|
}
|
|
1472
|
-
async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
|
|
1950
|
+
async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map(), signal) {
|
|
1473
1951
|
const cachedAsset = nativeTransitionAssets.get(assetId);
|
|
1474
1952
|
if (cachedAsset)
|
|
1475
1953
|
return cachedAsset;
|
|
@@ -1486,7 +1964,7 @@ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nati
|
|
|
1486
1964
|
// transition placement must use the stable identity returned by Final Cut's
|
|
1487
1965
|
// Transitions browser. Resolve registry assets back through native discovery
|
|
1488
1966
|
// instead of fabricating a native identity from the registry id.
|
|
1489
|
-
const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
|
|
1967
|
+
const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId, { signal });
|
|
1490
1968
|
const matchingNativeMatches = asset
|
|
1491
1969
|
? nativeMatches.filter((candidate) => candidate.name === asset.name)
|
|
1492
1970
|
: nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
|
|
@@ -1507,18 +1985,52 @@ async function connectionStatus(options) {
|
|
|
1507
1985
|
capabilities: null,
|
|
1508
1986
|
};
|
|
1509
1987
|
}
|
|
1988
|
+
async function effectiveConnectionStatus(runtime, options) {
|
|
1989
|
+
const status = await connectionStatus(options);
|
|
1990
|
+
const hasConnectionCapabilities = isRuntimeCapabilities(status.capabilities);
|
|
1991
|
+
if (status.state !== "ready" || (options.connectionStatus && !hasConnectionCapabilities)) {
|
|
1992
|
+
return normalizeConnectionStatus(status);
|
|
1993
|
+
}
|
|
1994
|
+
try {
|
|
1995
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1996
|
+
return {
|
|
1997
|
+
...status,
|
|
1998
|
+
identity: inspected.identity,
|
|
1999
|
+
capabilities: inspected.capabilities,
|
|
2000
|
+
preflight: inspected.preflight,
|
|
2001
|
+
};
|
|
2002
|
+
}
|
|
2003
|
+
catch (error) {
|
|
2004
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
2005
|
+
return normalizeConnectionStatus({
|
|
2006
|
+
...status,
|
|
2007
|
+
state: "unavailable",
|
|
2008
|
+
lastError: {
|
|
2009
|
+
code: "CAPABILITY_UNAVAILABLE",
|
|
2010
|
+
message: `effective runtime capability inspection failed: ${message}`,
|
|
2011
|
+
},
|
|
2012
|
+
identity: undefined,
|
|
2013
|
+
capabilities: undefined,
|
|
2014
|
+
preflight: undefined,
|
|
2015
|
+
});
|
|
2016
|
+
}
|
|
2017
|
+
}
|
|
1510
2018
|
async function inspectMcpEditor(runtime, options) {
|
|
1511
2019
|
const inspected = await runtime.inspectEditor();
|
|
1512
2020
|
const native = options.nativeEditor?.capabilities();
|
|
1513
2021
|
const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
|
|
1514
2022
|
const exportAvailable = Boolean(options.videoExporter?.isAvailable());
|
|
2023
|
+
const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
|
|
1515
2024
|
const capabilities = withCapabilityFamilies({
|
|
1516
2025
|
...inspected.capabilities,
|
|
1517
2026
|
editor: {
|
|
1518
2027
|
...inspected.capabilities.editor,
|
|
1519
2028
|
artifactPublish: publishingAvailable,
|
|
2029
|
+
artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
|
|
1520
2030
|
...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
|
|
1521
2031
|
videoExport: exportAvailable,
|
|
2032
|
+
backgroundRender: backgroundExportAvailable,
|
|
2033
|
+
externalRender: false,
|
|
1522
2034
|
},
|
|
1523
2035
|
}, {
|
|
1524
2036
|
backend: inspected.identity.backend,
|
|
@@ -1551,17 +2063,50 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
1551
2063
|
publishingBackend: "fcpxml-publisher",
|
|
1552
2064
|
export: exportAvailable,
|
|
1553
2065
|
exportBackend: "final-cut-native-export",
|
|
2066
|
+
backgroundExport: {
|
|
2067
|
+
available: backgroundExportAvailable,
|
|
2068
|
+
backend: "external-renderer",
|
|
2069
|
+
guarantee: backgroundExportAvailable ? "verified" : "none",
|
|
2070
|
+
...(backgroundExportAvailable ? { evidenceTier: "artifact-rendered" } : { unavailableReason: "background rendering is unavailable" }),
|
|
2071
|
+
},
|
|
2072
|
+
backgroundExportBackend: "external-renderer",
|
|
2073
|
+
externalExport: {
|
|
2074
|
+
available: false,
|
|
2075
|
+
backend: "external-renderer",
|
|
2076
|
+
guarantee: "none",
|
|
2077
|
+
unavailableReason: "external rendering is unavailable",
|
|
2078
|
+
},
|
|
2079
|
+
externalExportBackend: "external-renderer",
|
|
1554
2080
|
});
|
|
1555
2081
|
return {
|
|
1556
2082
|
...inspected,
|
|
1557
2083
|
capabilities,
|
|
1558
|
-
|
|
1559
|
-
|
|
1560
|
-
|
|
1561
|
-
|
|
2084
|
+
workflows: {
|
|
2085
|
+
artifact: {
|
|
2086
|
+
mode: "background-artifact",
|
|
2087
|
+
tools: [...BACKGROUND_ARTIFACT_WORKFLOW],
|
|
2088
|
+
requiresFinalCutFrontmost: false,
|
|
2089
|
+
changesOpenTimeline: false,
|
|
2090
|
+
},
|
|
2091
|
+
},
|
|
2092
|
+
preflight: {
|
|
2093
|
+
...createCapabilityPreflight(inspected.identity, capabilities, {
|
|
2094
|
+
processMode: options.processMode ?? (native ? "headed" : "headless"),
|
|
2095
|
+
nativeWrite: Boolean(native?.selectionEdit),
|
|
2096
|
+
}),
|
|
2097
|
+
fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
|
|
2098
|
+
},
|
|
1562
2099
|
...(native ? { native } : {}),
|
|
1563
2100
|
};
|
|
1564
2101
|
}
|
|
2102
|
+
function requireArtifactTransaction(runtime, transactionId, artifactPath) {
|
|
2103
|
+
const transaction = runtime.getTransaction(transactionId);
|
|
2104
|
+
const target = transaction.target;
|
|
2105
|
+
if (target?.kind !== "artifact" || resolvePath(target.artifactPath) !== resolvePath(artifactPath.trim())) {
|
|
2106
|
+
throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not bound to artifact ${artifactPath}`);
|
|
2107
|
+
}
|
|
2108
|
+
return transaction;
|
|
2109
|
+
}
|
|
1565
2110
|
async function requireEditingRoute(runtime, options, operation) {
|
|
1566
2111
|
const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
|
|
1567
2112
|
if (route.status !== "editor-selected") {
|
|
@@ -1569,7 +2114,7 @@ async function requireEditingRoute(runtime, options, operation) {
|
|
|
1569
2114
|
}
|
|
1570
2115
|
}
|
|
1571
2116
|
async function editingRouteContext(runtime, options) {
|
|
1572
|
-
const connection = await
|
|
2117
|
+
const connection = await effectiveConnectionStatus(runtime, options);
|
|
1573
2118
|
let editor;
|
|
1574
2119
|
try {
|
|
1575
2120
|
editor = await inspectMcpEditor(runtime, options);
|