@morshoto/framekit 0.1.0 → 0.1.5

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 (65) hide show
  1. package/README.md +42 -17
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +86 -2
  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 +70 -9
  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 +242 -30
  9. package/dist-package/adapters/final-cut/typescript/src/session.js +86 -9
  10. package/dist-package/apps/mcp-server/src/main.js +10 -1
  11. package/dist-package/apps/mcp-server/src/routing.js +172 -0
  12. package/dist-package/apps/mcp-server/src/server.js +867 -52
  13. package/dist-package/apps/mcp-server/src/version.js +34 -0
  14. package/dist-package/packages/runtime/src/application/duration-policy-service.js +6 -0
  15. package/dist-package/packages/runtime/src/application/media-analysis-service.js +473 -0
  16. package/dist-package/packages/runtime/src/application/project-service.js +146 -0
  17. package/dist-package/packages/runtime/src/application/runtime-options.js +1 -0
  18. package/dist-package/packages/runtime/src/application/transaction-store.js +12 -0
  19. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +64 -0
  20. package/dist-package/packages/runtime/src/audio/noise-reduction.js +46 -0
  21. package/dist-package/packages/runtime/src/capabilities.js +187 -1
  22. package/dist-package/packages/runtime/src/color-correction.js +48 -0
  23. package/dist-package/packages/runtime/src/context/context-engine.js +20 -6
  24. package/dist-package/packages/runtime/src/context/context-service.js +30 -0
  25. package/dist-package/packages/runtime/src/context/revision.js +3 -0
  26. package/dist-package/packages/runtime/src/domain/capabilities.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/context.js +1 -0
  28. package/dist-package/packages/runtime/src/domain/diff.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/duration.js +1 -0
  30. package/dist-package/packages/runtime/src/domain/editing.js +1 -0
  31. package/dist-package/packages/runtime/src/domain/index.js +12 -0
  32. package/dist-package/packages/runtime/src/domain/media.js +8 -0
  33. package/dist-package/packages/runtime/src/domain/ports.js +1 -0
  34. package/dist-package/packages/runtime/src/domain/primitives.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/project.js +1 -0
  36. package/dist-package/packages/runtime/src/domain/rough-cut.js +69 -0
  37. package/dist-package/packages/runtime/src/domain/skills.js +33 -0
  38. package/dist-package/packages/runtime/src/domain/types.js +5 -1
  39. package/dist-package/packages/runtime/src/domain/verification.js +1 -0
  40. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.js +141 -0
  41. package/dist-package/packages/runtime/src/editing/duration-policy.js +187 -0
  42. package/dist-package/packages/runtime/src/editing/edit-service.js +449 -0
  43. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +361 -0
  44. package/dist-package/packages/runtime/src/editing/music-service.js +85 -0
  45. package/dist-package/packages/runtime/src/index.js +14 -3
  46. package/dist-package/packages/runtime/src/planning/rough-cut.js +71 -0
  47. package/dist-package/packages/runtime/src/runtime.js +131 -826
  48. package/dist-package/packages/runtime/src/skills/builtin.js +339 -0
  49. package/dist-package/packages/runtime/src/skills/index.js +3 -0
  50. package/dist-package/packages/runtime/src/skills/registry.js +74 -0
  51. package/dist-package/packages/runtime/src/skills/requirements.js +170 -0
  52. package/dist-package/packages/runtime/src/skills/runtime.js +239 -0
  53. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  54. package/dist-package/packages/runtime/src/speech/filler-detector.js +132 -0
  55. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  56. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.js +314 -0
  57. package/dist-package/packages/runtime/src/timeline/rational-time.js +63 -0
  58. package/dist-package/packages/runtime/src/verification/verification.js +712 -1
  59. package/dist-package/packages/testkit/src/fixture-analyzers.js +28 -0
  60. package/dist-package/packages/testkit/src/in-memory-editor.js +287 -3
  61. package/dist-package/packages/testkit/src/index.js +1 -0
  62. package/dist-package/packages/testkit/src/skill-fixtures.js +64 -0
  63. package/package.json +17 -8
  64. /package/dist-package/packages/runtime/src/{diff/diff.js → timeline/snapshot-diff.js} +0 -0
  65. /package/dist-package/packages/runtime/src/{snapshot-digest.js → timeline/snapshot-digest.js} +0 -0
@@ -1,6 +1,9 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
2
3
  import { z } from "zod";
3
- import { resolveEditingIntent } from "../../../packages/runtime/src/index.js";
4
+ import { createCapabilityPreflight, resolveEditingIntent, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
5
+ import { EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
6
+ import { FRAMEKIT_VERSION } from "./version.js";
4
7
  const revisionValueSchema = z.object({
5
8
  id: z.string(),
6
9
  sequence: z.number().int().nonnegative(),
@@ -14,6 +17,44 @@ const rationalTimeSchema = z.object({
14
17
  const rangeSchema = z.object({
15
18
  start: z.number().nonnegative(),
16
19
  end: z.number().positive(),
20
+ }).refine((range) => range.end > range.start, {
21
+ message: "end must be greater than start",
22
+ path: ["end"],
23
+ });
24
+ const mediaIndexQuerySchema = z.object({
25
+ query: z.string().optional(),
26
+ subject: z.string().optional(),
27
+ scene: z.string().optional(),
28
+ environment: z.string().optional(),
29
+ timeOfDay: z.string().optional(),
30
+ mood: z.string().optional(),
31
+ motion: z.enum(["static", "low", "medium", "high"]).optional(),
32
+ range: rangeSchema.optional(),
33
+ capabilities: z.array(z.enum(["metadata", "speech", "audio", "noise", "visual"])).optional(),
34
+ });
35
+ const roughCutPlanSchema = mediaIndexQuerySchema.extend({
36
+ maxShots: z.number().int().positive().optional(),
37
+ });
38
+ const durationRangeSchema = z.object({
39
+ startSeconds: z.number().finite().nonnegative(),
40
+ endSeconds: z.number().finite().positive(),
41
+ });
42
+ const durationPolicyInputSchema = z.object({
43
+ requestedDurationSeconds: z.number().finite().positive(),
44
+ footage: z.array(z.object({
45
+ id: z.string().trim().min(1),
46
+ durationSeconds: z.number().finite().positive(),
47
+ usableDurationSeconds: z.number().finite().positive().optional(),
48
+ usableRanges: z.array(durationRangeSchema).optional(),
49
+ reusable: z.boolean().optional(),
50
+ })),
51
+ constraint: z.enum(["hard", "soft"]).optional(),
52
+ permissions: z.object({
53
+ allowReuse: z.boolean().optional(),
54
+ allowSlowMotion: z.boolean().optional(),
55
+ allowGeneratedAssets: z.boolean().optional(),
56
+ }).optional(),
57
+ actualDurationSeconds: z.number().finite().nonnegative().optional(),
17
58
  });
18
59
  const markerSchema = z.object({
19
60
  id: z.string().min(1),
@@ -30,32 +71,206 @@ const trimClipSchema = z.object({
30
71
  baseRevision: revisionSchema,
31
72
  });
32
73
  const setGainSchema = z.object({ type: z.literal("set-gain"), clipId: z.string().min(1), gainDb: z.number().finite(), baseRevision: revisionSchema });
74
+ const reduceNoiseSchema = z.object({
75
+ type: z.literal("reduce-noise"),
76
+ clipId: z.string().min(1),
77
+ range: rangeSchema,
78
+ reductionDb: z.number().finite().positive(),
79
+ baseRevision: revisionSchema,
80
+ });
81
+ const colorCorrectionSchema = z.object({
82
+ type: z.literal("set-color-correction"),
83
+ clipId: z.string().min(1),
84
+ correction: z.object({
85
+ exposure: z.number().finite().min(-4).max(4),
86
+ contrast: z.number().finite().min(-1).max(1),
87
+ saturation: z.number().finite().min(-1).max(1),
88
+ temperature: z.number().finite().min(-100).max(100),
89
+ tint: z.number().finite().min(-100).max(100),
90
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
91
+ }),
92
+ baseRevision: revisionSchema,
93
+ });
33
94
  const rippleDeleteSchema = z.object({ type: z.literal("ripple-delete"), timelineId: z.string().min(1), range: rangeSchema, reason: z.string().optional(), baseRevision: revisionSchema });
34
95
  const addMarkerSchema = z.object({ type: z.literal("add-marker"), timelineId: z.string().min(1), marker: markerSchema, baseRevision: revisionSchema });
96
+ const roughCutImportSchema = z.object({
97
+ type: z.literal("media.import"),
98
+ mediaId: z.string().min(1),
99
+ source: z.string().min(1),
100
+ mediaKind: z.literal("video"),
101
+ duration: z.number().positive(),
102
+ sourceDigest: z.string().min(1),
103
+ });
104
+ const roughCutShotSchema = z.object({
105
+ occurrenceId: z.string().min(1),
106
+ mediaId: z.string().min(1),
107
+ duration: z.number().positive().optional(),
108
+ });
109
+ const roughCutConstructionPlanInputSchema = {
110
+ baseRevision: revisionValueSchema,
111
+ imports: z.array(roughCutImportSchema).optional(),
112
+ shots: z.array(roughCutShotSchema).min(1),
113
+ };
35
114
  const editOperationSchema = z.discriminatedUnion("type", [
36
115
  renameClipSchema,
37
116
  trimClipSchema,
38
117
  setGainSchema,
118
+ reduceNoiseSchema,
119
+ colorCorrectionSchema,
39
120
  rippleDeleteSchema,
40
121
  addMarkerSchema,
41
122
  ]);
42
- const editToolInputSchema = z.object({
43
- type: z.enum(["rename-clip", "trim-clip", "set-gain", "ripple-delete", "add-marker"]),
44
- clipId: z.string().min(1).optional(),
45
- name: z.string().min(1).optional(),
46
- duration: z.number().positive().optional(),
47
- durationTime: rationalTimeSchema.optional(),
48
- gainDb: z.number().finite().optional(),
49
- timelineId: z.string().min(1).optional(),
50
- range: rangeSchema.optional(),
51
- reason: z.string().optional(),
52
- marker: markerSchema.optional(),
53
- baseRevision: revisionSchema,
123
+ const verificationAssertionSchema = z.discriminatedUnion("type", [
124
+ z.object({
125
+ type: z.literal("audio-audibility"),
126
+ mediaId: z.string().min(1),
127
+ minAudibleSamples: z.number().int().positive().optional(),
128
+ maxSilenceMs: z.number().finite().nonnegative().optional(),
129
+ }),
130
+ z.object({
131
+ type: z.literal("audio-coverage"),
132
+ mediaId: z.string().min(1),
133
+ start: z.number().finite().nonnegative(),
134
+ duration: z.number().finite().positive(),
135
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
136
+ }),
137
+ z.object({
138
+ type: z.literal("audio-loudness"),
139
+ mediaId: z.string().min(1),
140
+ targetLufs: z.number().finite(),
141
+ toleranceDb: z.number().finite().nonnegative().optional(),
142
+ }),
143
+ z.object({
144
+ type: z.literal("audio-noise"),
145
+ mediaId: z.string().min(1),
146
+ maxNoiseFloorDb: z.number().finite(),
147
+ minConfidence: z.number().finite().min(0).max(1).optional(),
148
+ }),
149
+ z.object({
150
+ type: z.literal("color-correction"),
151
+ clipId: z.string().min(1),
152
+ expected: z.object({
153
+ exposure: z.number().finite().min(-4).max(4),
154
+ contrast: z.number().finite().min(-1).max(1),
155
+ saturation: z.number().finite().min(-1).max(1),
156
+ temperature: z.number().finite().min(-100).max(100),
157
+ tint: z.number().finite().min(-100).max(100),
158
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
159
+ }),
160
+ }),
161
+ z.object({
162
+ type: z.literal("audio-source"),
163
+ mediaId: z.string().min(1),
164
+ sourceDigest: z.string().min(1).optional(),
165
+ source: z.string().min(1).optional(),
166
+ }),
167
+ z.object({
168
+ type: z.literal("visual-content"),
169
+ mediaId: z.string().min(1),
170
+ label: z.string().min(1),
171
+ labelKind: z.enum(["scene", "subject"]).optional(),
172
+ minConfidence: z.number().finite().min(0).max(1).optional(),
173
+ }),
174
+ z.object({
175
+ type: z.literal("duration"),
176
+ target: z.literal("timeline"),
177
+ expectedSeconds: z.number().finite().nonnegative(),
178
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
179
+ }),
180
+ z.object({
181
+ type: z.literal("stream"),
182
+ target: z.enum(["audio", "video"]),
183
+ expected: z.boolean(),
184
+ }),
185
+ z.object({
186
+ type: z.literal("structure"),
187
+ requirement: z.enum(["media-present", "occurrence-present", "operation-present"]),
188
+ mediaId: z.string().min(1).optional(),
189
+ occurrenceId: z.string().min(1).optional(),
190
+ operationType: z.string().min(1).optional(),
191
+ }),
192
+ ]);
193
+ const verificationPolicySchema = z.object({
194
+ requireExpectedChange: z.boolean().optional(),
195
+ maxTruePeakDb: z.number().finite().optional(),
196
+ requireSpeechContinuity: z.boolean().optional(),
197
+ targetLufs: z.number().finite().optional(),
198
+ loudnessToleranceDb: z.number().finite().nonnegative().optional(),
199
+ assertions: z.array(verificationAssertionSchema).optional(),
200
+ }).strict();
201
+ function mcpObjectSchema(schema) {
202
+ // The MCP SDK only serializes schemas it recognizes as object-shaped.
203
+ Object.defineProperty(schema, "shape", { value: {}, enumerable: false });
204
+ return schema;
205
+ }
206
+ function mcpDiscriminatedUnion(options) {
207
+ const schema = z.discriminatedUnion("type", options);
208
+ return mcpObjectSchema(schema);
209
+ }
210
+ function mcpUnion(options) {
211
+ const schema = z.union(options);
212
+ return mcpObjectSchema(schema);
213
+ }
214
+ function createEditToolInputSchema(target = {}, baseRevision = revisionSchema) {
215
+ const options = [
216
+ renameClipSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
217
+ trimClipSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
218
+ setGainSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
219
+ reduceNoiseSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
220
+ colorCorrectionSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
221
+ rippleDeleteSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
222
+ addMarkerSchema.extend({ ...target, verification: verificationPolicySchema.optional(), baseRevision }).strict(),
223
+ ];
224
+ return mcpDiscriminatedUnion(options);
225
+ }
226
+ const editToolInputSchema = createEditToolInputSchema();
227
+ const artifactEditToolInputSchema = createEditToolInputSchema({
228
+ artifactPath: z.string().trim().min(1),
229
+ }, revisionValueSchema);
230
+ const editorTimelineEditToolInputSchema = createEditToolInputSchema({
231
+ projectId: z.string().trim().min(1),
232
+ sequenceId: z.string().trim().min(1),
233
+ }, revisionValueSchema);
234
+ function exposeObjectRoot(schema) {
235
+ if (!isRecord(schema) || !Array.isArray(schema.anyOf))
236
+ return schema;
237
+ const properties = {};
238
+ for (const branch of schema.anyOf) {
239
+ for (const [key, value] of Object.entries(branch.properties ?? {})) {
240
+ if (key !== "type")
241
+ properties[key] = value;
242
+ }
243
+ }
244
+ return { ...schema, type: "object", properties };
245
+ }
246
+ function installMcpSchemaCompatibility(server) {
247
+ const handlers = server.server._requestHandlers;
248
+ const listToolsHandler = handlers?.get("tools/list");
249
+ if (!listToolsHandler)
250
+ throw new Error("MCP tools/list handler was not initialized");
251
+ server.server.removeRequestHandler("tools/list");
252
+ server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
253
+ const response = await listToolsHandler(request, extra);
254
+ return {
255
+ ...response,
256
+ tools: response.tools?.map((tool) => ({
257
+ ...tool,
258
+ inputSchema: exposeObjectRoot(tool.inputSchema),
259
+ })) ?? [],
260
+ };
261
+ });
262
+ }
263
+ const artifactPublishInputSchema = z.object({
264
+ artifactPath: z.string().trim().min(1),
265
+ transactionId: z.string().min(1),
266
+ confirm: z.boolean(),
54
267
  }).strict();
55
268
  const workflowOperationSchema = z.discriminatedUnion("type", [
56
269
  renameClipSchema,
57
270
  trimClipSchema,
58
271
  setGainSchema,
272
+ reduceNoiseSchema,
273
+ colorCorrectionSchema,
59
274
  rippleDeleteSchema,
60
275
  addMarkerSchema,
61
276
  z.object({
@@ -70,7 +285,7 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
70
285
  type: z.literal("timeline.media.add"),
71
286
  occurrenceId: z.string().min(1),
72
287
  mediaId: z.string().min(1),
73
- role: z.enum(["video", "music"]),
288
+ role: z.enum(["video", "music", "audio"]),
74
289
  start: z.number().nonnegative(),
75
290
  duration: z.number().positive(),
76
291
  targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
@@ -90,6 +305,45 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
90
305
  duration: z.number().positive(),
91
306
  targetLane: z.number().int().refine((lane) => lane !== 0, "title requires a non-primary lane"),
92
307
  }),
308
+ z.object({
309
+ type: z.literal("timeline.media.move"),
310
+ occurrenceId: z.string().min(1),
311
+ start: z.number().nonnegative(),
312
+ targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
313
+ }),
314
+ z.object({
315
+ type: z.literal("timeline.media.replace"),
316
+ occurrenceId: z.string().min(1),
317
+ mediaId: z.string().min(1),
318
+ duration: z.number().positive().optional(),
319
+ }),
320
+ z.object({
321
+ type: z.literal("timeline.media.remove"),
322
+ occurrenceId: z.string().min(1),
323
+ }),
324
+ z.object({
325
+ type: z.literal("timeline.transition.add"),
326
+ transitionId: z.string().min(1),
327
+ assetId: z.string().min(1),
328
+ beforeClipId: z.string().min(1),
329
+ afterClipId: z.string().min(1),
330
+ duration: z.number().positive(),
331
+ }),
332
+ z.object({
333
+ type: z.literal("timeline.audio.attach"),
334
+ occurrenceId: z.string().min(1),
335
+ targetClipId: z.string().min(1),
336
+ mediaId: z.string().min(1),
337
+ startOffset: z.number().nonnegative().optional(),
338
+ duration: z.number().positive().optional(),
339
+ }),
340
+ z.object({
341
+ type: z.literal("timeline.audio.mix"),
342
+ clipId: z.string().min(1),
343
+ gainDb: z.number().finite().optional(),
344
+ fadeIn: z.number().nonnegative().optional(),
345
+ fadeOut: z.number().nonnegative().optional(),
346
+ }),
93
347
  ]);
94
348
  const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
95
349
  operations.forEach((operation, index) => {
@@ -101,6 +355,14 @@ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRe
101
355
  && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
102
356
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "music requires an explicit non-primary lane" });
103
357
  }
358
+ if (operation.type === "timeline.media.add" && operation.role === "audio"
359
+ && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
360
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "audio requires an explicit non-primary lane" });
361
+ }
362
+ if (operation.type === "timeline.audio.mix"
363
+ && operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
364
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: "audio mix requires a gain or fade change" });
365
+ }
104
366
  });
105
367
  });
106
368
  const musicImportSchema = z.object({
@@ -114,20 +376,41 @@ const musicDuckingSchema = z.object({
114
376
  dialogueClipIds: z.array(z.string().min(1)).optional(),
115
377
  reductionDb: z.number().finite().optional(),
116
378
  });
117
- const musicAddInputSchema = {
379
+ const musicAddCommonInputSchema = {
118
380
  baseRevision: revisionValueSchema,
119
381
  occurrenceId: z.string().min(1),
120
- mediaId: z.string().min(1).optional(),
121
- import: musicImportSchema.optional(),
122
- placement: z.enum(["append", "insert"]),
123
- start: z.number().nonnegative().optional(),
124
382
  duration: z.number().positive().optional(),
125
383
  targetLane: z.number().int().refine((lane) => lane !== 0, "music requires a non-primary lane"),
126
384
  gainDb: z.number().finite().optional(),
127
385
  fadeIn: z.number().nonnegative().optional(),
128
386
  fadeOut: z.number().nonnegative().optional(),
129
387
  ducking: musicDuckingSchema.optional(),
388
+ verification: verificationPolicySchema.optional(),
130
389
  };
390
+ const musicAddInputSchema = mcpUnion([
391
+ z.object({
392
+ ...musicAddCommonInputSchema,
393
+ mediaId: z.string().min(1),
394
+ placement: z.literal("append"),
395
+ }).strict(),
396
+ z.object({
397
+ ...musicAddCommonInputSchema,
398
+ import: musicImportSchema,
399
+ placement: z.literal("append"),
400
+ }).strict(),
401
+ z.object({
402
+ ...musicAddCommonInputSchema,
403
+ mediaId: z.string().min(1),
404
+ placement: z.literal("insert"),
405
+ start: z.number().nonnegative(),
406
+ }).strict(),
407
+ z.object({
408
+ ...musicAddCommonInputSchema,
409
+ import: musicImportSchema,
410
+ placement: z.literal("insert"),
411
+ start: z.number().nonnegative(),
412
+ }).strict(),
413
+ ]);
131
414
  const fillerRemovalInputSchema = {
132
415
  baseRevision: revisionValueSchema,
133
416
  range: rangeSchema,
@@ -135,6 +418,35 @@ const fillerRemovalInputSchema = {
135
418
  preservePauseMs: z.number().finite().nonnegative().optional(),
136
419
  targetPauseMs: z.number().finite().nonnegative().optional(),
137
420
  };
421
+ const dialogueNormalizationInputSchema = {
422
+ mediaId: z.string().min(1),
423
+ occurrenceId: z.string().min(1),
424
+ baseRevision: revisionValueSchema,
425
+ targetLufs: z.number().finite(),
426
+ toleranceDb: z.number().finite().nonnegative(),
427
+ maxTruePeakDb: z.number().finite(),
428
+ minGainDb: z.number().finite(),
429
+ maxGainDb: z.number().finite(),
430
+ minDialogueDurationSeconds: z.number().finite().nonnegative(),
431
+ };
432
+ const noiseReductionInputSchema = {
433
+ mediaId: z.string().trim().min(1),
434
+ occurrenceId: z.string().trim().min(1),
435
+ baseRevision: revisionValueSchema,
436
+ noiseThresholdDb: z.number().finite(),
437
+ maxReductionDb: z.number().finite().positive(),
438
+ minConfidence: z.number().finite().min(0).max(1),
439
+ };
440
+ const colorCorrectionInputSchema = {
441
+ clipId: z.string().trim().min(1),
442
+ baseRevision: revisionValueSchema,
443
+ preset: z.enum(["neutral", "warm", "cool", "high-contrast"]).optional(),
444
+ exposure: z.number().finite().min(-4).max(4).optional(),
445
+ contrast: z.number().finite().min(-1).max(1).optional(),
446
+ saturation: z.number().finite().min(-1).max(1).optional(),
447
+ temperature: z.number().finite().min(-100).max(100).optional(),
448
+ tint: z.number().finite().min(-100).max(100).optional(),
449
+ };
138
450
  const nativeEditSchema = z.discriminatedUnion("type", [
139
451
  z.object({ type: z.literal("rename-selected-clip"), name: z.string().min(1) }),
140
452
  z.object({ type: z.literal("trim-selected-clip-to-playhead"), edge: z.enum(["start", "end"]) }),
@@ -152,6 +464,45 @@ const nativeTitlePreviewSchema = {
152
464
  start: rationalTimeSchema.optional(),
153
465
  duration: rationalTimeSchema,
154
466
  };
467
+ const nativeTransitionPreviewSchema = {
468
+ assetId: z.string().min(1),
469
+ beforeOccurrenceHandle: z.string().min(1),
470
+ afterOccurrenceHandle: z.string().min(1),
471
+ duration: rationalTimeSchema,
472
+ };
473
+ const exportAssertionSchema = z.discriminatedUnion("type", [
474
+ z.object({
475
+ type: z.literal("audio-audibility"),
476
+ minAudibleSamples: z.number().int().positive().optional(),
477
+ maxSilenceMs: z.number().finite().nonnegative().optional(),
478
+ }),
479
+ z.object({
480
+ type: z.literal("audio-coverage"),
481
+ expectedSeconds: z.number().finite().positive(),
482
+ toleranceSeconds: z.number().finite().nonnegative().optional(),
483
+ }),
484
+ z.object({
485
+ type: z.literal("audio-loudness"),
486
+ targetLufs: z.number().finite(),
487
+ toleranceDb: z.number().finite().nonnegative().optional(),
488
+ }),
489
+ z.object({
490
+ type: z.literal("audio-source"),
491
+ sourceDigest: z.string().min(1).optional(),
492
+ source: z.string().min(1).optional(),
493
+ }),
494
+ z.object({
495
+ type: z.literal("visual-content"),
496
+ label: z.string().min(1),
497
+ labelKind: z.enum(["scene", "subject"]).optional(),
498
+ minConfidence: z.number().finite().min(0).max(1).optional(),
499
+ }),
500
+ z.object({
501
+ type: z.literal("stream"),
502
+ target: z.enum(["audio", "video"]),
503
+ expected: z.boolean(),
504
+ }),
505
+ ]);
155
506
  const exportExpectationSchema = z.object({
156
507
  durationSeconds: z.number().positive().optional(),
157
508
  durationToleranceSeconds: z.number().nonnegative().optional(),
@@ -160,7 +511,9 @@ const exportExpectationSchema = z.object({
160
511
  frameRate: z.number().positive().optional(),
161
512
  frameRateTolerance: z.number().nonnegative().optional(),
162
513
  hasAudio: z.boolean().optional(),
514
+ assertions: z.array(exportAssertionSchema).optional(),
163
515
  }).optional();
516
+ const exportTransactionSchema = z.string().trim().min(1).optional();
164
517
  const nativeEditToolInputSchema = z.object({
165
518
  type: z.enum([
166
519
  "rename-selected-clip",
@@ -178,6 +531,59 @@ function jsonResult(value) {
178
531
  content: [{ type: "text", text: JSON.stringify(value) }],
179
532
  };
180
533
  }
534
+ function skillErrorResult(error) {
535
+ const value = error && typeof error === "object" ? error : {};
536
+ const message = error instanceof Error ? error.message : String(error);
537
+ const code = error instanceof z.ZodError
538
+ ? "SKILL_INPUT_INVALID"
539
+ : typeof value.code === "string" ? value.code : message.split(":", 1)[0] || "SKILL_ERROR";
540
+ return {
541
+ isError: true,
542
+ content: [{
543
+ type: "text",
544
+ text: JSON.stringify({
545
+ code,
546
+ message,
547
+ ...(value.availability ? { availability: value.availability } : {}),
548
+ }),
549
+ }],
550
+ };
551
+ }
552
+ function skillPreviewResult(preview) {
553
+ const details = preview.plan.details ?? {};
554
+ return jsonResult({
555
+ ...preview,
556
+ ...details,
557
+ plan: { ...preview.plan, ...details },
558
+ });
559
+ }
560
+ function normalizeConnectionStatus(value) {
561
+ if (!value || typeof value !== "object")
562
+ return value;
563
+ const status = value;
564
+ if (!isRuntimeCapabilities(status.capabilities))
565
+ return value;
566
+ const identity = status.identity && typeof status.identity === "object"
567
+ ? status.identity
568
+ : undefined;
569
+ const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
570
+ return {
571
+ ...status,
572
+ capabilities: withCapabilityFamilies(status.capabilities, {
573
+ ...(backend ? { backend, connectionBackend: backend } : {}),
574
+ connection: status.state === "ready",
575
+ }),
576
+ };
577
+ }
578
+ function isRuntimeCapabilities(value) {
579
+ if (!value || typeof value !== "object" || Array.isArray(value))
580
+ return false;
581
+ const capabilities = value;
582
+ return isRecord(capabilities.editor) && isRecord(capabilities.analyzers);
583
+ }
584
+ function isRecord(value) {
585
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
586
+ }
181
587
  function frameResult(value) {
182
588
  const { data, mimeType, ...imageMetadata } = value.image;
183
589
  return {
@@ -194,21 +600,81 @@ function frameResult(value) {
194
600
  };
195
601
  }
196
602
  export function createMcpServer(runtime, options = {}) {
197
- const server = new McpServer({ name: "framekit", version: "0.1.0" });
603
+ runtime.registerBuiltinSkills();
604
+ const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
605
+ const nativeTransitionAssets = new Map();
198
606
  server.registerTool("connection.status", {
199
- description: "Read Framekit's Final Cut connection state, setup progress, and live capabilities.",
607
+ description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
200
608
  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
- }));
609
+ }, async () => jsonResult(normalizeConnectionStatus(await connectionStatus(options))));
610
+ server.registerTool("skill.list", {
611
+ description: "List registered versioned Framekit Skills with current capability availability.",
612
+ inputSchema: {},
613
+ }, async () => {
614
+ try {
615
+ return jsonResult((await runtime.listSkillAvailability()).map(({ manifest, availability }) => ({
616
+ ...manifest,
617
+ availability,
618
+ })));
619
+ }
620
+ catch (error) {
621
+ return skillErrorResult(error);
622
+ }
623
+ });
624
+ server.registerTool("skill.inspect", {
625
+ description: "Inspect one registered Framekit Skill version and its current capability availability.",
626
+ inputSchema: { skill: z.string().min(1), version: z.string().min(1).optional() },
627
+ }, async ({ skill, version }) => {
628
+ try {
629
+ const { manifest, availability } = await runtime.inspectSkillAvailability(skill, version);
630
+ return jsonResult({ ...manifest, availability });
631
+ }
632
+ catch (error) {
633
+ return skillErrorResult(error);
634
+ }
635
+ });
636
+ server.registerTool("skill.preview", {
637
+ description: "Validate and preview a registered Skill without mutating the editor.",
638
+ inputSchema: {
639
+ skill: z.string().min(1),
640
+ version: z.string().min(1).optional(),
641
+ arguments: z.record(z.unknown()),
642
+ },
643
+ }, async ({ skill, version, arguments: skillArguments }) => {
644
+ try {
645
+ const baseRevision = revisionValueSchema.parse(skillArguments.baseRevision);
646
+ const { baseRevision: _baseRevision, ...input } = skillArguments;
647
+ return skillPreviewResult(await runtime.previewSkill({
648
+ skillId: skill,
649
+ ...(version ? { version } : {}),
650
+ baseRevision,
651
+ input,
652
+ }));
653
+ }
654
+ catch (error) {
655
+ return skillErrorResult(error);
656
+ }
657
+ });
658
+ server.registerTool("skill.execute", {
659
+ description: "Execute only a runtime-issued Skill preview token and return verification/rollback evidence.",
660
+ inputSchema: {
661
+ previewToken: z.string().min(1),
662
+ },
663
+ }, async ({ previewToken }) => {
664
+ try {
665
+ return jsonResult(await runtime.executeSkill(previewToken));
666
+ }
667
+ catch (error) {
668
+ return skillErrorResult(error);
669
+ }
670
+ });
209
671
  server.registerTool("project.inspect", {
210
- description: "Read the current canonical project snapshot.",
672
+ description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
211
673
  }, async () => jsonResult(await runtime.inspectProject()));
674
+ server.registerTool("artifact.inspect", {
675
+ description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
676
+ inputSchema: {},
677
+ }, async () => jsonResult(await runtime.inspectArtifact()));
212
678
  server.registerTool("project.list", {
213
679
  description: "List projects and their stable Final Cut sequence identities, including the active target.",
214
680
  inputSchema: {},
@@ -221,26 +687,44 @@ export function createMcpServer(runtime, options = {}) {
221
687
  },
222
688
  }, async ({ projectId, sequenceId }) => jsonResult(await runtime.selectProject({ projectId, sequenceId })));
223
689
  server.registerTool("editor.inspect", {
224
- description: "Read editor identity and machine-readable Phase 2 capabilities.",
690
+ description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
225
691
  }, async () => {
226
- const inspected = await runtime.inspectEditor();
692
+ const inspected = await inspectMcpEditor(runtime, options);
693
+ const capabilities = inspected.capabilities;
227
694
  return jsonResult({
228
695
  ...inspected,
229
696
  capabilities: {
230
- ...inspected.capabilities,
697
+ ...capabilities,
231
698
  editor: {
232
- ...inspected.capabilities.editor,
233
- timelinePublishNewProject: Boolean(options.projectPublisher),
234
- videoExport: Boolean(options.videoExporter?.isAvailable()),
699
+ ...capabilities.editor,
700
+ artifactPublish: Boolean(capabilities.editor.artifactPublish ?? capabilities.editor.timelinePublishNewProject),
235
701
  },
236
702
  },
237
- ...(options.nativeEditor ? { native: options.nativeEditor.capabilities() } : {}),
238
703
  });
239
704
  });
240
705
  server.registerTool("editing.intent.resolve", {
241
706
  description: "Map a supported natural-language editing request to one explicit operation without executing it.",
242
707
  inputSchema: { request: z.string().trim().min(1) },
243
708
  }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
709
+ server.registerTool("editing.route", {
710
+ description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
711
+ inputSchema: {
712
+ operation: z.enum([
713
+ "timeline.edit",
714
+ "editor.native.edit",
715
+ "timeline.publish.new-project",
716
+ "timeline.export",
717
+ ]),
718
+ fallback: z.enum(["none", "external-renderer"]).optional().default("none"),
719
+ },
720
+ }, async ({ operation, fallback }) => {
721
+ const context = await editingRouteContext(runtime, options);
722
+ return jsonResult(resolveEditingRoute({ operation, fallback }, context));
723
+ });
724
+ server.registerTool("editing.duration.plan", {
725
+ description: "Plan requested duration against unique footage and return explicit quality-preserving alternatives without editing.",
726
+ inputSchema: durationPolicyInputSchema,
727
+ }, async (request) => jsonResult(runtime.planDuration(request)));
244
728
  server.registerTool("editor.native.inspect", {
245
729
  description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
246
730
  inputSchema: {},
@@ -311,6 +795,41 @@ export function createMcpServer(runtime, options = {}) {
311
795
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
312
796
  return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
313
797
  });
798
+ server.registerTool("editor.native.transition.search", {
799
+ description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
800
+ inputSchema: { query: z.string().trim().min(1) },
801
+ }, async ({ query }) => {
802
+ if (!options.nativeEditor)
803
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
804
+ const matches = await options.nativeEditor.searchTransitions(query);
805
+ for (const match of matches) {
806
+ nativeTransitionAssets.set(match.id, match);
807
+ nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
808
+ }
809
+ return jsonResult(matches);
810
+ });
811
+ server.registerTool("editor.native.transition.add.preview", {
812
+ description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
813
+ inputSchema: nativeTransitionPreviewSchema,
814
+ }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
815
+ if (!options.nativeEditor)
816
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
817
+ const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
818
+ return jsonResult(await options.nativeEditor.previewTransitionAdd({
819
+ asset,
820
+ beforeOccurrenceHandle,
821
+ afterOccurrenceHandle,
822
+ duration,
823
+ }));
824
+ });
825
+ server.registerTool("editor.native.transition.add.execute", {
826
+ description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
827
+ inputSchema: { previewToken: z.string().min(1) },
828
+ }, async ({ previewToken }) => {
829
+ if (!options.nativeEditor)
830
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
831
+ return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
832
+ });
314
833
  server.registerTool("editor.native.undo", {
315
834
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
316
835
  inputSchema: { operationId: z.string().min(1) },
@@ -447,29 +966,112 @@ export function createMcpServer(runtime, options = {}) {
447
966
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
448
967
  return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
449
968
  });
969
+ server.registerTool("artifact.publish", {
970
+ description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
971
+ inputSchema: artifactPublishInputSchema,
972
+ }, async ({ artifactPath, transactionId, confirm }) => {
973
+ if (!options.projectPublisher)
974
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
975
+ const transaction = runtime.getTransaction(transactionId);
976
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
977
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
978
+ }
979
+ if (!transaction.artifactDigest) {
980
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
981
+ }
982
+ const verification = await runtime.verifyTransaction(transactionId);
983
+ if (!verification.passed)
984
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
985
+ return jsonResult(await options.projectPublisher.publishNewProject({
986
+ sourceTransactionId: transactionId,
987
+ artifactPath,
988
+ artifactDigest: transaction.artifactDigest,
989
+ confirm,
990
+ }));
991
+ });
450
992
  server.registerTool("timeline.publish.new-project", {
451
- description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project.",
993
+ description: "Legacy alias for publishing a verified artifact transaction as a new Final Cut project.",
452
994
  inputSchema: { transactionId: z.string().min(1) },
453
995
  }, async ({ transactionId }) => {
454
- if (!options.projectPublisher)
996
+ if (!options.projectPublisher?.isAvailable())
455
997
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
998
+ const transaction = runtime.getTransaction(transactionId);
999
+ if (transaction.target?.kind !== "artifact") {
1000
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for a managed artifact`);
1001
+ }
1002
+ if (!transaction.artifactDigest) {
1003
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1004
+ }
456
1005
  const verification = await runtime.verifyTransaction(transactionId);
457
1006
  if (!verification.passed)
458
1007
  throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
459
- return jsonResult(await options.projectPublisher.publishNewProject(transactionId));
1008
+ return jsonResult(await options.projectPublisher.publishNewProject({
1009
+ sourceTransactionId: transactionId,
1010
+ artifactPath: transaction.target.artifactPath,
1011
+ artifactDigest: transaction.artifactDigest,
1012
+ confirm: true,
1013
+ }));
460
1014
  });
461
1015
  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.",
1016
+ 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
1017
  inputSchema: {
464
1018
  outputPath: z.string().trim().min(1),
465
1019
  preset: z.enum(["master", "web"]),
466
1020
  overwrite: z.boolean().optional(),
467
1021
  expected: exportExpectationSchema,
1022
+ transactionId: exportTransactionSchema,
468
1023
  },
469
- }, async ({ outputPath, preset, overwrite, expected }) => {
1024
+ }, async ({ outputPath, preset, overwrite, expected, transactionId }) => {
470
1025
  if (!options.videoExporter?.isAvailable())
471
1026
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut video export is not configured");
472
- return jsonResult(await options.videoExporter.exportVideo({ outputPath, preset, overwrite, expected }));
1027
+ const transaction = transactionId ? runtime.getTransaction(transactionId) : undefined;
1028
+ if (transactionId) {
1029
+ if (!transaction)
1030
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} was not found`);
1031
+ if (transaction.status !== "VERIFIED") {
1032
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} is not verified`);
1033
+ }
1034
+ const verification = await runtime.verifyTransaction(transactionId);
1035
+ if (!verification.passed) {
1036
+ throw new Error(`FINAL_CUT_EXPORT_TRANSACTION_INVALID: transaction ${transactionId} did not pass verification`);
1037
+ }
1038
+ const current = await runtime.inspectProject();
1039
+ if (current.projectId !== transaction.after.projectId
1040
+ || current.timeline.id !== transaction.after.timeline.id
1041
+ || current.revision.id !== transaction.after.revision.id
1042
+ || current.revision.sequence !== transaction.after.revision.sequence) {
1043
+ throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not for the active project and sequence`);
1044
+ }
1045
+ }
1046
+ const result = await options.videoExporter.exportVideo({ outputPath, preset, overwrite, expected });
1047
+ if (!transaction || !transactionId)
1048
+ return jsonResult(result);
1049
+ const currentAfterExport = await runtime.inspectProject();
1050
+ if (currentAfterExport.projectId !== transaction.after.projectId
1051
+ || currentAfterExport.timeline.id !== transaction.after.timeline.id
1052
+ || currentAfterExport.revision.id !== transaction.after.revision.id
1053
+ || currentAfterExport.revision.sequence !== transaction.after.revision.sequence) {
1054
+ throw new Error(`STALE_CONTEXT: transaction ${transactionId} changed while the export was running`);
1055
+ }
1056
+ return jsonResult({
1057
+ ...result,
1058
+ manifest: {
1059
+ schemaVersion: 1,
1060
+ transactionId,
1061
+ sourceRevision: transaction.after.revision,
1062
+ project: { id: transaction.after.projectId, name: transaction.after.projectName },
1063
+ sequence: { id: transaction.after.timeline.id, name: transaction.after.timeline.name },
1064
+ timelineDurationSeconds: transaction.after.timeline.duration,
1065
+ media: transaction.after.media.map((media) => ({
1066
+ mediaId: media.mediaId,
1067
+ ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
1068
+ })),
1069
+ output: {
1070
+ format: result.metadata.format,
1071
+ digest: result.metadata.outputDigest,
1072
+ },
1073
+ },
1074
+ });
473
1075
  });
474
1076
  server.registerTool("context.inspect", {
475
1077
  description: "Read the queryable agent editing context and its current revision.",
@@ -519,6 +1121,10 @@ export function createMcpServer(runtime, options = {}) {
519
1121
  description: "Search normalized media references by id or source path.",
520
1122
  inputSchema: { query: z.string() },
521
1123
  }, async ({ query }) => jsonResult(await runtime.searchMedia(query)));
1124
+ server.registerTool("media.index", {
1125
+ description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
1126
+ inputSchema: mediaIndexQuerySchema.shape,
1127
+ }, async (query) => jsonResult(await runtime.indexMedia(query)));
522
1128
  server.registerTool("visual.analyze", {
523
1129
  description: "Analyze scenes, subjects, motion, and keyframes for one media item.",
524
1130
  inputSchema: {
@@ -530,6 +1136,10 @@ export function createMcpServer(runtime, options = {}) {
530
1136
  description: "Return combined speech, audio, and visual understanding for one media item.",
531
1137
  inputSchema: { mediaId: z.string().min(1) },
532
1138
  }, async ({ mediaId }) => jsonResult(await runtime.understandMedia(mediaId)));
1139
+ server.registerTool("rough-cut.plan", {
1140
+ description: "Create a deterministic, explainable, read-only shot plan from analyzed media; does not mutate the timeline.",
1141
+ inputSchema: roughCutPlanSchema.shape,
1142
+ }, async (request) => jsonResult(await runtime.planRoughCut(request)));
533
1143
  server.registerTool("editor.assets", {
534
1144
  description: "Search editor-native transitions, effects, titles, generators, and templates.",
535
1145
  inputSchema: {
@@ -550,9 +1160,34 @@ export function createMcpServer(runtime, options = {}) {
550
1160
  }));
551
1161
  });
552
1162
  server.registerTool("timeline.edit", {
553
- description: "Apply one supported edit and return read-after-write plus its diff.",
1163
+ description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
554
1164
  inputSchema: editToolInputSchema,
555
- }, async (input) => jsonResult(await runtime.edit(editOperationSchema.parse(input))));
1165
+ }, async (input) => {
1166
+ await requireEditingRoute(runtime, options, "timeline.edit");
1167
+ return jsonResult(await runtime.edit(editOperationSchema.parse(input), input.verification ?? {}));
1168
+ });
1169
+ server.registerTool("rough-cut.construction.plan", {
1170
+ description: "Build a deterministic ordered rough-cut construction plan without changing the active project.",
1171
+ inputSchema: roughCutConstructionPlanInputSchema,
1172
+ }, async (request) => jsonResult(await runtime.planRoughCutConstruction(request)));
1173
+ server.registerTool("rough-cut.construction.preview", {
1174
+ description: "Preview a deterministic rough cut with capability and revision checks before execution.",
1175
+ inputSchema: roughCutConstructionPlanInputSchema,
1176
+ }, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
1177
+ server.registerTool("artifact.edit", {
1178
+ description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
1179
+ inputSchema: artifactEditToolInputSchema,
1180
+ }, async (input) => {
1181
+ const { artifactPath, verification, ...operation } = input;
1182
+ return jsonResult(await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {}));
1183
+ });
1184
+ server.registerTool("editor.timeline.edit", {
1185
+ description: "Edit the active Final Cut project and sequence identified by IDs and base revision; return the live timeline target, read-after-write, and diff.",
1186
+ inputSchema: editorTimelineEditToolInputSchema,
1187
+ }, async (input) => {
1188
+ const { projectId, sequenceId, verification, ...operation } = input;
1189
+ return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1190
+ });
556
1191
  server.registerTool("music.add", {
557
1192
  description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
558
1193
  inputSchema: musicAddInputSchema,
@@ -566,20 +1201,54 @@ export function createMcpServer(runtime, options = {}) {
566
1201
  inputSchema: { previewToken: z.string().min(1) },
567
1202
  }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
568
1203
  server.registerTool("timeline.edit.preview", {
569
- description: "Validate and preview one ordered, atomic Basic Editing MVP workflow without mutating the project.",
1204
+ description: "Validate and preview one ordered, atomic Basic Editing MVP workflow after editing.route confirms capabilities; do not mutate the project.",
570
1205
  inputSchema: {
571
1206
  baseRevision: revisionValueSchema,
572
1207
  operations: workflowOperationsSchema,
1208
+ verification: verificationPolicySchema.optional(),
573
1209
  },
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.",
1210
+ }, async (request) => {
1211
+ await requireEditingRoute(runtime, options, "timeline.edit");
1212
+ return jsonResult(await runtime.previewEdit(request));
1213
+ });
1214
+ server.registerTool("artifact.edit.preview", {
1215
+ description: "Validate and preview an ordered artifact edit against the identified FCPXML artifact without mutating it.",
1216
+ inputSchema: {
1217
+ artifactPath: z.string().trim().min(1),
1218
+ baseRevision: revisionValueSchema,
1219
+ operations: workflowOperationsSchema,
1220
+ verification: verificationPolicySchema.optional(),
1221
+ },
1222
+ }, async ({ artifactPath, baseRevision, operations, verification }) => jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1223
+ server.registerTool("editor.timeline.edit.preview", {
1224
+ description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
1225
+ inputSchema: {
1226
+ projectId: z.string().trim().min(1),
1227
+ sequenceId: z.string().trim().min(1),
1228
+ baseRevision: revisionValueSchema,
1229
+ operations: workflowOperationsSchema,
1230
+ verification: verificationPolicySchema.optional(),
1231
+ },
1232
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1233
+ server.registerTool("artifact.edit.execute", {
1234
+ description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
1235
+ inputSchema: { previewToken: z.string().min(1) },
1236
+ }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1237
+ server.registerTool("editor.timeline.edit.execute", {
1238
+ description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
577
1239
  inputSchema: { previewToken: z.string().min(1) },
578
1240
  }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1241
+ server.registerTool("timeline.edit.execute", {
1242
+ description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1243
+ inputSchema: { previewToken: z.string().min(1) },
1244
+ }, async ({ previewToken }) => {
1245
+ await requireEditingRoute(runtime, options, "timeline.edit");
1246
+ return jsonResult(await runtime.executeEdit(previewToken));
1247
+ });
579
1248
  server.registerTool("speech.analyze", {
580
- description: "Analyze speech words and filler markers for one media item.",
581
- inputSchema: { mediaId: z.string().min(1) },
582
- }, async ({ mediaId }) => jsonResult(await runtime.analyzeSpeech(mediaId)));
1249
+ description: "Analyze speech words, filler markers, and optional VAD for one media item or source range.",
1250
+ inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
1251
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeSpeech(mediaId, range)));
583
1252
  server.registerTool("speech.filler.remove.preview", {
584
1253
  description: "Analyze a selected canonical timeline range and preview removal of high-confidence filler words with safe rational delete ranges.",
585
1254
  inputSchema: fillerRemovalInputSchema,
@@ -592,6 +1261,40 @@ export function createMcpServer(runtime, options = {}) {
592
1261
  description: "Analyze loudness, true peak, and silence for one media item.",
593
1262
  inputSchema: { mediaId: z.string().min(1) },
594
1263
  }, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
1264
+ server.registerTool("audio.noise.analyze", {
1265
+ description: "Analyze unwanted background noise for one media item when a noise analyzer is configured.",
1266
+ inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
1267
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeNoise(mediaId, range)));
1268
+ server.registerTool("audio.noise.reduce.preview", {
1269
+ description: "Preview a bounded noise-reduction adjustment and its affected ranges without mutating the editor.",
1270
+ inputSchema: noiseReductionInputSchema,
1271
+ }, async (request) => {
1272
+ const { baseRevision, ...input } = request;
1273
+ return skillPreviewResult(await runtime.previewSkill({
1274
+ skillId: "audio-noise-reduction",
1275
+ baseRevision,
1276
+ input,
1277
+ }));
1278
+ });
1279
+ server.registerTool("audio.noise.reduce.execute", {
1280
+ description: "Execute one previewed noise-reduction adjustment and return post-write measurement verification and rollback state.",
1281
+ inputSchema: { previewToken: z.string().min(1) },
1282
+ }, async ({ previewToken }) => jsonResult(await runtime.executeSkill(previewToken)));
1283
+ server.registerTool("color.correction.preview", {
1284
+ description: "Preview a clip-scoped basic color correction with before/after values without mutating the editor.",
1285
+ inputSchema: colorCorrectionInputSchema,
1286
+ }, async (request) => {
1287
+ const { baseRevision, ...input } = request;
1288
+ return skillPreviewResult(await runtime.previewSkill({
1289
+ skillId: "color-correction",
1290
+ baseRevision,
1291
+ input,
1292
+ }));
1293
+ });
1294
+ server.registerTool("color.correction.execute", {
1295
+ description: "Execute one previewed basic color correction and return the target verification, diff, and rollback state.",
1296
+ inputSchema: { previewToken: z.string().min(1) },
1297
+ }, async ({ previewToken }) => jsonResult(await runtime.executeSkill(previewToken)));
595
1298
  server.registerTool("edit.diff", {
596
1299
  description: "Read the deterministic diff for a completed edit transaction.",
597
1300
  inputSchema: { transactionId: z.string().min(1) },
@@ -604,6 +1307,7 @@ export function createMcpServer(runtime, options = {}) {
604
1307
  description: "Restore the pre-edit snapshot for a completed transaction.",
605
1308
  inputSchema: { transactionId: z.string().min(1) },
606
1309
  }, async ({ transactionId }) => jsonResult(await runtime.undo(transactionId)));
1310
+ installMcpSchemaCompatibility(server);
607
1311
  return server;
608
1312
  }
609
1313
  async function resolveNativeTitleAsset(runtime, assetId) {
@@ -615,3 +1319,114 @@ async function resolveNativeTitleAsset(runtime, assetId) {
615
1319
  throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
616
1320
  return asset;
617
1321
  }
1322
+ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
1323
+ const cachedAsset = nativeTransitionAssets.get(assetId);
1324
+ if (cachedAsset)
1325
+ return cachedAsset;
1326
+ let assets = [];
1327
+ try {
1328
+ assets = await runtime.listAssets({ kind: "transition" });
1329
+ }
1330
+ catch {
1331
+ // A native-only session may not expose the runtime asset registry. Native
1332
+ // discovery below remains the source of truth in that case.
1333
+ }
1334
+ const asset = assets.find((candidate) => candidate.id === assetId);
1335
+ // The runtime registry identifies installed assets by filesystem metadata;
1336
+ // transition placement must use the stable identity returned by Final Cut's
1337
+ // Transitions browser. Resolve registry assets back through native discovery
1338
+ // instead of fabricating a native identity from the registry id.
1339
+ const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
1340
+ const matchingNativeMatches = asset
1341
+ ? nativeMatches.filter((candidate) => candidate.name === asset.name)
1342
+ : nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
1343
+ if (asset && matchingNativeMatches.length > 1) {
1344
+ throw new Error(`TRANSITION_ASSET_AMBIGUOUS: native transition name ${asset.name} has multiple stable identities`);
1345
+ }
1346
+ const nativeMatch = matchingNativeMatches[0];
1347
+ if (!nativeMatch)
1348
+ throw new Error(`TRANSITION_ASSET_NOT_FOUND: installed transition asset ${assetId} was not discovered`);
1349
+ return nativeMatch;
1350
+ }
1351
+ async function connectionStatus(options) {
1352
+ return await options.connectionStatus?.() ?? {
1353
+ state: "ready",
1354
+ editorDetected: false,
1355
+ extensionInstalled: false,
1356
+ socketPath: null,
1357
+ capabilities: null,
1358
+ };
1359
+ }
1360
+ async function inspectMcpEditor(runtime, options) {
1361
+ const inspected = await runtime.inspectEditor();
1362
+ const native = options.nativeEditor?.capabilities();
1363
+ const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
1364
+ const exportAvailable = Boolean(options.videoExporter?.isAvailable());
1365
+ const capabilities = withCapabilityFamilies({
1366
+ ...inspected.capabilities,
1367
+ editor: {
1368
+ ...inspected.capabilities.editor,
1369
+ artifactPublish: publishingAvailable,
1370
+ ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
1371
+ videoExport: exportAvailable,
1372
+ },
1373
+ }, {
1374
+ backend: inspected.identity.backend,
1375
+ nativeBackend: "final-cut-accessibility",
1376
+ native: {
1377
+ selectionWrite: Boolean(native?.selectionEdit),
1378
+ undo: Boolean(native?.undo),
1379
+ mediaLibrarySearch: Boolean(native?.mediaLibrarySearch),
1380
+ mediaImport: Boolean(native?.mediaImport),
1381
+ mediaSelection: Boolean(native?.mediaSelection),
1382
+ mediaAppendSelected: Boolean(native?.mediaAppendSelected),
1383
+ timelineOccurrenceLocate: Boolean(native?.timelineOccurrenceLocate),
1384
+ bladeAtPlayhead: Boolean(native?.bladeAtPlayhead),
1385
+ deleteRange: Boolean(native?.deleteRange),
1386
+ trimToDuration: Boolean(native?.trimToDuration),
1387
+ mediaAppend: Boolean(native?.mediaAppend),
1388
+ mediaInsert: Boolean(native?.mediaInsert),
1389
+ titlePlacement: Boolean(native?.titlePlacement),
1390
+ transitionDiscovery: Boolean(native?.transitionDiscovery),
1391
+ transitionPlacement: Boolean(native?.transitionPlacement),
1392
+ timelineFocus: Boolean(native?.timelineFocus),
1393
+ projectCreation: false,
1394
+ clipInsertion: false,
1395
+ clipMovement: false,
1396
+ },
1397
+ publishing: publishingAvailable,
1398
+ publishingBackend: "fcpxml-publisher",
1399
+ export: exportAvailable,
1400
+ exportBackend: "final-cut-native-export",
1401
+ });
1402
+ return {
1403
+ ...inspected,
1404
+ capabilities,
1405
+ preflight: createCapabilityPreflight(inspected.identity, capabilities, {
1406
+ processMode: options.processMode ?? (native ? "headed" : "headless"),
1407
+ nativeWrite: Boolean(native?.selectionEdit),
1408
+ }),
1409
+ ...(native ? { native } : {}),
1410
+ };
1411
+ }
1412
+ async function requireEditingRoute(runtime, options, operation) {
1413
+ const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
1414
+ if (route.status !== "editor-selected") {
1415
+ throw new Error(`${route.reason.code}: ${route.reason.message}`);
1416
+ }
1417
+ }
1418
+ async function editingRouteContext(runtime, options) {
1419
+ const connection = await connectionStatus(options);
1420
+ let editor;
1421
+ try {
1422
+ editor = await inspectMcpEditor(runtime, options);
1423
+ }
1424
+ catch {
1425
+ editor = undefined;
1426
+ }
1427
+ return {
1428
+ connection,
1429
+ ...(editor ? { editor } : {}),
1430
+ ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
1431
+ };
1432
+ }