@morshoto/framekit 0.1.14 → 0.1.17
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/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
- package/dist-package/adapters/final-cut/typescript/src/connection.js +8 -5
- package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
- package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
- package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
- package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
- package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
- package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
- package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
- package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
- package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
- package/dist-package/adapters/headless/typescript/src/index.js +3 -0
- package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
- package/dist-package/apps/mcp-server/src/main.js +28 -4
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
- package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
- package/dist-package/apps/mcp-server/src/routing.js +134 -5
- package/dist-package/apps/mcp-server/src/server.js +311 -34
- package/dist-package/packages/runtime/src/application/local-media.js +157 -0
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
- package/dist-package/packages/runtime/src/application/project-store.js +234 -0
- package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
- package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
- package/dist-package/packages/runtime/src/index.js +7 -0
- package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
- package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
- package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
- package/dist-package/packages/runtime/src/runtime.js +5 -2
- package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
- package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
- package/package.json +2 -1
|
@@ -2,12 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
|
2
2
|
import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
3
3
|
import { resolve as resolvePath } from "node:path";
|
|
4
4
|
import { z } from "zod";
|
|
5
|
-
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
|
|
5
|
+
import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
|
|
6
6
|
import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
|
|
7
|
-
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
7
|
+
import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
|
|
8
8
|
import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
|
|
9
9
|
import { EditingSessionRepository } from "./headless-sessions.js";
|
|
10
10
|
import { SessionMaterializationJobs, } from "./materialization-jobs.js";
|
|
11
|
+
import { chooseTimelineReadback } from "./readback-policy.js";
|
|
11
12
|
const revisionValueSchema = z.object({
|
|
12
13
|
id: z.string(),
|
|
13
14
|
sequence: z.number().int().nonnegative(),
|
|
@@ -18,6 +19,11 @@ const contextTargetSchema = z.object({
|
|
|
18
19
|
projectId: z.string().min(1),
|
|
19
20
|
sequenceId: z.string().min(1),
|
|
20
21
|
}).strict();
|
|
22
|
+
const timelineReadbackSchema = z.object({
|
|
23
|
+
sessionId: z.string().min(1).optional(),
|
|
24
|
+
requestedCanonical: z.boolean().optional().default(false),
|
|
25
|
+
finalVerification: z.boolean().optional().default(false),
|
|
26
|
+
}).strict();
|
|
21
27
|
const contextCursorSchema = z.object({
|
|
22
28
|
revision: revisionValueSchema,
|
|
23
29
|
target: contextTargetSchema.optional(),
|
|
@@ -44,6 +50,10 @@ const mediaIndexQuerySchema = z.object({
|
|
|
44
50
|
range: rangeSchema.optional(),
|
|
45
51
|
capabilities: z.array(z.enum(["metadata", "speech", "audio", "noise", "visual"])).optional(),
|
|
46
52
|
});
|
|
53
|
+
const timelineSemanticContextQuerySchema = z.object({
|
|
54
|
+
query: z.string().optional(),
|
|
55
|
+
occurrenceIds: z.array(z.string().min(1)).optional(),
|
|
56
|
+
}).strict();
|
|
47
57
|
const roughCutPlanSchema = mediaIndexQuerySchema.extend({
|
|
48
58
|
maxShots: z.number().int().positive().optional(),
|
|
49
59
|
});
|
|
@@ -165,6 +175,7 @@ const editOperationSchema = z.discriminatedUnion("type", [
|
|
|
165
175
|
rippleDeleteSchema,
|
|
166
176
|
addMarkerSchema,
|
|
167
177
|
]);
|
|
178
|
+
const editingPathSchema = z.enum(["headless", "headed"]).optional();
|
|
168
179
|
const verificationAssertionSchema = z.discriminatedUnion("type", [
|
|
169
180
|
z.object({
|
|
170
181
|
type: z.literal("audio-audibility"),
|
|
@@ -268,13 +279,14 @@ function createEditToolInputSchema(target = {}, baseRevision = revisionSchema) {
|
|
|
268
279
|
];
|
|
269
280
|
return mcpDiscriminatedUnion(options);
|
|
270
281
|
}
|
|
271
|
-
const editToolInputSchema = createEditToolInputSchema();
|
|
282
|
+
const editToolInputSchema = createEditToolInputSchema({ path: editingPathSchema });
|
|
272
283
|
const artifactEditToolInputSchema = createEditToolInputSchema({
|
|
273
284
|
artifactPath: z.string().trim().min(1),
|
|
274
285
|
}, revisionValueSchema);
|
|
275
286
|
const editorTimelineEditToolInputSchema = createEditToolInputSchema({
|
|
276
287
|
projectId: z.string().trim().min(1),
|
|
277
288
|
sequenceId: z.string().trim().min(1),
|
|
289
|
+
path: editingPathSchema,
|
|
278
290
|
}, revisionValueSchema);
|
|
279
291
|
function exposeObjectRoot(schema) {
|
|
280
292
|
if (!isRecord(schema) || !Array.isArray(schema.anyOf))
|
|
@@ -824,7 +836,7 @@ function frameResult(value) {
|
|
|
824
836
|
}
|
|
825
837
|
export function createMcpServer(runtime, options = {}) {
|
|
826
838
|
runtime.registerBuiltinSkills();
|
|
827
|
-
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
839
|
+
const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
|
|
828
840
|
const nativeTransitionAssets = new Map();
|
|
829
841
|
const sessions = options.sessionDirectory
|
|
830
842
|
? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
|
|
@@ -842,6 +854,37 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
842
854
|
throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
|
|
843
855
|
return materializations;
|
|
844
856
|
};
|
|
857
|
+
const requireHeadlessProjects = () => {
|
|
858
|
+
if (!options.headlessProjects)
|
|
859
|
+
throw new Error("HEADLESS_PROJECT_UNAVAILABLE: headless project storage is not configured");
|
|
860
|
+
return options.headlessProjects;
|
|
861
|
+
};
|
|
862
|
+
const prepareSessionReadback = async (sessionId, requestedCanonical, finalVerification) => {
|
|
863
|
+
const stored = await requireSessions().inspect(sessionId);
|
|
864
|
+
const decision = chooseTimelineReadback({
|
|
865
|
+
hasCanonicalBase: true,
|
|
866
|
+
requestedCanonical,
|
|
867
|
+
finalVerification,
|
|
868
|
+
sessionState: stored.document.state,
|
|
869
|
+
...(stored.document.observation ? {
|
|
870
|
+
fastObservation: {
|
|
871
|
+
available: true,
|
|
872
|
+
coverageComplete: stored.document.observation.coverageComplete,
|
|
873
|
+
status: "possibly-stale",
|
|
874
|
+
},
|
|
875
|
+
} : {}),
|
|
876
|
+
});
|
|
877
|
+
return { stored, decision };
|
|
878
|
+
};
|
|
879
|
+
const canonicalResyncSession = async (sessionId, providerId) => {
|
|
880
|
+
if (providerId && providerId !== "final-cut") {
|
|
881
|
+
throw new Error(`SESSION_PROVIDER_MISMATCH: canonical Final Cut resync cannot replace provider ${providerId}`);
|
|
882
|
+
}
|
|
883
|
+
const snapshot = await runtime.inspectProject();
|
|
884
|
+
const timeline = createTimelineIrFromProjectSnapshot(snapshot, { id: "final-cut" });
|
|
885
|
+
const session = await requireSessions().reconcile(sessionId, { id: "final-cut" }, timeline);
|
|
886
|
+
return { snapshot, session };
|
|
887
|
+
};
|
|
845
888
|
const sessionOperationSchema = z.array(z.unknown());
|
|
846
889
|
server.registerTool("session.create", {
|
|
847
890
|
description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
|
|
@@ -921,6 +964,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
921
964
|
description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
|
|
922
965
|
inputSchema: { jobId: z.string().min(1) },
|
|
923
966
|
}, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
|
|
967
|
+
server.registerTool("session.materialize.resync", {
|
|
968
|
+
description: "Read the completed versioned handoff target and create a fresh editing-session baseline for continuation.",
|
|
969
|
+
inputSchema: { jobId: z.string().min(1), sessionId: z.string().min(1) },
|
|
970
|
+
}, async ({ jobId, sessionId }) => sessionResult(async () => requireMaterializations().resync(jobId, sessionId)));
|
|
924
971
|
server.registerTool("connection.status", {
|
|
925
972
|
description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
|
|
926
973
|
inputSchema: {},
|
|
@@ -987,8 +1034,22 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
987
1034
|
}
|
|
988
1035
|
});
|
|
989
1036
|
server.registerTool("project.inspect", {
|
|
990
|
-
description: "Read
|
|
991
|
-
|
|
1037
|
+
description: "Read a bound session baseline or perform an explicit canonical project resync before editing.route selects a capability-checked path.",
|
|
1038
|
+
inputSchema: timelineReadbackSchema,
|
|
1039
|
+
}, async ({ sessionId, requestedCanonical, finalVerification }) => {
|
|
1040
|
+
if (sessionId) {
|
|
1041
|
+
const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
|
|
1042
|
+
if (decision.route === "session" || decision.route === "fast-observation") {
|
|
1043
|
+
return jsonResult({
|
|
1044
|
+
sessionId,
|
|
1045
|
+
readback: decision,
|
|
1046
|
+
session: stored.document,
|
|
1047
|
+
snapshot: stored.document.base,
|
|
1048
|
+
});
|
|
1049
|
+
}
|
|
1050
|
+
const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
|
|
1051
|
+
return jsonResult({ sessionId, readback: decision, ...resynced });
|
|
1052
|
+
}
|
|
992
1053
|
const inspected = await inspectMcpEditor(runtime, options);
|
|
993
1054
|
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
994
1055
|
if (!capability.available) {
|
|
@@ -1037,6 +1098,151 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1037
1098
|
return capabilityUnavailableErrorResult(error);
|
|
1038
1099
|
}
|
|
1039
1100
|
});
|
|
1101
|
+
server.registerTool("headless.project.create", {
|
|
1102
|
+
description: "Create and persist a Framekit-owned canonical project without contacting Final Cut Pro.",
|
|
1103
|
+
inputSchema: { timeline: z.unknown() },
|
|
1104
|
+
}, async ({ timeline }) => sessionResult(async () => requireHeadlessProjects().create(timeline)));
|
|
1105
|
+
server.registerTool("headless.project.list", {
|
|
1106
|
+
description: "List persisted Framekit-owned projects and their stable canonical revisions.",
|
|
1107
|
+
inputSchema: {},
|
|
1108
|
+
}, async () => sessionResult(() => requireHeadlessProjects().list()));
|
|
1109
|
+
server.registerTool("headless.project.open", {
|
|
1110
|
+
description: "Open a persisted Framekit-owned project and fail closed if registered media changed or is missing.",
|
|
1111
|
+
inputSchema: { projectId: z.string().min(1) },
|
|
1112
|
+
}, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().open(projectId)));
|
|
1113
|
+
server.registerTool("headless.project.inspect", {
|
|
1114
|
+
description: "Inspect the current persisted Framekit Timeline IR and exact revision.",
|
|
1115
|
+
inputSchema: { projectId: z.string().min(1) },
|
|
1116
|
+
}, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().inspect(projectId)));
|
|
1117
|
+
server.registerTool("headless.media.register", {
|
|
1118
|
+
description: "Register one local source file in the canonical Framekit project with digest and ffprobe metadata.",
|
|
1119
|
+
inputSchema: {
|
|
1120
|
+
projectId: z.string().min(1),
|
|
1121
|
+
sourcePath: z.string().min(1),
|
|
1122
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
1123
|
+
},
|
|
1124
|
+
}, async ({ projectId, sourcePath, expectedRevision }) => sessionResult(() => requireHeadlessProjects().registerMedia(projectId, sourcePath, expectedRevision)));
|
|
1125
|
+
server.registerTool("headless.edit.preview", {
|
|
1126
|
+
description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
|
|
1127
|
+
inputSchema: {
|
|
1128
|
+
projectId: z.string().min(1),
|
|
1129
|
+
sequenceId: z.string().min(1),
|
|
1130
|
+
expectedRevision: revisionValueSchema,
|
|
1131
|
+
operations: z.array(z.unknown()),
|
|
1132
|
+
},
|
|
1133
|
+
}, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().previewEdit(projectId, {
|
|
1134
|
+
schemaVersion: 1,
|
|
1135
|
+
expectedRevision,
|
|
1136
|
+
operations: operations,
|
|
1137
|
+
}, sequenceId)));
|
|
1138
|
+
server.registerTool("headless.edit.execute", {
|
|
1139
|
+
description: "Execute supported Framekit Timeline IR edits against the expected canonical revision and persist exactly one revision.",
|
|
1140
|
+
inputSchema: {
|
|
1141
|
+
projectId: z.string().min(1),
|
|
1142
|
+
sequenceId: z.string().min(1),
|
|
1143
|
+
expectedRevision: revisionValueSchema,
|
|
1144
|
+
operations: z.array(z.unknown()),
|
|
1145
|
+
},
|
|
1146
|
+
}, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().executeEdit(projectId, {
|
|
1147
|
+
schemaVersion: 1,
|
|
1148
|
+
expectedRevision,
|
|
1149
|
+
operations: operations,
|
|
1150
|
+
}, sequenceId)));
|
|
1151
|
+
const headlessRenderParametersSchema = z.object({
|
|
1152
|
+
outputPath: z.string().min(1),
|
|
1153
|
+
format: z.enum(["mp4", "mov"]),
|
|
1154
|
+
width: z.number().int().positive(),
|
|
1155
|
+
height: z.number().int().positive(),
|
|
1156
|
+
frameRate: rationalTimeSchema,
|
|
1157
|
+
overwrite: z.boolean().optional(),
|
|
1158
|
+
}).strict();
|
|
1159
|
+
const roughCutExecutionPlanSchema = z.object({
|
|
1160
|
+
planner: z.object({ id: z.string().min(1), version: z.number().int().nonnegative() }).strict(),
|
|
1161
|
+
revision: revisionValueSchema,
|
|
1162
|
+
query: z.record(z.unknown()),
|
|
1163
|
+
shots: z.array(z.object({
|
|
1164
|
+
order: z.number().int().positive(),
|
|
1165
|
+
sourceIdentity: z.object({
|
|
1166
|
+
mediaId: z.string().min(1),
|
|
1167
|
+
source: z.string().min(1),
|
|
1168
|
+
sourceDigest: z.string().optional(),
|
|
1169
|
+
mediaKind: z.enum(["video", "audio"]).optional(),
|
|
1170
|
+
duration: z.number().finite().positive().optional(),
|
|
1171
|
+
}).strict(),
|
|
1172
|
+
range: z.object({
|
|
1173
|
+
start: z.number().finite().nonnegative(),
|
|
1174
|
+
end: z.number().finite().positive(),
|
|
1175
|
+
startTime: rationalTimeSchema.optional(),
|
|
1176
|
+
durationTime: rationalTimeSchema.optional(),
|
|
1177
|
+
}).strict(),
|
|
1178
|
+
confidence: z.number().finite().nonnegative(),
|
|
1179
|
+
matchedProperties: z.array(z.string()),
|
|
1180
|
+
rationale: z.string().min(1),
|
|
1181
|
+
evidence: z.object({
|
|
1182
|
+
kind: z.literal("speech"),
|
|
1183
|
+
transcript: z.string(),
|
|
1184
|
+
wordCount: z.number().int().nonnegative(),
|
|
1185
|
+
averageWordConfidence: z.number().finite().min(0).max(1),
|
|
1186
|
+
vad: z.object({
|
|
1187
|
+
kind: z.enum(["speech", "silence", "breath", "laughter", "noise"]),
|
|
1188
|
+
confidence: z.number().finite().min(0).max(1).optional(),
|
|
1189
|
+
}).strict().optional(),
|
|
1190
|
+
audio: z.object({
|
|
1191
|
+
integratedLufs: z.number().finite().optional(),
|
|
1192
|
+
truePeakDb: z.number().finite().optional(),
|
|
1193
|
+
silenceMs: z.number().finite().nonnegative().optional(),
|
|
1194
|
+
}).strict().optional(),
|
|
1195
|
+
}).strict().optional(),
|
|
1196
|
+
}).strict()),
|
|
1197
|
+
warnings: z.array(z.string()),
|
|
1198
|
+
}).strict();
|
|
1199
|
+
const headlessFcpxmlTargetSchema = z.object({
|
|
1200
|
+
provider: z.literal("final-cut"),
|
|
1201
|
+
libraryUid: z.string().min(1),
|
|
1202
|
+
eventUid: z.string().min(1),
|
|
1203
|
+
projectUid: z.string().min(1),
|
|
1204
|
+
sequenceUid: z.string().min(1),
|
|
1205
|
+
eventName: z.string().min(1).optional(),
|
|
1206
|
+
materialization: z.enum(["versioned", "reuse-existing"]).optional(),
|
|
1207
|
+
}).strict();
|
|
1208
|
+
const headlessRoughCutRequestSchema = z.object({
|
|
1209
|
+
projectId: z.string().min(1),
|
|
1210
|
+
sequenceId: z.string().min(1),
|
|
1211
|
+
plan: roughCutExecutionPlanSchema,
|
|
1212
|
+
operations: z.array(z.unknown()).optional().describe("Ordered Timeline IR edit operations included in the preview and bound into planDigest."),
|
|
1213
|
+
sourceAudioPolicy: z.literal("preserve-and-mix").optional().describe("Retain source audio and mix registered audio/music occurrences using their configured gain."),
|
|
1214
|
+
render: headlessRenderParametersSchema,
|
|
1215
|
+
fcpxml: z.object({
|
|
1216
|
+
path: z.string().min(1),
|
|
1217
|
+
target: headlessFcpxmlTargetSchema,
|
|
1218
|
+
overwrite: z.boolean().optional(),
|
|
1219
|
+
}).strict(),
|
|
1220
|
+
}).strict();
|
|
1221
|
+
server.registerTool("headless.render", {
|
|
1222
|
+
description: "Render and independently verify one immutable Framekit revision without launching an NLE.",
|
|
1223
|
+
inputSchema: {
|
|
1224
|
+
projectId: z.string().min(1),
|
|
1225
|
+
sequenceId: z.string().min(1),
|
|
1226
|
+
expectedRevision: revisionValueSchema.optional(),
|
|
1227
|
+
parameters: headlessRenderParametersSchema,
|
|
1228
|
+
},
|
|
1229
|
+
}, async ({ projectId, sequenceId, expectedRevision, parameters }) => sessionResult(() => requireHeadlessProjects().render(projectId, sequenceId, parameters, expectedRevision)));
|
|
1230
|
+
server.registerTool("headless.rough-cut.preview", {
|
|
1231
|
+
description: "Preview a semantic rough-cut plan with optional Timeline IR operations; the digest binds both, and preview returns provenance and FCPXML output intent without mutation.",
|
|
1232
|
+
inputSchema: headlessRoughCutRequestSchema.shape,
|
|
1233
|
+
}, async (request) => sessionResult(() => requireHeadlessProjects().previewRoughCut(request)));
|
|
1234
|
+
server.registerTool("headless.rough-cut.execute", {
|
|
1235
|
+
description: "Execute an explicitly approved semantic rough-cut plan and its digest-bound Timeline IR operations headlessly, verify MP4 output, and write equivalent editable FCPXML.",
|
|
1236
|
+
inputSchema: {
|
|
1237
|
+
...headlessRoughCutRequestSchema.shape,
|
|
1238
|
+
approved: z.boolean(),
|
|
1239
|
+
planDigest: z.string().regex(/^[a-f0-9]{64}$/),
|
|
1240
|
+
},
|
|
1241
|
+
}, async (request) => sessionResult(() => requireHeadlessProjects().executeRoughCut(request)));
|
|
1242
|
+
server.registerTool("headless.render.inspect", {
|
|
1243
|
+
description: "Inspect a persisted headless render record, provenance, and independent verification evidence.",
|
|
1244
|
+
inputSchema: { renderId: z.string().min(1) },
|
|
1245
|
+
}, async ({ renderId }) => sessionResult(() => requireHeadlessProjects().inspectRender(renderId)));
|
|
1040
1246
|
server.registerTool("editor.inspect", {
|
|
1041
1247
|
description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
|
|
1042
1248
|
}, async () => {
|
|
@@ -1060,7 +1266,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1060
1266
|
availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
|
|
1061
1267
|
})));
|
|
1062
1268
|
server.registerTool("editing.route", {
|
|
1063
|
-
description: "Resolve an
|
|
1269
|
+
description: "Resolve the default headless SSoT path or an explicitly requested headed path after capability checks; never fall back to native UI implicitly, and require explicit external-renderer fallback selection.",
|
|
1064
1270
|
inputSchema: {
|
|
1065
1271
|
operation: z.enum([
|
|
1066
1272
|
"project.list",
|
|
@@ -1077,10 +1283,17 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1077
1283
|
"timeline.export",
|
|
1078
1284
|
]),
|
|
1079
1285
|
fallback: z.enum(["none", "external-renderer"]).optional().default("none"),
|
|
1286
|
+
path: z.enum(["headless", "headed"]).optional(),
|
|
1287
|
+
editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
|
|
1080
1288
|
},
|
|
1081
|
-
}, async ({ operation, fallback }) => {
|
|
1289
|
+
}, async ({ operation, fallback, path, editType }) => {
|
|
1082
1290
|
const context = await editingRouteContext(runtime, options);
|
|
1083
|
-
return jsonResult(resolveEditingRoute({
|
|
1291
|
+
return jsonResult(resolveEditingRoute({
|
|
1292
|
+
operation,
|
|
1293
|
+
fallback,
|
|
1294
|
+
...(path ? { path } : {}),
|
|
1295
|
+
...(editType ? { editType } : {}),
|
|
1296
|
+
}, context));
|
|
1084
1297
|
});
|
|
1085
1298
|
server.registerTool("editing.duration.plan", {
|
|
1086
1299
|
description: "Plan requested duration against unique footage and return explicit quality-preserving alternatives without editing.",
|
|
@@ -1415,7 +1628,7 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1415
1628
|
return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
|
|
1416
1629
|
});
|
|
1417
1630
|
server.registerTool("artifact.publish.preview", {
|
|
1418
|
-
description: "Prepare a
|
|
1631
|
+
description: "Prepare a verified FCPXML publish handoff without opening Final Cut; the configured native route may use non-activating document delivery or an explicit headed fallback.",
|
|
1419
1632
|
inputSchema: {
|
|
1420
1633
|
artifactPath: z.string().trim().min(1),
|
|
1421
1634
|
transactionId: z.string().min(1),
|
|
@@ -1615,8 +1828,27 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1615
1828
|
timestamp: new Date(sequence).toISOString(),
|
|
1616
1829
|
}, waitMs ?? 0)));
|
|
1617
1830
|
server.registerTool("timeline.inspect", {
|
|
1618
|
-
description: "Read
|
|
1619
|
-
|
|
1831
|
+
description: "Read a bound session baseline or perform an explicit canonical timeline resync after canonical capability checks.",
|
|
1832
|
+
inputSchema: timelineReadbackSchema,
|
|
1833
|
+
}, async ({ sessionId, requestedCanonical, finalVerification }) => {
|
|
1834
|
+
if (sessionId) {
|
|
1835
|
+
const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
|
|
1836
|
+
if (decision.route === "session" || decision.route === "fast-observation") {
|
|
1837
|
+
return jsonResult({
|
|
1838
|
+
sessionId,
|
|
1839
|
+
readback: decision,
|
|
1840
|
+
session: stored.document,
|
|
1841
|
+
timeline: stored.document.base,
|
|
1842
|
+
});
|
|
1843
|
+
}
|
|
1844
|
+
const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
|
|
1845
|
+
return jsonResult({
|
|
1846
|
+
sessionId,
|
|
1847
|
+
readback: decision,
|
|
1848
|
+
snapshot: resynced.snapshot.timeline,
|
|
1849
|
+
session: resynced.session,
|
|
1850
|
+
});
|
|
1851
|
+
}
|
|
1620
1852
|
const inspected = await inspectMcpEditor(runtime, options);
|
|
1621
1853
|
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1622
1854
|
if (!capability.available) {
|
|
@@ -1629,6 +1861,22 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1629
1861
|
return capabilityUnavailableErrorResult(error);
|
|
1630
1862
|
}
|
|
1631
1863
|
});
|
|
1864
|
+
server.registerTool("timeline.semantic.inspect", {
|
|
1865
|
+
description: "Enrich timeline occurrences with source-range-bound semantic speech, visual, and metadata context without mutating the timeline.",
|
|
1866
|
+
inputSchema: timelineSemanticContextQuerySchema.shape,
|
|
1867
|
+
}, async (query) => {
|
|
1868
|
+
const inspected = await inspectMcpEditor(runtime, options);
|
|
1869
|
+
const capability = inspected.capabilities.families.canonicalDocument.read;
|
|
1870
|
+
if (!capability.available) {
|
|
1871
|
+
return capabilityErrorResult("timeline.semantic.inspect", "canonicalDocument.read", capability);
|
|
1872
|
+
}
|
|
1873
|
+
try {
|
|
1874
|
+
return jsonResult(await runtime.inspectTimelineSemanticContext(query));
|
|
1875
|
+
}
|
|
1876
|
+
catch (error) {
|
|
1877
|
+
return capabilityUnavailableErrorResult(error);
|
|
1878
|
+
}
|
|
1879
|
+
});
|
|
1632
1880
|
server.registerTool("timeline.frame.capture", {
|
|
1633
1881
|
description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
|
|
1634
1882
|
inputSchema: {
|
|
@@ -1717,8 +1965,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1717
1965
|
description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
|
|
1718
1966
|
inputSchema: editToolInputSchema,
|
|
1719
1967
|
}, async (input) => {
|
|
1720
|
-
|
|
1721
|
-
|
|
1968
|
+
const { path, verification, ...operation } = input;
|
|
1969
|
+
const parsedOperation = editOperationSchema.parse(operation);
|
|
1970
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
|
|
1971
|
+
return jsonResult(await runtime.edit(parsedOperation, verification ?? {}));
|
|
1722
1972
|
});
|
|
1723
1973
|
server.registerTool("rough-cut.construction.plan", {
|
|
1724
1974
|
description: "Build a deterministic ordered rough-cut construction plan without changing the active project.",
|
|
@@ -1741,9 +1991,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1741
1991
|
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.",
|
|
1742
1992
|
inputSchema: editorTimelineEditToolInputSchema,
|
|
1743
1993
|
}, async (input) => {
|
|
1744
|
-
|
|
1745
|
-
const
|
|
1746
|
-
|
|
1994
|
+
const { path, projectId, sequenceId, verification, ...operation } = input;
|
|
1995
|
+
const parsedOperation = editOperationSchema.parse(operation);
|
|
1996
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
|
|
1997
|
+
return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, parsedOperation, verification ?? {}));
|
|
1747
1998
|
});
|
|
1748
1999
|
server.registerTool("music.add", {
|
|
1749
2000
|
description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
|
|
@@ -1763,10 +2014,12 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1763
2014
|
baseRevision: revisionValueSchema,
|
|
1764
2015
|
operations: workflowOperationsSchema,
|
|
1765
2016
|
verification: verificationPolicySchema.optional(),
|
|
2017
|
+
path: editingPathSchema,
|
|
1766
2018
|
},
|
|
1767
2019
|
}, async (request) => {
|
|
1768
|
-
|
|
1769
|
-
|
|
2020
|
+
const { path, ...editRequest } = request;
|
|
2021
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path);
|
|
2022
|
+
return jsonResult(await runtime.previewEdit(editRequest));
|
|
1770
2023
|
});
|
|
1771
2024
|
server.registerTool("timeline.mask.add.preview", {
|
|
1772
2025
|
description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
|
|
@@ -1799,9 +2052,10 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1799
2052
|
baseRevision: revisionValueSchema,
|
|
1800
2053
|
operations: workflowOperationsSchema,
|
|
1801
2054
|
verification: verificationPolicySchema.optional(),
|
|
2055
|
+
path: editingPathSchema,
|
|
1802
2056
|
},
|
|
1803
|
-
}, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
|
|
1804
|
-
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
2057
|
+
}, async ({ projectId, sequenceId, baseRevision, operations, verification, path }) => {
|
|
2058
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path);
|
|
1805
2059
|
return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
|
|
1806
2060
|
});
|
|
1807
2061
|
server.registerTool("artifact.edit.execute", {
|
|
@@ -1840,16 +2094,16 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1840
2094
|
});
|
|
1841
2095
|
server.registerTool("editor.timeline.edit.execute", {
|
|
1842
2096
|
description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
|
|
1843
|
-
inputSchema: { previewToken: z.string().min(1) },
|
|
1844
|
-
}, async ({ previewToken }) => {
|
|
1845
|
-
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
2097
|
+
inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
|
|
2098
|
+
}, async ({ previewToken, path }) => {
|
|
2099
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path);
|
|
1846
2100
|
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1847
2101
|
});
|
|
1848
2102
|
server.registerTool("timeline.edit.execute", {
|
|
1849
2103
|
description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
|
|
1850
|
-
inputSchema: { previewToken: z.string().min(1) },
|
|
1851
|
-
}, async ({ previewToken }) => {
|
|
1852
|
-
await requireEditingRoute(runtime, options, "timeline.edit");
|
|
2104
|
+
inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
|
|
2105
|
+
}, async ({ previewToken, path }) => {
|
|
2106
|
+
await requireEditingRoute(runtime, options, "timeline.edit", path);
|
|
1853
2107
|
return jsonResult(await runtime.executeEdit(previewToken));
|
|
1854
2108
|
});
|
|
1855
2109
|
server.registerTool("timeline.mask.add.execute", {
|
|
@@ -1872,9 +2126,9 @@ export function createMcpServer(runtime, options = {}) {
|
|
|
1872
2126
|
inputSchema: { previewToken: z.string().min(1) },
|
|
1873
2127
|
}, async ({ previewToken }) => jsonResult(await runtime.executeFillerRemoval(previewToken)));
|
|
1874
2128
|
server.registerTool("audio.analyze", {
|
|
1875
|
-
description: "Analyze loudness, true peak, and silence for one media item.",
|
|
1876
|
-
inputSchema: { mediaId: z.string().min(1) },
|
|
1877
|
-
}, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
|
|
2129
|
+
description: "Analyze loudness, true peak, and silence for one media item or source range.",
|
|
2130
|
+
inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
|
|
2131
|
+
}, async ({ mediaId, range }) => jsonResult(await runtime.analyzeAudio(mediaId, range)));
|
|
1878
2132
|
server.registerTool("audio.noise.analyze", {
|
|
1879
2133
|
description: "Analyze unwanted background noise for one media item when a noise analyzer is configured.",
|
|
1880
2134
|
inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
|
|
@@ -2068,6 +2322,11 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2068
2322
|
const inspected = await runtime.inspectEditor();
|
|
2069
2323
|
const native = options.nativeEditor?.capabilities();
|
|
2070
2324
|
const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
|
|
2325
|
+
const publishingMode = publishingAvailable
|
|
2326
|
+
? (typeof options.projectPublisher?.executionMode === "function"
|
|
2327
|
+
? options.projectPublisher.executionMode()
|
|
2328
|
+
: "headed-only")
|
|
2329
|
+
: "unavailable";
|
|
2071
2330
|
const exportAvailable = Boolean(options.videoExporter?.isAvailable());
|
|
2072
2331
|
const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
|
|
2073
2332
|
const capabilities = withCapabilityFamilies({
|
|
@@ -2075,7 +2334,7 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2075
2334
|
editor: {
|
|
2076
2335
|
...inspected.capabilities.editor,
|
|
2077
2336
|
artifactPublish: publishingAvailable,
|
|
2078
|
-
artifactPublishMode:
|
|
2337
|
+
artifactPublishMode: publishingMode,
|
|
2079
2338
|
...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
|
|
2080
2339
|
videoExport: exportAvailable,
|
|
2081
2340
|
backgroundRender: backgroundExportAvailable,
|
|
@@ -2109,7 +2368,7 @@ async function inspectMcpEditor(runtime, options) {
|
|
|
2109
2368
|
clipMovement: false,
|
|
2110
2369
|
},
|
|
2111
2370
|
publishing: publishingAvailable,
|
|
2112
|
-
publishingBackend: "fcpxml-publisher",
|
|
2371
|
+
publishingBackend: publishingMode === "background-capable" ? "fcpxml-document-open" : "fcpxml-publisher",
|
|
2113
2372
|
export: exportAvailable,
|
|
2114
2373
|
exportBackend: "final-cut-native-export",
|
|
2115
2374
|
backgroundExport: {
|
|
@@ -2156,8 +2415,15 @@ function requireArtifactTransaction(runtime, transactionId, artifactPath) {
|
|
|
2156
2415
|
}
|
|
2157
2416
|
return transaction;
|
|
2158
2417
|
}
|
|
2159
|
-
async function requireEditingRoute(runtime, options, operation) {
|
|
2160
|
-
const route = resolveEditingRoute({
|
|
2418
|
+
async function requireEditingRoute(runtime, options, operation, path, editType) {
|
|
2419
|
+
const route = resolveEditingRoute({
|
|
2420
|
+
operation,
|
|
2421
|
+
...(path ? { path } : {}),
|
|
2422
|
+
...(editType ? { editType } : {}),
|
|
2423
|
+
}, await editingRouteContext(runtime, options));
|
|
2424
|
+
if (route.status === "headless-selected") {
|
|
2425
|
+
throw new Error("HEADLESS_ROUTE_SELECTED: use the headless.project and headless.edit tools for the default Framekit SSoT path");
|
|
2426
|
+
}
|
|
2161
2427
|
if (route.status !== "editor-selected") {
|
|
2162
2428
|
throw new Error(`${route.reason.code}: ${route.reason.message}`);
|
|
2163
2429
|
}
|
|
@@ -2183,6 +2449,17 @@ async function editingRouteContext(runtime, options) {
|
|
|
2183
2449
|
return {
|
|
2184
2450
|
connection,
|
|
2185
2451
|
...(editor ? { editor } : {}),
|
|
2452
|
+
...(options.headlessProjects ? {
|
|
2453
|
+
headless: {
|
|
2454
|
+
available: true,
|
|
2455
|
+
backend: "framekit-project-store",
|
|
2456
|
+
guarantee: "canonical-write",
|
|
2457
|
+
// Advertise only concrete Timeline IR edit capabilities. The legacy
|
|
2458
|
+
// timeline.edit surface also accepts operations that the headless
|
|
2459
|
+
// transaction layer does not implement.
|
|
2460
|
+
supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
|
|
2461
|
+
},
|
|
2462
|
+
} : {}),
|
|
2186
2463
|
...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
|
|
2187
2464
|
...(nativeReadiness ? { nativeReadiness } : {}),
|
|
2188
2465
|
};
|