@morshoto/framekit 0.1.0 → 0.1.4

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.
Files changed (62) hide show
  1. package/README.md +42 -17
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +57 -0
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +5 -1
  4. package/dist-package/adapters/final-cut/typescript/src/export.js +231 -8
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +55 -5
  6. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  7. package/dist-package/adapters/final-cut/typescript/src/native.js +1000 -100
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +40 -5
  9. package/dist-package/adapters/final-cut/typescript/src/session.js +21 -5
  10. package/dist-package/apps/mcp-server/src/main.js +9 -1
  11. package/dist-package/apps/mcp-server/src/routing.js +172 -0
  12. package/dist-package/apps/mcp-server/src/server.js +780 -33
  13. package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
  14. package/dist-package/packages/runtime/src/application/media-analysis-service.js +370 -0
  15. package/dist-package/packages/runtime/src/application/project-service.js +127 -0
  16. package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
  17. package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
  18. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
  19. package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
  20. package/dist-package/packages/runtime/src/capabilities.js +112 -1
  21. package/dist-package/packages/runtime/src/color-correction.js +48 -0
  22. package/dist-package/packages/runtime/src/context/context-engine.js +11 -6
  23. package/dist-package/packages/runtime/src/context/context-service.js +30 -0
  24. package/dist-package/packages/runtime/src/context/revision.js +3 -0
  25. package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
  26. package/dist-package/packages/runtime/src/domain/context.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/diff.js +1 -0
  28. package/dist-package/packages/runtime/src/domain/duration.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/editing.js +1 -0
  30. package/dist-package/packages/runtime/src/domain/index.js +12 -0
  31. package/dist-package/packages/runtime/src/domain/media.js +7 -0
  32. package/dist-package/packages/runtime/src/domain/ports.js +1 -0
  33. package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
  34. package/dist-package/packages/runtime/src/domain/project.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
  36. package/dist-package/packages/runtime/src/domain/skills.js +33 -0
  37. package/dist-package/packages/runtime/src/domain/types.js +5 -1
  38. package/dist-package/packages/runtime/src/domain/verification.js +1 -0
  39. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
  40. package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
  41. package/dist-package/packages/runtime/src/editing/edit-service.js +413 -0
  42. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +337 -0
  43. package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
  44. package/dist-package/packages/runtime/src/index.js +12 -3
  45. package/dist-package/packages/runtime/src/planning/rough-cut.js +65 -0
  46. package/dist-package/packages/runtime/src/runtime.js +130 -825
  47. package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
  48. package/dist-package/packages/runtime/src/skills/index.js +3 -0
  49. package/dist-package/packages/runtime/src/skills/registry.js +74 -0
  50. package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
  51. package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
  52. package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
  53. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
  54. package/dist-package/packages/runtime/src/timeline/rational-time.js +58 -0
  55. package/dist-package/packages/runtime/src/verification/verification.js +712 -1
  56. package/dist-package/packages/testkit/src/fixture-analyzers.js +27 -0
  57. package/dist-package/packages/testkit/src/in-memory-editor.js +286 -3
  58. package/dist-package/packages/testkit/src/index.js +1 -0
  59. package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
  60. package/package.json +15 -7
  61. /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
  62. /package/dist-package/packages/runtime/src/{snapshot-digest.js → timeline/snapshot-digest.js} +0 -0
@@ -1,6 +1,7 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { z } from "zod";
3
- import { resolveEditingIntent } from "../../../packages/runtime/src/index.js";
3
+ import { resolveEditingIntent, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
4
+ import { EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
4
5
  const revisionValueSchema = z.object({
5
6
  id: z.string(),
6
7
  sequence: z.number().int().nonnegative(),
@@ -15,6 +16,41 @@ const rangeSchema = z.object({
15
16
  start: z.number().nonnegative(),
16
17
  end: z.number().positive(),
17
18
  });
19
+ const mediaIndexQuerySchema = z.object({
20
+ query: z.string().optional(),
21
+ subject: z.string().optional(),
22
+ scene: z.string().optional(),
23
+ environment: z.string().optional(),
24
+ timeOfDay: z.string().optional(),
25
+ mood: z.string().optional(),
26
+ motion: z.enum(["static", "low", "medium", "high"]).optional(),
27
+ range: rangeSchema.optional(),
28
+ capabilities: z.array(z.enum(["metadata", "speech", "audio", "noise", "visual"])).optional(),
29
+ });
30
+ const roughCutPlanSchema = mediaIndexQuerySchema.extend({
31
+ maxShots: z.number().int().positive().optional(),
32
+ });
33
+ const durationRangeSchema = z.object({
34
+ startSeconds: z.number().finite().nonnegative(),
35
+ endSeconds: z.number().finite().positive(),
36
+ });
37
+ const durationPolicyInputSchema = z.object({
38
+ requestedDurationSeconds: z.number().finite().positive(),
39
+ footage: z.array(z.object({
40
+ id: z.string().trim().min(1),
41
+ durationSeconds: z.number().finite().positive(),
42
+ usableDurationSeconds: z.number().finite().positive().optional(),
43
+ usableRanges: z.array(durationRangeSchema).optional(),
44
+ reusable: z.boolean().optional(),
45
+ })),
46
+ constraint: z.enum(["hard", "soft"]).optional(),
47
+ permissions: z.object({
48
+ allowReuse: z.boolean().optional(),
49
+ allowSlowMotion: z.boolean().optional(),
50
+ allowGeneratedAssets: z.boolean().optional(),
51
+ }).optional(),
52
+ actualDurationSeconds: z.number().finite().nonnegative().optional(),
53
+ });
18
54
  const markerSchema = z.object({
19
55
  id: z.string().min(1),
20
56
  start: z.number().nonnegative(),
@@ -30,32 +66,169 @@ const trimClipSchema = z.object({
30
66
  baseRevision: revisionSchema,
31
67
  });
32
68
  const setGainSchema = z.object({ type: z.literal("set-gain"), clipId: z.string().min(1), gainDb: z.number().finite(), baseRevision: revisionSchema });
69
+ const reduceNoiseSchema = z.object({
70
+ type: z.literal("reduce-noise"),
71
+ clipId: z.string().min(1),
72
+ range: rangeSchema,
73
+ reductionDb: z.number().finite().positive(),
74
+ baseRevision: revisionSchema,
75
+ });
76
+ const colorCorrectionSchema = z.object({
77
+ type: z.literal("set-color-correction"),
78
+ clipId: z.string().min(1),
79
+ correction: z.object({
80
+ exposure: z.number().finite().min(-4).max(4),
81
+ contrast: z.number().finite().min(-1).max(1),
82
+ saturation: z.number().finite().min(-1).max(1),
83
+ temperature: z.number().finite().min(-100).max(100),
84
+ tint: z.number().finite().min(-100).max(100),
85
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
86
+ }),
87
+ baseRevision: revisionSchema,
88
+ });
33
89
  const rippleDeleteSchema = z.object({ type: z.literal("ripple-delete"), timelineId: z.string().min(1), range: rangeSchema, reason: z.string().optional(), baseRevision: revisionSchema });
34
90
  const addMarkerSchema = z.object({ type: z.literal("add-marker"), timelineId: z.string().min(1), marker: markerSchema, baseRevision: revisionSchema });
91
+ const roughCutImportSchema = z.object({
92
+ type: z.literal("media.import"),
93
+ mediaId: z.string().min(1),
94
+ source: z.string().min(1),
95
+ mediaKind: z.literal("video"),
96
+ duration: z.number().positive(),
97
+ sourceDigest: z.string().min(1),
98
+ });
99
+ const roughCutShotSchema = z.object({
100
+ occurrenceId: z.string().min(1),
101
+ mediaId: z.string().min(1),
102
+ duration: z.number().positive().optional(),
103
+ });
104
+ const roughCutConstructionPlanInputSchema = {
105
+ baseRevision: revisionValueSchema,
106
+ imports: z.array(roughCutImportSchema).optional(),
107
+ shots: z.array(roughCutShotSchema).min(1),
108
+ };
35
109
  const editOperationSchema = z.discriminatedUnion("type", [
36
110
  renameClipSchema,
37
111
  trimClipSchema,
38
112
  setGainSchema,
113
+ reduceNoiseSchema,
114
+ colorCorrectionSchema,
39
115
  rippleDeleteSchema,
40
116
  addMarkerSchema,
41
117
  ]);
118
+ const verificationAssertionSchema = z.discriminatedUnion("type", [
119
+ z.object({
120
+ type: z.literal("audio-audibility"),
121
+ mediaId: z.string().min(1),
122
+ minAudibleSamples: z.number().int().positive().optional(),
123
+ maxSilenceMs: z.number().finite().nonnegative().optional(),
124
+ }),
125
+ z.object({
126
+ type: z.literal("audio-coverage"),
127
+ mediaId: z.string().min(1),
128
+ start: z.number().finite().nonnegative(),
129
+ duration: z.number().finite().positive(),
130
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
131
+ }),
132
+ z.object({
133
+ type: z.literal("audio-loudness"),
134
+ mediaId: z.string().min(1),
135
+ targetLufs: z.number().finite(),
136
+ toleranceDb: z.number().finite().nonnegative().optional(),
137
+ }),
138
+ z.object({
139
+ type: z.literal("audio-noise"),
140
+ mediaId: z.string().min(1),
141
+ maxNoiseFloorDb: z.number().finite(),
142
+ minConfidence: z.number().finite().min(0).max(1).optional(),
143
+ }),
144
+ z.object({
145
+ type: z.literal("color-correction"),
146
+ clipId: z.string().min(1),
147
+ expected: z.object({
148
+ exposure: z.number().finite().min(-4).max(4),
149
+ contrast: z.number().finite().min(-1).max(1),
150
+ saturation: z.number().finite().min(-1).max(1),
151
+ temperature: z.number().finite().min(-100).max(100),
152
+ tint: z.number().finite().min(-100).max(100),
153
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
154
+ }),
155
+ }),
156
+ z.object({
157
+ type: z.literal("audio-source"),
158
+ mediaId: z.string().min(1),
159
+ sourceDigest: z.string().min(1).optional(),
160
+ source: z.string().min(1).optional(),
161
+ }),
162
+ z.object({
163
+ type: z.literal("visual-content"),
164
+ mediaId: z.string().min(1),
165
+ label: z.string().min(1),
166
+ labelKind: z.enum(["scene", "subject"]).optional(),
167
+ minConfidence: z.number().finite().min(0).max(1).optional(),
168
+ }),
169
+ z.object({
170
+ type: z.literal("duration"),
171
+ target: z.literal("timeline"),
172
+ expectedSeconds: z.number().finite().nonnegative(),
173
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
174
+ }),
175
+ z.object({
176
+ type: z.literal("stream"),
177
+ target: z.enum(["audio", "video"]),
178
+ expected: z.boolean(),
179
+ }),
180
+ z.object({
181
+ type: z.literal("structure"),
182
+ requirement: z.enum(["media-present", "occurrence-present", "operation-present"]),
183
+ mediaId: z.string().min(1).optional(),
184
+ occurrenceId: z.string().min(1).optional(),
185
+ operationType: z.string().min(1).optional(),
186
+ }),
187
+ ]);
188
+ const verificationPolicySchema = z.object({
189
+ requireExpectedChange: z.boolean().optional(),
190
+ maxTruePeakDb: z.number().finite().optional(),
191
+ requireSpeechContinuity: z.boolean().optional(),
192
+ targetLufs: z.number().finite().optional(),
193
+ loudnessToleranceDb: z.number().finite().nonnegative().optional(),
194
+ assertions: z.array(verificationAssertionSchema).optional(),
195
+ }).strict();
42
196
  const editToolInputSchema = z.object({
43
- type: z.enum(["rename-clip", "trim-clip", "set-gain", "ripple-delete", "add-marker"]),
197
+ type: z.enum(["rename-clip", "trim-clip", "set-gain", "reduce-noise", "set-color-correction", "ripple-delete", "add-marker"]),
44
198
  clipId: z.string().min(1).optional(),
45
199
  name: z.string().min(1).optional(),
46
200
  duration: z.number().positive().optional(),
47
201
  durationTime: rationalTimeSchema.optional(),
48
202
  gainDb: z.number().finite().optional(),
203
+ reductionDb: z.number().finite().positive().optional(),
204
+ correction: colorCorrectionSchema.shape.correction.optional(),
49
205
  timelineId: z.string().min(1).optional(),
50
206
  range: rangeSchema.optional(),
51
207
  reason: z.string().optional(),
52
208
  marker: markerSchema.optional(),
53
209
  baseRevision: revisionSchema,
210
+ verification: verificationPolicySchema.optional(),
211
+ }).strict();
212
+ const artifactEditToolInputSchema = editToolInputSchema.extend({
213
+ artifactPath: z.string().trim().min(1),
214
+ baseRevision: revisionValueSchema,
215
+ }).strict();
216
+ const editorTimelineEditToolInputSchema = editToolInputSchema.extend({
217
+ projectId: z.string().trim().min(1),
218
+ sequenceId: z.string().trim().min(1),
219
+ baseRevision: revisionValueSchema,
220
+ }).strict();
221
+ const artifactPublishInputSchema = z.object({
222
+ artifactPath: z.string().trim().min(1),
223
+ transactionId: z.string().min(1),
224
+ confirm: z.boolean(),
54
225
  }).strict();
55
226
  const workflowOperationSchema = z.discriminatedUnion("type", [
56
227
  renameClipSchema,
57
228
  trimClipSchema,
58
229
  setGainSchema,
230
+ reduceNoiseSchema,
231
+ colorCorrectionSchema,
59
232
  rippleDeleteSchema,
60
233
  addMarkerSchema,
61
234
  z.object({
@@ -70,7 +243,7 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
70
243
  type: z.literal("timeline.media.add"),
71
244
  occurrenceId: z.string().min(1),
72
245
  mediaId: z.string().min(1),
73
- role: z.enum(["video", "music"]),
246
+ role: z.enum(["video", "music", "audio"]),
74
247
  start: z.number().nonnegative(),
75
248
  duration: z.number().positive(),
76
249
  targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
@@ -90,6 +263,45 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
90
263
  duration: z.number().positive(),
91
264
  targetLane: z.number().int().refine((lane) => lane !== 0, "title requires a non-primary lane"),
92
265
  }),
266
+ z.object({
267
+ type: z.literal("timeline.media.move"),
268
+ occurrenceId: z.string().min(1),
269
+ start: z.number().nonnegative(),
270
+ targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
271
+ }),
272
+ z.object({
273
+ type: z.literal("timeline.media.replace"),
274
+ occurrenceId: z.string().min(1),
275
+ mediaId: z.string().min(1),
276
+ duration: z.number().positive().optional(),
277
+ }),
278
+ z.object({
279
+ type: z.literal("timeline.media.remove"),
280
+ occurrenceId: z.string().min(1),
281
+ }),
282
+ z.object({
283
+ type: z.literal("timeline.transition.add"),
284
+ transitionId: z.string().min(1),
285
+ assetId: z.string().min(1),
286
+ beforeClipId: z.string().min(1),
287
+ afterClipId: z.string().min(1),
288
+ duration: z.number().positive(),
289
+ }),
290
+ z.object({
291
+ type: z.literal("timeline.audio.attach"),
292
+ occurrenceId: z.string().min(1),
293
+ targetClipId: z.string().min(1),
294
+ mediaId: z.string().min(1),
295
+ startOffset: z.number().nonnegative().optional(),
296
+ duration: z.number().positive().optional(),
297
+ }),
298
+ z.object({
299
+ type: z.literal("timeline.audio.mix"),
300
+ clipId: z.string().min(1),
301
+ gainDb: z.number().finite().optional(),
302
+ fadeIn: z.number().nonnegative().optional(),
303
+ fadeOut: z.number().nonnegative().optional(),
304
+ }),
93
305
  ]);
94
306
  const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
95
307
  operations.forEach((operation, index) => {
@@ -101,6 +313,14 @@ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRe
101
313
  && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
102
314
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "music requires an explicit non-primary lane" });
103
315
  }
316
+ if (operation.type === "timeline.media.add" && operation.role === "audio"
317
+ && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
318
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "audio requires an explicit non-primary lane" });
319
+ }
320
+ if (operation.type === "timeline.audio.mix"
321
+ && operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
322
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: "audio mix requires a gain or fade change" });
323
+ }
104
324
  });
105
325
  });
106
326
  const musicImportSchema = z.object({
@@ -127,6 +347,7 @@ const musicAddInputSchema = {
127
347
  fadeIn: z.number().nonnegative().optional(),
128
348
  fadeOut: z.number().nonnegative().optional(),
129
349
  ducking: musicDuckingSchema.optional(),
350
+ verification: verificationPolicySchema.optional(),
130
351
  };
131
352
  const fillerRemovalInputSchema = {
132
353
  baseRevision: revisionValueSchema,
@@ -135,6 +356,35 @@ const fillerRemovalInputSchema = {
135
356
  preservePauseMs: z.number().finite().nonnegative().optional(),
136
357
  targetPauseMs: z.number().finite().nonnegative().optional(),
137
358
  };
359
+ const dialogueNormalizationInputSchema = {
360
+ mediaId: z.string().min(1),
361
+ occurrenceId: z.string().min(1),
362
+ baseRevision: revisionValueSchema,
363
+ targetLufs: z.number().finite(),
364
+ toleranceDb: z.number().finite().nonnegative(),
365
+ maxTruePeakDb: z.number().finite(),
366
+ minGainDb: z.number().finite(),
367
+ maxGainDb: z.number().finite(),
368
+ minDialogueDurationSeconds: z.number().finite().nonnegative(),
369
+ };
370
+ const noiseReductionInputSchema = {
371
+ mediaId: z.string().trim().min(1),
372
+ occurrenceId: z.string().trim().min(1),
373
+ baseRevision: revisionValueSchema,
374
+ noiseThresholdDb: z.number().finite(),
375
+ maxReductionDb: z.number().finite().positive(),
376
+ minConfidence: z.number().finite().min(0).max(1),
377
+ };
378
+ const colorCorrectionInputSchema = {
379
+ clipId: z.string().trim().min(1),
380
+ baseRevision: revisionValueSchema,
381
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
382
+ exposure: z.number().finite().min(-4).max(4).optional(),
383
+ contrast: z.number().finite().min(-1).max(1).optional(),
384
+ saturation: z.number().finite().min(-1).max(1).optional(),
385
+ temperature: z.number().finite().min(-100).max(100).optional(),
386
+ tint: z.number().finite().min(-100).max(100).optional(),
387
+ };
138
388
  const nativeEditSchema = z.discriminatedUnion("type", [
139
389
  z.object({ type: z.literal("rename-selected-clip"), name: z.string().min(1) }),
140
390
  z.object({ type: z.literal("trim-selected-clip-to-playhead"), edge: z.enum(["start", "end"]) }),
@@ -152,6 +402,45 @@ const nativeTitlePreviewSchema = {
152
402
  start: rationalTimeSchema.optional(),
153
403
  duration: rationalTimeSchema,
154
404
  };
405
+ const nativeTransitionPreviewSchema = {
406
+ assetId: z.string().min(1),
407
+ beforeOccurrenceHandle: z.string().min(1),
408
+ afterOccurrenceHandle: z.string().min(1),
409
+ duration: rationalTimeSchema,
410
+ };
411
+ const exportAssertionSchema = z.discriminatedUnion("type", [
412
+ z.object({
413
+ type: z.literal("audio-audibility"),
414
+ minAudibleSamples: z.number().int().positive().optional(),
415
+ maxSilenceMs: z.number().finite().nonnegative().optional(),
416
+ }),
417
+ z.object({
418
+ type: z.literal("audio-coverage"),
419
+ expectedSeconds: z.number().finite().positive(),
420
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
421
+ }),
422
+ z.object({
423
+ type: z.literal("audio-loudness"),
424
+ targetLufs: z.number().finite(),
425
+ toleranceDb: z.number().finite().nonnegative().optional(),
426
+ }),
427
+ z.object({
428
+ type: z.literal("audio-source"),
429
+ sourceDigest: z.string().min(1).optional(),
430
+ source: z.string().min(1).optional(),
431
+ }),
432
+ z.object({
433
+ type: z.literal("visual-content"),
434
+ label: z.string().min(1),
435
+ labelKind: z.enum(["scene", "subject"]).optional(),
436
+ minConfidence: z.number().finite().min(0).max(1).optional(),
437
+ }),
438
+ z.object({
439
+ type: z.literal("stream"),
440
+ target: z.enum(["audio", "video"]),
441
+ expected: z.boolean(),
442
+ }),
443
+ ]);
155
444
  const exportExpectationSchema = z.object({
156
445
  durationSeconds: z.number().positive().optional(),
157
446
  durationToleranceSeconds: z.number().nonnegative().optional(),
@@ -160,7 +449,9 @@ const exportExpectationSchema = z.object({
160
449
  frameRate: z.number().positive().optional(),
161
450
  frameRateTolerance: z.number().nonnegative().optional(),
162
451
  hasAudio: z.boolean().optional(),
452
+ assertions: z.array(exportAssertionSchema).optional(),
163
453
  }).optional();
454
+ const exportTransactionSchema = z.string().trim().min(1).optional();
164
455
  const nativeEditToolInputSchema = z.object({
165
456
  type: z.enum([
166
457
  "rename-selected-clip",
@@ -178,6 +469,59 @@ function jsonResult(value) {
178
469
  content: [{ type: "text", text: JSON.stringify(value) }],
179
470
  };
180
471
  }
472
+ function skillErrorResult(error) {
473
+ const value = error && typeof error === "object" ? error : {};
474
+ const message = error instanceof Error ? error.message : String(error);
475
+ const code = error instanceof z.ZodError
476
+ ? "SKILL_INPUT_INVALID"
477
+ : typeof value.code === "string" ? value.code : message.split(":", 1)[0] || "SKILL_ERROR";
478
+ return {
479
+ isError: true,
480
+ content: [{
481
+ type: "text",
482
+ text: JSON.stringify({
483
+ code,
484
+ message,
485
+ ...(value.availability ? { availability: value.availability } : {}),
486
+ }),
487
+ }],
488
+ };
489
+ }
490
+ function skillPreviewResult(preview) {
491
+ const details = preview.plan.details ?? {};
492
+ return jsonResult({
493
+ ...preview,
494
+ ...details,
495
+ plan: { ...preview.plan, ...details },
496
+ });
497
+ }
498
+ function normalizeConnectionStatus(value) {
499
+ if (!value || typeof value !== "object")
500
+ return value;
501
+ const status = value;
502
+ if (!isRuntimeCapabilities(status.capabilities))
503
+ return value;
504
+ const identity = status.identity && typeof status.identity === "object"
505
+ ? status.identity
506
+ : undefined;
507
+ const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
508
+ return {
509
+ ...status,
510
+ capabilities: withCapabilityFamilies(status.capabilities, {
511
+ ...(backend ? { backend, connectionBackend: backend } : {}),
512
+ connection: status.state === "ready",
513
+ }),
514
+ };
515
+ }
516
+ function isRuntimeCapabilities(value) {
517
+ if (!value || typeof value !== "object" || Array.isArray(value))
518
+ return false;
519
+ const capabilities = value;
520
+ return isRecord(capabilities.editor) && isRecord(capabilities.analyzers);
521
+ }
522
+ function isRecord(value) {
523
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
524
+ }
181
525
  function frameResult(value) {
182
526
  const { data, mimeType, ...imageMetadata } = value.image;
183
527
  return {
@@ -194,21 +538,81 @@ function frameResult(value) {
194
538
  };
195
539
  }
196
540
  export function createMcpServer(runtime, options = {}) {
197
- const server = new McpServer({ name: "framekit", version: "0.1.0" });
541
+ runtime.registerBuiltinSkills();
542
+ const server = new McpServer({ name: "framekit", version: "0.1.0" }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
543
+ const nativeTransitionAssets = new Map();
198
544
  server.registerTool("connection.status", {
199
- description: "Read Framekit's Final Cut connection state, setup progress, and live capabilities.",
545
+ description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
200
546
  inputSchema: {},
201
- }, async () => jsonResult(options.connectionStatus?.() ?? {
202
- state: "ready",
203
- editorDetected: false,
204
- extensionInstalled: false,
205
- socketPath: null,
206
- capabilities: null,
207
- lastError: null,
208
- }));
547
+ }, async () => jsonResult(normalizeConnectionStatus(await connectionStatus(options))));
548
+ server.registerTool("skill.list", {
549
+ description: "List registered versioned Framekit Skills with current capability availability.",
550
+ inputSchema: {},
551
+ }, async () => {
552
+ try {
553
+ return jsonResult((await runtime.listSkillAvailability()).map(({ manifest, availability }) => ({
554
+ ...manifest,
555
+ availability,
556
+ })));
557
+ }
558
+ catch (error) {
559
+ return skillErrorResult(error);
560
+ }
561
+ });
562
+ server.registerTool("skill.inspect", {
563
+ description: "Inspect one registered Framekit Skill version and its current capability availability.",
564
+ inputSchema: { skill: z.string().min(1), version: z.string().min(1).optional() },
565
+ }, async ({ skill, version }) => {
566
+ try {
567
+ const { manifest, availability } = await runtime.inspectSkillAvailability(skill, version);
568
+ return jsonResult({ ...manifest, availability });
569
+ }
570
+ catch (error) {
571
+ return skillErrorResult(error);
572
+ }
573
+ });
574
+ server.registerTool("skill.preview", {
575
+ description: "Validate and preview a registered Skill without mutating the editor.",
576
+ inputSchema: {
577
+ skill: z.string().min(1),
578
+ version: z.string().min(1).optional(),
579
+ arguments: z.record(z.unknown()),
580
+ },
581
+ }, async ({ skill, version, arguments: skillArguments }) => {
582
+ try {
583
+ const baseRevision = revisionValueSchema.parse(skillArguments.baseRevision);
584
+ const { baseRevision: _baseRevision, ...input } = skillArguments;
585
+ return skillPreviewResult(await runtime.previewSkill({
586
+ skillId: skill,
587
+ ...(version ? { version } : {}),
588
+ baseRevision,
589
+ input,
590
+ }));
591
+ }
592
+ catch (error) {
593
+ return skillErrorResult(error);
594
+ }
595
+ });
596
+ server.registerTool("skill.execute", {
597
+ description: "Execute only a runtime-issued Skill preview token and return verification/rollback evidence.",
598
+ inputSchema: {
599
+ previewToken: z.string().min(1),
600
+ },
601
+ }, async ({ previewToken }) => {
602
+ try {
603
+ return jsonResult(await runtime.executeSkill(previewToken));
604
+ }
605
+ catch (error) {
606
+ return skillErrorResult(error);
607
+ }
608
+ });
209
609
  server.registerTool("project.inspect", {
210
- description: "Read the current canonical project snapshot.",
610
+ description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
211
611
  }, async () => jsonResult(await runtime.inspectProject()));
612
+ server.registerTool("artifact.inspect", {
613
+ description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
614
+ inputSchema: {},
615
+ }, async () => jsonResult(await runtime.inspectArtifact()));
212
616
  server.registerTool("project.list", {
213
617
  description: "List projects and their stable Final Cut sequence identities, including the active target.",
214
618
  inputSchema: {},
@@ -221,26 +625,44 @@ export function createMcpServer(runtime, options = {}) {
221
625
  },
222
626
  }, async ({ projectId, sequenceId }) => jsonResult(await runtime.selectProject({ projectId, sequenceId })));
223
627
  server.registerTool("editor.inspect", {
224
- description: "Read editor identity and machine-readable Phase 2 capabilities.",
628
+ description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
225
629
  }, async () => {
226
- const inspected = await runtime.inspectEditor();
630
+ const inspected = await inspectMcpEditor(runtime, options);
631
+ const capabilities = inspected.capabilities;
227
632
  return jsonResult({
228
633
  ...inspected,
229
634
  capabilities: {
230
- ...inspected.capabilities,
635
+ ...capabilities,
231
636
  editor: {
232
- ...inspected.capabilities.editor,
233
- timelinePublishNewProject: Boolean(options.projectPublisher),
234
- videoExport: Boolean(options.videoExporter?.isAvailable()),
637
+ ...capabilities.editor,
638
+ artifactPublish: Boolean(capabilities.editor.artifactPublish ?? capabilities.editor.timelinePublishNewProject),
235
639
  },
236
640
  },
237
- ...(options.nativeEditor ? { native: options.nativeEditor.capabilities() } : {}),
238
641
  });
239
642
  });
240
643
  server.registerTool("editing.intent.resolve", {
241
644
  description: "Map a supported natural-language editing request to one explicit operation without executing it.",
242
645
  inputSchema: { request: z.string().trim().min(1) },
243
646
  }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
647
+ server.registerTool("editing.route", {
648
+ description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
649
+ inputSchema: {
650
+ operation: z.enum([
651
+ "timeline.edit",
652
+ "editor.native.edit",
653
+ "timeline.publish.new-project",
654
+ "timeline.export",
655
+ ]),
656
+ fallback: z.enum(["none", "external-renderer"]).optional().default("none"),
657
+ },
658
+ }, async ({ operation, fallback }) => {
659
+ const context = await editingRouteContext(runtime, options);
660
+ return jsonResult(resolveEditingRoute({ operation, fallback }, context));
661
+ });
662
+ server.registerTool("editing.duration.plan", {
663
+ description: "Plan requested duration against unique footage and return explicit quality-preserving alternatives without editing.",
664
+ inputSchema: durationPolicyInputSchema,
665
+ }, async (request) => jsonResult(runtime.planDuration(request)));
244
666
  server.registerTool("editor.native.inspect", {
245
667
  description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
246
668
  inputSchema: {},
@@ -311,6 +733,41 @@ export function createMcpServer(runtime, options = {}) {
311
733
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
312
734
  return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
313
735
  });
736
+ server.registerTool("editor.native.transition.search", {
737
+ description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
738
+ inputSchema: { query: z.string().trim().min(1) },
739
+ }, async ({ query }) => {
740
+ if (!options.nativeEditor)
741
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
742
+ const matches = await options.nativeEditor.searchTransitions(query);
743
+ for (const match of matches) {
744
+ nativeTransitionAssets.set(match.id, match);
745
+ nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
746
+ }
747
+ return jsonResult(matches);
748
+ });
749
+ server.registerTool("editor.native.transition.add.preview", {
750
+ description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
751
+ inputSchema: nativeTransitionPreviewSchema,
752
+ }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
753
+ if (!options.nativeEditor)
754
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
755
+ const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
756
+ return jsonResult(await options.nativeEditor.previewTransitionAdd({
757
+ asset,
758
+ beforeOccurrenceHandle,
759
+ afterOccurrenceHandle,
760
+ duration,
761
+ }));
762
+ });
763
+ server.registerTool("editor.native.transition.add.execute", {
764
+ description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
765
+ inputSchema: { previewToken: z.string().min(1) },
766
+ }, async ({ previewToken }) => {
767
+ if (!options.nativeEditor)
768
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
769
+ return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
770
+ });
314
771
  server.registerTool("editor.native.undo", {
315
772
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
316
773
  inputSchema: { operationId: z.string().min(1) },
@@ -447,29 +904,112 @@ export function createMcpServer(runtime, options = {}) {
447
904
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
448
905
  return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
449
906
  });
907
+ server.registerTool("artifact.publish", {
908
+ description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
909
+ inputSchema: artifactPublishInputSchema,
910
+ }, async ({ artifactPath, transactionId, confirm }) => {
911
+ if (!options.projectPublisher)
912
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
913
+ const transaction = runtime.getTransaction(transactionId);
914
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
915
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
916
+ }
917
+ if (!transaction.artifactDigest) {
918
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
919
+ }
920
+ const verification = await runtime.verifyTransaction(transactionId);
921
+ if (!verification.passed)
922
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
923
+ return jsonResult(await options.projectPublisher.publishNewProject({
924
+ sourceTransactionId: transactionId,
925
+ artifactPath,
926
+ artifactDigest: transaction.artifactDigest,
927
+ confirm,
928
+ }));
929
+ });
450
930
  server.registerTool("timeline.publish.new-project", {
451
- description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project.",
931
+ description: "Legacy alias for publishing a verified artifact transaction as a new Final Cut project.",
452
932
  inputSchema: { transactionId: z.string().min(1) },
453
933
  }, async ({ transactionId }) => {
454
- if (!options.projectPublisher)
934
+ if (!options.projectPublisher?.isAvailable())
455
935
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
936
+ const transaction = runtime.getTransaction(transactionId);
937
+ if (transaction.target?.kind !== "artifact") {
938
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for a managed artifact`);
939
+ }
940
+ if (!transaction.artifactDigest) {
941
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
942
+ }
456
943
  const verification = await runtime.verifyTransaction(transactionId);
457
944
  if (!verification.passed)
458
945
  throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
459
- return jsonResult(await options.projectPublisher.publishNewProject(transactionId));
946
+ return jsonResult(await options.projectPublisher.publishNewProject({
947
+ sourceTransactionId: transactionId,
948
+ artifactPath: transaction.target.artifactPath,
949
+ artifactDigest: transaction.artifactDigest,
950
+ confirm: true,
951
+ }));
460
952
  });
461
953
  server.registerTool("timeline.export", {
462
- description: "Export the active Final Cut timeline to a local video file, wait for completion, and verify its media metadata.",
954
+ description: "Export the active Final Cut timeline to a local video file, wait for completion, verify its media metadata, and optionally bind the result to a verified edit transaction.",
463
955
  inputSchema: {
464
956
  outputPath: z.string().trim().min(1),
465
957
  preset: z.enum(["master", "web"]),
466
958
  overwrite: z.boolean().optional(),
467
959
  expected: exportExpectationSchema,
960
+ transactionId: exportTransactionSchema,
468
961
  },
469
- }, async ({ outputPath, preset, overwrite, expected }) => {
962
+ }, async ({ outputPath, preset, overwrite, expected, transactionId }) => {
470
963
  if (!options.videoExporter?.isAvailable())
471
964
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut video export is not configured");
472
- return jsonResult(await options.videoExporter.exportVideo({ outputPath, preset, overwrite, expected }));
965
+ const transaction = transactionId ? runtime.getTransaction(transactionId) : undefined;
966
+ if (transactionId) {
967
+ if (!transaction)
968
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} was not found`);
969
+ if (transaction.status !== "VERIFIED") {
970
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} is not verified`);
971
+ }
972
+ const verification = await runtime.verifyTransaction(transactionId);
973
+ if (!verification.passed) {
974
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} did not pass verification`);
975
+ }
976
+ const current = await runtime.inspectProject();
977
+ if (current.projectId !== transaction.after.projectId
978
+ || current.timeline.id !== transaction.after.timeline.id
979
+ || current.revision.id !== transaction.after.revision.id
980
+ || current.revision.sequence !== transaction.after.revision.sequence) {
981
+ throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not for the active project and sequence`);
982
+ }
983
+ }
984
+ const result = await options.videoExporter.exportVideo({ outputPath, preset, overwrite, expected });
985
+ if (!transaction || !transactionId)
986
+ return jsonResult(result);
987
+ const currentAfterExport = await runtime.inspectProject();
988
+ if (currentAfterExport.projectId !== transaction.after.projectId
989
+ || currentAfterExport.timeline.id !== transaction.after.timeline.id
990
+ || currentAfterExport.revision.id !== transaction.after.revision.id
991
+ || currentAfterExport.revision.sequence !== transaction.after.revision.sequence) {
992
+ throw new Error(`STALE_CONTEXT: transaction ${transactionId} changed while the export was running`);
993
+ }
994
+ return jsonResult({
995
+ ...result,
996
+ manifest: {
997
+ schemaVersion: 1,
998
+ transactionId,
999
+ sourceRevision: transaction.after.revision,
1000
+ project: { id: transaction.after.projectId, name: transaction.after.projectName },
1001
+ sequence: { id: transaction.after.timeline.id, name: transaction.after.timeline.name },
1002
+ timelineDurationSeconds: transaction.after.timeline.duration,
1003
+ media: transaction.after.media.map((media) => ({
1004
+ mediaId: media.mediaId,
1005
+ ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
1006
+ })),
1007
+ output: {
1008
+ format: result.metadata.format,
1009
+ digest: result.metadata.outputDigest,
1010
+ },
1011
+ },
1012
+ });
473
1013
  });
474
1014
  server.registerTool("context.inspect", {
475
1015
  description: "Read the queryable agent editing context and its current revision.",
@@ -519,6 +1059,10 @@ export function createMcpServer(runtime, options = {}) {
519
1059
  description: "Search normalized media references by id or source path.",
520
1060
  inputSchema: { query: z.string() },
521
1061
  }, async ({ query }) => jsonResult(await runtime.searchMedia(query)));
1062
+ server.registerTool("media.index", {
1063
+ description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
1064
+ inputSchema: mediaIndexQuerySchema.shape,
1065
+ }, async (query) => jsonResult(await runtime.indexMedia(query)));
522
1066
  server.registerTool("visual.analyze", {
523
1067
  description: "Analyze scenes, subjects, motion, and keyframes for one media item.",
524
1068
  inputSchema: {
@@ -530,6 +1074,10 @@ export function createMcpServer(runtime, options = {}) {
530
1074
  description: "Return combined speech, audio, and visual understanding for one media item.",
531
1075
  inputSchema: { mediaId: z.string().min(1) },
532
1076
  }, async ({ mediaId }) => jsonResult(await runtime.understandMedia(mediaId)));
1077
+ server.registerTool("rough-cut.plan", {
1078
+ description: "Create a deterministic, explainable, read-only shot plan from analyzed media; does not mutate the timeline.",
1079
+ inputSchema: roughCutPlanSchema.shape,
1080
+ }, async (request) => jsonResult(await runtime.planRoughCut(request)));
533
1081
  server.registerTool("editor.assets", {
534
1082
  description: "Search editor-native transitions, effects, titles, generators, and templates.",
535
1083
  inputSchema: {
@@ -550,9 +1098,34 @@ export function createMcpServer(runtime, options = {}) {
550
1098
  }));
551
1099
  });
552
1100
  server.registerTool("timeline.edit", {
553
- description: "Apply one supported edit and return read-after-write plus its diff.",
1101
+ description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
554
1102
  inputSchema: editToolInputSchema,
555
- }, async (input) => jsonResult(await runtime.edit(editOperationSchema.parse(input))));
1103
+ }, async (input) => {
1104
+ await requireEditingRoute(runtime, options, "timeline.edit");
1105
+ return jsonResult(await runtime.edit(editOperationSchema.parse(input), input.verification ?? {}));
1106
+ });
1107
+ server.registerTool("rough-cut.construction.plan", {
1108
+ description: "Build a deterministic ordered rough-cut construction plan without changing the active project.",
1109
+ inputSchema: roughCutConstructionPlanInputSchema,
1110
+ }, async (request) => jsonResult(await runtime.planRoughCutConstruction(request)));
1111
+ server.registerTool("rough-cut.construction.preview", {
1112
+ description: "Preview a deterministic rough cut with capability and revision checks before execution.",
1113
+ inputSchema: roughCutConstructionPlanInputSchema,
1114
+ }, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
1115
+ server.registerTool("artifact.edit", {
1116
+ description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
1117
+ inputSchema: artifactEditToolInputSchema,
1118
+ }, async (input) => {
1119
+ const { artifactPath, verification, ...operation } = input;
1120
+ return jsonResult(await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {}));
1121
+ });
1122
+ server.registerTool("editor.timeline.edit", {
1123
+ 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.",
1124
+ inputSchema: editorTimelineEditToolInputSchema,
1125
+ }, async (input) => {
1126
+ const { projectId, sequenceId, verification, ...operation } = input;
1127
+ return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1128
+ });
556
1129
  server.registerTool("music.add", {
557
1130
  description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
558
1131
  inputSchema: musicAddInputSchema,
@@ -566,16 +1139,50 @@ export function createMcpServer(runtime, options = {}) {
566
1139
  inputSchema: { previewToken: z.string().min(1) },
567
1140
  }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
568
1141
  server.registerTool("timeline.edit.preview", {
569
- description: "Validate and preview one ordered, atomic Basic Editing MVP workflow without mutating the project.",
1142
+ description: "Validate and preview one ordered, atomic Basic Editing MVP workflow after editing.route confirms capabilities; do not mutate the project.",
570
1143
  inputSchema: {
571
1144
  baseRevision: revisionValueSchema,
572
1145
  operations: workflowOperationsSchema,
1146
+ verification: verificationPolicySchema.optional(),
573
1147
  },
574
- }, async (request) => jsonResult(await runtime.previewEdit(request)));
575
- server.registerTool("timeline.edit.execute", {
576
- description: "Execute one short-lived composite edit preview token exactly once and verify the transaction.",
1148
+ }, async (request) => {
1149
+ await requireEditingRoute(runtime, options, "timeline.edit");
1150
+ return jsonResult(await runtime.previewEdit(request));
1151
+ });
1152
+ server.registerTool("artifact.edit.preview", {
1153
+ description: "Validate and preview an ordered artifact edit against the identified FCPXML artifact without mutating it.",
1154
+ inputSchema: {
1155
+ artifactPath: z.string().trim().min(1),
1156
+ baseRevision: revisionValueSchema,
1157
+ operations: workflowOperationsSchema,
1158
+ verification: verificationPolicySchema.optional(),
1159
+ },
1160
+ }, async ({ artifactPath, baseRevision, operations, verification }) => jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1161
+ server.registerTool("editor.timeline.edit.preview", {
1162
+ description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
1163
+ inputSchema: {
1164
+ projectId: z.string().trim().min(1),
1165
+ sequenceId: z.string().trim().min(1),
1166
+ baseRevision: revisionValueSchema,
1167
+ operations: workflowOperationsSchema,
1168
+ verification: verificationPolicySchema.optional(),
1169
+ },
1170
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1171
+ server.registerTool("artifact.edit.execute", {
1172
+ description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
1173
+ inputSchema: { previewToken: z.string().min(1) },
1174
+ }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1175
+ server.registerTool("editor.timeline.edit.execute", {
1176
+ description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
577
1177
  inputSchema: { previewToken: z.string().min(1) },
578
1178
  }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1179
+ server.registerTool("timeline.edit.execute", {
1180
+ description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1181
+ inputSchema: { previewToken: z.string().min(1) },
1182
+ }, async ({ previewToken }) => {
1183
+ await requireEditingRoute(runtime, options, "timeline.edit");
1184
+ return jsonResult(await runtime.executeEdit(previewToken));
1185
+ });
579
1186
  server.registerTool("speech.analyze", {
580
1187
  description: "Analyze speech words and filler markers for one media item.",
581
1188
  inputSchema: { mediaId: z.string().min(1) },
@@ -592,6 +1199,40 @@ export function createMcpServer(runtime, options = {}) {
592
1199
  description: "Analyze loudness, true peak, and silence for one media item.",
593
1200
  inputSchema: { mediaId: z.string().min(1) },
594
1201
  }, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
1202
+ server.registerTool("audio.noise.analyze", {
1203
+ description: "Analyze unwanted background noise for one media item when a noise analyzer is configured.",
1204
+ inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
1205
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeNoise(mediaId, range)));
1206
+ server.registerTool("audio.noise.reduce.preview", {
1207
+ description: "Preview a bounded noise-reduction adjustment and its affected ranges without mutating the editor.",
1208
+ inputSchema: noiseReductionInputSchema,
1209
+ }, async (request) => {
1210
+ const { baseRevision, ...input } = request;
1211
+ return skillPreviewResult(await runtime.previewSkill({
1212
+ skillId: "audio-noise-reduction",
1213
+ baseRevision,
1214
+ input,
1215
+ }));
1216
+ });
1217
+ server.registerTool("audio.noise.reduce.execute", {
1218
+ description: "Execute one previewed noise-reduction adjustment and return post-write measurement verification and rollback state.",
1219
+ inputSchema: { previewToken: z.string().min(1) },
1220
+ }, async ({ previewToken }) => jsonResult(await runtime.executeSkill(previewToken)));
1221
+ server.registerTool("color.correction.preview", {
1222
+ description: "Preview a clip-scoped basic color correction with before/after values without mutating the editor.",
1223
+ inputSchema: colorCorrectionInputSchema,
1224
+ }, async (request) => {
1225
+ const { baseRevision, ...input } = request;
1226
+ return skillPreviewResult(await runtime.previewSkill({
1227
+ skillId: "color-correction",
1228
+ baseRevision,
1229
+ input,
1230
+ }));
1231
+ });
1232
+ server.registerTool("color.correction.execute", {
1233
+ description: "Execute one previewed basic color correction and return the target verification, diff, and rollback state.",
1234
+ inputSchema: { previewToken: z.string().min(1) },
1235
+ }, async ({ previewToken }) => jsonResult(await runtime.executeSkill(previewToken)));
595
1236
  server.registerTool("edit.diff", {
596
1237
  description: "Read the deterministic diff for a completed edit transaction.",
597
1238
  inputSchema: { transactionId: z.string().min(1) },
@@ -615,3 +1256,109 @@ async function resolveNativeTitleAsset(runtime, assetId) {
615
1256
  throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
616
1257
  return asset;
617
1258
  }
1259
+ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
1260
+ const cachedAsset = nativeTransitionAssets.get(assetId);
1261
+ if (cachedAsset)
1262
+ return cachedAsset;
1263
+ let assets = [];
1264
+ try {
1265
+ assets = await runtime.listAssets({ kind: "transition" });
1266
+ }
1267
+ catch {
1268
+ // A native-only session may not expose the runtime asset registry. Native
1269
+ // discovery below remains the source of truth in that case.
1270
+ }
1271
+ const asset = assets.find((candidate) => candidate.id === assetId);
1272
+ // The runtime registry identifies installed assets by filesystem metadata;
1273
+ // transition placement must use the stable identity returned by Final Cut's
1274
+ // Transitions browser. Resolve registry assets back through native discovery
1275
+ // instead of fabricating a native identity from the registry id.
1276
+ const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
1277
+ const matchingNativeMatches = asset
1278
+ ? nativeMatches.filter((candidate) => candidate.name === asset.name)
1279
+ : nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
1280
+ if (asset && matchingNativeMatches.length > 1) {
1281
+ throw new Error(`TRANSITION_ASSET_AMBIGUOUS: native transition name ${asset.name} has multiple stable identities`);
1282
+ }
1283
+ const nativeMatch = matchingNativeMatches[0];
1284
+ if (!nativeMatch)
1285
+ throw new Error(`TRANSITION_ASSET_NOT_FOUND: installed transition asset ${assetId} was not discovered`);
1286
+ return nativeMatch;
1287
+ }
1288
+ async function connectionStatus(options) {
1289
+ return await options.connectionStatus?.() ?? {
1290
+ state: "ready",
1291
+ editorDetected: false,
1292
+ extensionInstalled: false,
1293
+ socketPath: null,
1294
+ capabilities: null,
1295
+ };
1296
+ }
1297
+ async function inspectMcpEditor(runtime, options) {
1298
+ const inspected = await runtime.inspectEditor();
1299
+ const native = options.nativeEditor?.capabilities();
1300
+ const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
1301
+ const exportAvailable = Boolean(options.videoExporter?.isAvailable());
1302
+ return {
1303
+ ...inspected,
1304
+ capabilities: withCapabilityFamilies({
1305
+ ...inspected.capabilities,
1306
+ editor: {
1307
+ ...inspected.capabilities.editor,
1308
+ artifactPublish: publishingAvailable,
1309
+ ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
1310
+ videoExport: exportAvailable,
1311
+ },
1312
+ }, {
1313
+ backend: inspected.identity.backend,
1314
+ nativeBackend: "final-cut-accessibility",
1315
+ native: {
1316
+ selectionWrite: Boolean(native?.selectionEdit),
1317
+ undo: Boolean(native?.undo),
1318
+ mediaLibrarySearch: Boolean(native?.mediaLibrarySearch),
1319
+ mediaImport: Boolean(native?.mediaImport),
1320
+ mediaSelection: Boolean(native?.mediaSelection),
1321
+ mediaAppendSelected: Boolean(native?.mediaAppendSelected),
1322
+ timelineOccurrenceLocate: Boolean(native?.timelineOccurrenceLocate),
1323
+ bladeAtPlayhead: Boolean(native?.bladeAtPlayhead),
1324
+ deleteRange: Boolean(native?.deleteRange),
1325
+ trimToDuration: Boolean(native?.trimToDuration),
1326
+ mediaAppend: Boolean(native?.mediaAppend),
1327
+ mediaInsert: Boolean(native?.mediaInsert),
1328
+ titlePlacement: Boolean(native?.titlePlacement),
1329
+ transitionDiscovery: Boolean(native?.transitionDiscovery),
1330
+ transitionPlacement: Boolean(native?.transitionPlacement),
1331
+ timelineFocus: Boolean(native?.timelineFocus),
1332
+ projectCreation: false,
1333
+ clipInsertion: false,
1334
+ clipMovement: false,
1335
+ },
1336
+ publishing: publishingAvailable,
1337
+ publishingBackend: "fcpxml-publisher",
1338
+ export: exportAvailable,
1339
+ exportBackend: "final-cut-native-export",
1340
+ }),
1341
+ ...(native ? { native } : {}),
1342
+ };
1343
+ }
1344
+ async function requireEditingRoute(runtime, options, operation) {
1345
+ const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
1346
+ if (route.status !== "editor-selected") {
1347
+ throw new Error(`${route.reason.code}: ${route.reason.message}`);
1348
+ }
1349
+ }
1350
+ async function editingRouteContext(runtime, options) {
1351
+ const connection = await connectionStatus(options);
1352
+ let editor;
1353
+ try {
1354
+ editor = await inspectMcpEditor(runtime, options);
1355
+ }
1356
+ catch {
1357
+ editor = undefined;
1358
+ }
1359
+ return {
1360
+ connection,
1361
+ ...(editor ? { editor } : {}),
1362
+ ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
1363
+ };
1364
+ }