@lalalic/markcut 3.2.6 → 3.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.2.6",
+  "version": "3.2.8",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -22,6 +22,7 @@
     "render:demo": "node src/render/cli.mjs render src/demo-components.json",
     "templates": "node src/render/cli.mjs templates",
     "preview": "node src/render/cli.mjs preview",
+    "mcp": "node src/mcp/server.mjs",
     "verify": "node src/render/cli.mjs verify",
     "resolve": "node src/render/cli.mjs resolve",
     "render:pixelle": "remotion render examples/pixelle/index.tsx Root out/pixelle-asset-default.mp4 --props=./examples/pixelle/asset-default.json",
@@ -37,6 +38,7 @@
   },
   "dependencies": {
     "@babel/standalone": "^8.0.3",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@remotion/cli": "4.0.469",
     "@remotion/media-parser": "4.0.469",
     "@remotion/media-utils": "4.0.469",

package/skills/markcut/SKILL.md

@@ -78,10 +78,20 @@ npx @lalalic/markcut spots --waypoints "lat,lng;lat,lng" # discover POIs along a
 
 ---
 
+## MCP Markdown Review
+
+Use the model-visible MCP tool `markcut.preview({ path })` when a human needs to review a Markdown artifact. This is a generic Markdown review surface and is separate from the video-specific `npx @lalalic/markcut preview <file>` CLI.
+
+- `path` must be an absolute path to a Markdown file.
+- The user sees the rendered Markdown and can either **Approve** or submit feedback with **Request changes**.
+- Markcut does not edit the file. The calling agent owns all source changes.
+- On `approved`, continue the workflow.
+- On `changes_requested`, apply the feedback to the source Markdown, then call `markcut.preview({ path })` again for another review round.
+
 ## review
 use the review contract defined in [./review.md](./review.md) to guide the review process.
 review as early as possible in the video production process to catch issues before they propagate.
-* review md file
+* review md file with `markcut.preview({ path })` when the MCP tool is available
 * review compiled.json
 * review the rendered video
 

package/src/mcp/bridge.mjs

@@ -0,0 +1,15 @@
+export function buildPreviewBridgeScript(submitToolName) {
+  return `
+const feedback=document.getElementById('feedback'),status=document.getElementById('status'),article=document.querySelector('article'),pathLabel=document.querySelector('main>p code');
+let nextRequestId=0;
+const pendingRequests=new Map();
+function send(message){window.parent.postMessage(message,'*');}
+function rpcRequest(method,params){const id=++nextRequestId;send({jsonrpc:'2.0',id,method,params});return new Promise((resolve,reject)=>pendingRequests.set(id,{resolve,reject}));}
+function applyToolResult(params){const result=params?.result||params||{},data=result.structuredContent||result.structured_content||{};if(typeof data.path==='string')pathLabel.textContent=data.path;if(typeof data.markdown==='string'){article.innerHTML=data.markdown.split(/\\r?\\n/).map(line=>{const escaped=line.replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));if(line.startsWith('### '))return '<h3>'+escaped.slice(4)+'</h3>';if(line.startsWith('## '))return '<h2>'+escaped.slice(3)+'</h2>';if(line.startsWith('# '))return '<h1>'+escaped.slice(2)+'</h1>';if(line.startsWith('- '))return '<li>'+escaped.slice(2)+'</li>';return line.trim()?'<p>'+escaped+'</p>':''}).join('\\n');}}
+window.addEventListener('message',event=>{if(event.source!==window.parent)return;const message=event.data;if(!message||typeof message!=='object'||message.jsonrpc!=='2.0')return;if(Object.prototype.hasOwnProperty.call(message,'id')&&pendingRequests.has(message.id)){const pending=pendingRequests.get(message.id);pendingRequests.delete(message.id);if(message.error)pending.reject(new Error(message.error.message||'MCP request failed'));else pending.resolve(message.result);return;}if(message.method==='ui/notifications/tool-result')applyToolResult(message.params);});
+async function initializeBridge(){try{await rpcRequest('ui/initialize',{protocolVersion:'2026-01-26',capabilities:{},clientInfo:{name:'markcut-preview',version:'1'}});send({jsonrpc:'2.0',method:'ui/notifications/initialized'});status.textContent='Ready for review.';}catch(error){status.textContent=error.message||'MCP initialization failed.';}}
+async function submit(decision){const value=feedback.value.trim();if(decision==='changes_requested'&&!value){status.textContent='Feedback is required.';feedback.focus();return;}const result={decision};if(value&&decision==='changes_requested')result.feedback=value;status.textContent='Submitting...';try{await rpcRequest('tools/call',{name:'${submitToolName}',arguments:result});send({jsonrpc:'2.0',method:'ui/message',params:{role:'user',content:[{type:'text',text:JSON.stringify(result)}]}});status.textContent=decision==='approved'?'Approved.':'Changes requested.';}catch(error){status.textContent=error.message||'Unable to submit review.';}}
+initializeBridge();
+document.getElementById('approve').onclick=()=>submit('approved');document.getElementById('changes').onclick=()=>submit('changes_requested');
+`;
+}

package/src/mcp/preview.mjs

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, extname } from "node:path";
+import { buildPreviewBridgeScript } from "./bridge.mjs";
+
+export const TOOL_NAME = "markcut.preview";
+export const SUBMIT_TOOL_NAME = "markcut.preview.submit";
+export const RESOURCE_URI = "ui://markcut/markdown-preview.html";
+
+export function validateMarkdownPath(value) {
+  if (typeof value !== "string" || !isAbsolute(value)) {
+    throw new Error("path must be an absolute filesystem path");
+  }
+  if (extname(value).toLowerCase() !== ".md") {
+    throw new Error("path must point to a Markdown file (.md)");
+  }
+  return value;
+}
+
+export async function readMarkdownPreview(path) {
+  const validatedPath = validateMarkdownPath(path);
+  try {
+    return { path: validatedPath, markdown: await readFile(validatedPath, "utf8") };
+  } catch (error) {
+    throw new Error(`unable to read Markdown file: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function reviewResult(decision, feedback = "") {
+  if (decision === "approved") return { decision };
+  if (decision === "changes_requested") {
+    const normalized = typeof feedback === "string" ? feedback.trim() : "";
+    if (!normalized) throw new Error("feedback is required when requesting changes");
+    return { decision, feedback: normalized };
+  }
+  throw new Error(`unsupported review decision: ${String(decision)}`);
+}
+
+export function reviewMessage(result) {
+  const normalized = reviewResult(result?.decision, result?.feedback);
+  return {
+    jsonrpc: "2.0",
+    method: "ui/message",
+    params: {
+      role: "user",
+      content: [{ type: "text", text: JSON.stringify(normalized) }],
+    },
+  };
+}
+
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
+  })[character]);
+}
+
+function renderMarkdown(markdown) {
+  return markdown.split(/\r?\n/).map((line) => {
+    const escaped = escapeHtml(line);
+    if (line.startsWith("### ")) return `<h3>${escaped.slice(4)}</h3>`;
+    if (line.startsWith("## ")) return `<h2>${escaped.slice(3)}</h2>`;
+    if (line.startsWith("# ")) return `<h1>${escaped.slice(2)}</h1>`;
+    if (line.startsWith("- ")) return `<li>${escaped.slice(2)}</li>`;
+    return line.trim() ? `<p>${escaped}</p>` : "";
+  }).join("\n");
+}
+
+export function buildPreviewHtml({ path = "", markdown = "" }) {
+  const safePath = escapeHtml(path);
+  const rendered = renderMarkdown(markdown);
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>MarkCut Markdown review</title>
+<style>body{font:15px system-ui,sans-serif;margin:0;padding:24px;color:#17202a;background:#fff}main{max-width:860px;margin:auto}article{border:1px solid #d8dee4;border-radius:8px;padding:20px;overflow:auto}h1,h2,h3{margin-top:0}p{line-height:1.5}textarea{box-sizing:border-box;width:100%;min-height:100px;margin:16px 0 10px;padding:10px;border:1px solid #8c959f;border-radius:6px;font:inherit}button{border:0;border-radius:6px;padding:9px 14px;margin-right:8px;font:inherit;cursor:pointer}#approve{background:#1f883d;color:#fff}#changes{background:#cf222e;color:#fff}#status{min-height:1.4em;color:#cf222e}</style></head>
+<body><main><h1>Review Markdown</h1><p><code>${safePath}</code></p><article>${rendered}</article>
+<label for="feedback">Feedback (required for requested changes)</label><textarea id="feedback" placeholder="What should be changed?"></textarea><div id="status" role="status"></div>
+<button id="approve">Approve</button><button id="changes">Request changes</button></main>
+<script>${buildPreviewBridgeScript(SUBMIT_TOOL_NAME)}</script></body></html>`;
+}

package/src/mcp/server.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  TOOL_NAME, SUBMIT_TOOL_NAME, RESOURCE_URI, buildPreviewHtml, readMarkdownPreview, reviewResult,
+} from "./preview.mjs";
+
+const server = new Server(
+  { name: "markcut", version: "3.2.0" },
+  { capabilities: { tools: {}, resources: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: TOOL_NAME,
+    description: "Ask a human to review a Markdown file and return an approval or requested changes.",
+    inputSchema: {
+      type: "object", properties: { path: { type: "string", description: "Absolute path to a .md file" } },
+      required: ["path"], additionalProperties: false,
+    },
+    _meta: { "ui/resourceUri": RESOURCE_URI, ui: { resourceUri: RESOURCE_URI } },
+  }, {
+    name: SUBMIT_TOOL_NAME,
+    description: "Submit the review decision from the Markdown preview UI.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        decision: { type: "string", enum: ["approved", "changes_requested"] },
+        feedback: { type: "string" },
+      },
+      required: ["decision"], additionalProperties: false,
+    },
+    _meta: { ui: { visibility: ["app"] } },
+  }],
+}));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [{ uri: RESOURCE_URI, name: "MarkCut Markdown review", mimeType: "text/html;profile=mcp-app" }],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => ({
+  contents: [{ uri: RESOURCE_URI, mimeType: "text/html;profile=mcp-app", text: buildPreviewHtml({ path: "", markdown: "" }) }],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    const input = request.params.arguments ?? {};
+    if (request.params.name === SUBMIT_TOOL_NAME) {
+      const decision = reviewResult(input.decision, input.feedback);
+      return { content: [{ type: "text", text: JSON.stringify(decision) }], structuredContent: decision };
+    }
+    if (request.params.name !== TOOL_NAME) throw new Error(`unknown tool: ${request.params.name}`);
+    const { path, markdown } = await readMarkdownPreview(input.path);
+    return {
+      content: [{ type: "text", text: `Markdown ready for review: ${path}` }],
+      structuredContent: { path, markdown, resourceUri: RESOURCE_URI },
+      _meta: {
+        "ui/resourceUri": RESOURCE_URI,
+        ui: { resourceUri: RESOURCE_URI, props: { path, markdown } },
+      },
+    };
+  } catch (error) {
+    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+  }
+});
+
+await server.connect(new StdioServerTransport());

package/tests/mcp-preview.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import vm from "node:vm";
+import { buildPreviewHtml, readMarkdownPreview, reviewMessage, reviewResult, validateMarkdownPath } from "../src/mcp/preview.mjs";
+import { buildPreviewBridgeScript } from "../src/mcp/bridge.mjs";
+
+describe("MarkCut MCP Markdown preview", () => {
+  it("requires an absolute .md path", () => {
+    expect(() => validateMarkdownPath("notes.md")).toThrow(/absolute/);
+    expect(() => validateMarkdownPath("/tmp/notes.txt")).toThrow(/Markdown/);
+  });
+
+  it("reads Markdown and builds a reviewable UI resource", async () => {
+    const directory = mkdtempSync(join(tmpdir(), "markcut-mcp-"));
+    const path = join(directory, "review.md");
+    writeFileSync(path, "# Hello\n\nThis is a review.");
+    const preview = await readMarkdownPreview(path);
+    const html = buildPreviewHtml(preview);
+    expect(preview.markdown).toContain("# Hello");
+    expect(html).toContain("This is a review.");
+    expect(html).toContain("Approve");
+    expect(html).toContain("Request changes");
+    expect(html).toContain("ui/initialize");
+    expect(html).toContain("ui/notifications/tool-result");
+    expect(html).toContain("tools/call");
+    expect(html).toContain("ui/message");
+    expect(html).toContain("review.md");
+  });
+
+  it("returns approved", () => {
+    expect(reviewResult("approved")).toEqual({ decision: "approved" });
+  });
+
+  it("requires non-empty feedback for requested changes", () => {
+    expect(() => reviewResult("changes_requested", "  ")).toThrow(/feedback is required/);
+    expect(reviewResult("changes_requested", " Fix the title ")).toEqual({
+      decision: "changes_requested", feedback: "Fix the title",
+    });
+  });
+
+  it("formats decisions as an MCP Apps ui/message notification", () => {
+    expect(reviewMessage({ decision: "approved" })).toEqual({
+      jsonrpc: "2.0",
+      method: "ui/message",
+      params: { role: "user", content: [{ type: "text", text: '{"decision":"approved"}' }] },
+    });
+    expect(reviewMessage({ decision: "changes_requested", feedback: "Fix the title" }).params.content[0].text)
+      .toBe('{"decision":"changes_requested","feedback":"Fix the title"}');
+  });
+
+  it("performs the MCP Apps handshake and awaits a successful submit", async () => {
+    const harness = createBridgeHarness();
+    harness.run();
+    expect(harness.messages[0]).toMatchObject({ id: 1, method: "ui/initialize" });
+    harness.respond({ id: 1, result: { protocolVersion: "2026-01-26" } });
+    await tick();
+    expect(harness.messages[1]).toMatchObject({ method: "ui/notifications/initialized" });
+
+    harness.elements.approve.onclick();
+    expect(harness.messages[2]).toMatchObject({ id: 2, method: "tools/call" });
+    expect(harness.messages).not.toContainEqual(expect.objectContaining({ method: "ui/message" }));
+    harness.respond({ id: 2, result: { structuredContent: { decision: "approved" } } });
+    await tick();
+    expect(harness.messages[3]).toMatchObject({ method: "ui/message" });
+    expect(new Set(harness.messages.filter((message) => "id" in message).map((message) => message.id)).size).toBe(2);
+  });
+
+  it("surfaces submit errors without sending a decision message and rejects invalid bridge messages", async () => {
+    const harness = createBridgeHarness();
+    harness.run();
+    harness.dispatch({ source: {}, data: { jsonrpc: "2.0", id: 1, result: {} } });
+    expect(harness.elements.status.textContent).toBe("");
+    harness.respond({ id: 1, result: {} });
+    await tick();
+    harness.elements.changes.onclick();
+    expect(harness.elements.status.textContent).toBe("Feedback is required.");
+    harness.elements.feedback.value = "Fix the title";
+    harness.elements.changes.onclick();
+    harness.respond({ id: 2, error: { message: "submit failed" } });
+    await tick();
+    expect(harness.elements.status.textContent).toBe("submit failed");
+    expect(harness.messages.some((message) => message.method === "ui/message")).toBe(false);
+  });
+});
+
+function tick() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function createBridgeHarness() {
+  const messages: any[] = [];
+  const listeners: ((event: any) => void)[] = [];
+  const element = (value = "") => ({ value, textContent: "", innerHTML: "", onclick: undefined as (() => void) | undefined, focus() {} });
+  const elements = {
+    feedback: element(),
+    status: element(),
+    article: element(),
+    pathLabel: element(),
+    approve: element(),
+    changes: element(),
+  };
+  const parent = { postMessage(message: any) { messages.push(message); } };
+  const document = {
+    getElementById(id: string) { return id === "feedback" ? elements.feedback : id === "status" ? elements.status : id === "approve" ? elements.approve : elements.changes; },
+    querySelector(selector: string) { return selector === "article" ? elements.article : elements.pathLabel; },
+  };
+  const window = { parent, addEventListener(_type: string, listener: (event: any) => void) { listeners.push(listener); } };
+  const context = vm.createContext({ window, document });
+  return {
+    messages,
+    elements,
+    run() { vm.runInContext(buildPreviewBridgeScript("markcut.preview.submit"), context); },
+    dispatch(event: any) { listeners.forEach((listener) => listener(event)); },
+    respond(message: any) { this.dispatch({ source: parent, data: { jsonrpc: "2.0", ...message } }); },
+  };
+}