@engine-room/after-effects-mcp 0.1.1 → 0.1.2

package/README.md

@@ -94,6 +94,7 @@ It reinstalls the panel and tells you to restart After Effects. Ask it to check
 | Raw (1) | `run_jsx` |
 | Jobs (3) | `await_job`, `get_job`, `cancel_job` |
 | Setup (2) | `check_setup`, `setup_panel` |
+| Issues (3) | `list_known_issues`, `log_issue`, `mark_issue_reported` |
 
 A few notes on the ones that behave differently from the rest:
 
@@ -101,6 +102,30 @@ A few notes on the ones that behave differently from the rest:
 - `run_batch` runs many operations in a single pass and counts as one undo step. Long batches stream progress.
 - `screenshot_frame` and `screenshot_layer` are for occasional checks, not for reviewing motion frame by frame. On large comps, `downsample: 2` renders at half resolution, which is faster and keeps the image small.
 - `run_jsx` runs arbitrary ExtendScript for anything the other tools do not cover.
+- `log_issue` and `list_known_issues` are the notebook described below.
+
+## When something goes wrong
+
+These tools have rough edges. When the AI hits one and works out a way around
+it, it writes the problem and the fix into a notebook in your project folder, at
+`.ae-mcp/issues/` — plain text files you can read or delete. The next session
+reads that notebook before guessing, so the same twenty minutes are never spent
+twice on the same project.
+
+The folder ignores itself, so it stays out of version control without you doing
+anything.
+
+If the problem looks like ours rather than yours, the AI will say so at the end
+of its reply and offer to pass it on. You can also start that yourself:
+
+```
+/report-ae-issue
+```
+
+It writes the report, shows it to you, and only sends it once you say yes.
+Nothing about your own work — comp names, file paths, clients — goes into it.
+Sending needs the [GitHub CLI](https://cli.github.com); without it you get a
+prefilled link to click instead.
 
 ## Troubleshooting
 

package/bin/server.js

@@ -65,6 +65,39 @@ description: The visual and motion style for this project \u2014 palette, type,
 - _Anything that should always or never happen. E.g. "never put text directly on
   footage \u2014 always on a rounded chip", "keep total runtime under 8 seconds"._
 `;
+var REPORT_COMMAND = `---
+description: Send a problem you hit with the After Effects tools to the people who maintain them
+argument-hint: "[what went wrong, in your own words]"
+---
+
+# Report a problem with the After Effects tools
+
+Assume the person you are helping is a motion designer, not a developer, and may
+never have used GitHub. Do the technical part for them.
+
+1. **Find what to report.** Call \`list_known_issues\` with \`status: "unreported"\`.
+   It returns what earlier sessions wrote down, plus \`repo\`, \`newIssueUrl\`,
+   \`serverVersion\` and \`platform\`. List the entries in plain sentences \u2014 not raw
+   titles \u2014 and ask which to send. If there is nothing recorded but \`$ARGUMENTS\`
+   describes a problem, ask what they were doing and what happened, then
+   \`log_issue\` it first. If there is nothing at all, say so and stop.
+
+2. **Draft it short.** Title: one concrete line. Body: **What happens** (the
+   failing call and exact error), **Why** if known, **Workaround**, and
+   **Environment** (\`after-effects-mcp <serverVersion> \xB7 <platform> \xB7 After
+   Effects 2026\`). Leave out their own work \u2014 comp names, file paths, client
+   names, anything about the video.
+
+3. **Show it and ask.** This posts publicly, so get a real yes.
+
+4. **Send it.** \`gh issue create --repo <repo> --title "..." --body "..."\`. If
+   \`gh\` is missing or not logged in, do not install it \u2014 build a prefilled link
+   instead by URL-encoding the title and body onto \`<newIssueUrl>\` as
+   \`?title=\u2026&body=\u2026\`, and tell them to open it and press the green button.
+
+5. **Close the loop.** On success call \`mark_issue_reported\` with the entry id
+   and URL, then give them the link. If they decline, leave the entry unreported.
+`;
 var CLAUDE_MD = `# {{NAME}}
 
 After Effects project folder. The tools drive After Effects directly from here.
@@ -82,6 +115,14 @@ The look of everything built here is defined in
 \`.claude/skills/house-style/SKILL.md\`. Edit that file to change the defaults \u2014
 palette, type, timing, layout. It is read automatically.
 
+## When a tool misbehaves
+
+Check \`list_known_issues\` before guessing \u2014 an earlier session may already have
+solved it. When you work out a fix for something that cost real time and was the
+tool's fault rather than yours, record it with \`log_issue\` so the next session
+does not pay for it again, and offer at the end of your reply to pass it on.
+\`/report-ae-issue\` sends it to the maintainers.
+
 ## Conventions for this project
 
 <!-- Anything specific to this project rather than to your general style:
@@ -123,6 +164,7 @@ Usage: npx @engine-room/after-effects-mcp init <directory> [--no-mcp]
   const files = [
     ["CLAUDE.md", CLAUDE_MD.replace("{{NAME}}", name)],
     [path.join(".claude", "skills", "house-style", "SKILL.md"), HOUSE_STYLE],
+    [path.join(".claude", "commands", "report-ae-issue.md"), REPORT_COMMAND],
     [path.join("renders", ".gitkeep"), ""]
   ];
   if (parsed.withMcp) files.push([".mcp.json", MCP_JSON]);
@@ -147,6 +189,7 @@ Delete them first, or choose a different directory.
     ``,
     `  CLAUDE.md                                what this project is`,
     `  .claude/skills/house-style/SKILL.md      your look \u2014 edit this first`,
+    `  .claude/commands/report-ae-issue.md      /report-ae-issue \u2014 tell the maintainers something broke`,
     `  renders/                                 exports land here`,
     ...parsed.withMcp ? [`  .mcp.json                                connects your client to After Effects`] : [],
     ``,
@@ -262,7 +305,10 @@ __export(schemas_exports, {
   ListAvailableEffects: () => ListAvailableEffects,
   ListComps: () => ListComps,
   ListEffects: () => ListEffects,
+  ListKnownIssues: () => ListKnownIssues,
   ListLayers: () => ListLayers,
+  LogIssue: () => LogIssue,
+  MarkIssueReported: () => MarkIssueReported,
   OpSchemas: () => OpSchemas,
   ParentLayer: () => ParentLayer,
   PropertyPath: () => PropertyPath,
@@ -669,6 +715,21 @@ var SetupPanel = z2.object({
   enableDebugMode: z2.boolean().default(true).optional().describe("Also enable Adobe's PlayerDebugMode preference, which AE requires to load this unsigned panel. Default true."),
   force: z2.boolean().default(false).optional().describe("Replace an existing symlinked (development) install with a copy. Default false.")
 }).strict();
+var LogIssue = z2.object({
+  title: z2.string().min(3).describe("One line naming the problem, specific enough to recognise again. Becomes the entry's id."),
+  symptom: z2.string().min(3).describe("What went wrong, including the exact error text and the call that produced it."),
+  workaround: z2.string().min(3).describe("What actually worked \u2014 concrete enough for the next session to apply without rediscovering it."),
+  cause: z2.string().optional().describe("Why it happens, if you worked it out."),
+  tools: z2.array(z2.string()).optional().describe("Tool names involved, e.g. ['set_temporal_ease'].")
+}).strict();
+var ListKnownIssues = z2.object({
+  status: z2.enum(["all", "unreported", "reported"]).default("all").optional(),
+  tool: z2.string().optional().describe("Only entries about this tool, e.g. 'set_temporal_ease'. Omit for everything.")
+}).strict();
+var MarkIssueReported = z2.object({
+  id: z2.string().describe("The entry id returned by log_issue or list_known_issues."),
+  url: z2.string().optional().describe("Link to the issue that was opened.")
+}).strict();
 var AwaitJob = z2.object({ jobId: z2.string(), timeoutMs: z2.number().int().positive().default(6e5).optional() });
 var GetJob = z2.object({ jobId: z2.string() });
 var CancelJob = z2.object({ jobId: z2.string() });
@@ -748,7 +809,11 @@ var OpSchemas = {
   cancel_job: CancelJob,
   // setup
   check_setup: CheckSetup,
-  setup_panel: SetupPanel
+  setup_panel: SetupPanel,
+  // issue journal
+  log_issue: LogIssue,
+  list_known_issues: ListKnownIssues,
+  mark_issue_reported: MarkIssueReported
 };
 
 // src/util/errors.ts
@@ -1106,7 +1171,11 @@ var descriptions = {
   cancel_job: "Set cancel flag; chunked loop stops at next boundary.",
   // ---------- setup ----------
   check_setup: "Diagnose the After Effects connection: panel installed, up to date, Adobe debug preference on, AE running, bridge answering. Read-only and safe to call any time. Call this FIRST whenever another tool reports it cannot reach After Effects, then relay `nextSteps` to the user in plain language.",
-  setup_panel: "Install or refresh the After Effects panel and enable the Adobe preference AE needs to load it. Run this when check_setup reports the panel is missing or out of date. It writes to the user's Adobe CEP extensions folder and sets a user-level Adobe preference \u2014 tell the user what it will do before calling it. Afterwards, AE must be restarted; if the preference was newly enabled, a one-time Mac reboot may also be needed."
+  setup_panel: "Install or refresh the After Effects panel and enable the Adobe preference AE needs to load it. Run this when check_setup reports the panel is missing or out of date. It writes to the user's Adobe CEP extensions folder and sets a user-level Adobe preference \u2014 tell the user what it will do before calling it. Afterwards, AE must be restarted; if the preference was newly enabled, a one-time Mac reboot may also be needed.",
+  // ---------- issue journal ----------
+  list_known_issues: "Problems earlier sessions hit with these tools, with the workarounds that worked. Read it when a tool fails in a way you don't immediately understand \u2014 pass `tool` to narrow it to that one \u2014 and before nontrivial work. It can save you rediscovering a fix that already cost someone an hour. Also returns the repo and server version needed to report one.",
+  log_issue: "Record a problem you hit and the workaround that got past it, so the next session doesn't rediscover it. Log only what cost real effort and will recur: a tool failing for a non-obvious reason, an argument shape the schema didn't imply, AE behaving unlike the docs. Not your own typos, not one-off user mistakes. Call list_known_issues first and reuse the same title to extend an existing entry rather than duplicating it. If the result comes back with reported:false, then AFTER you have finished the actual work, close your reply by telling the user in plain language that something took much longer than it should have and offering to pass it to the people who maintain this tool \u2014 phrase it for a motion designer, in terms of what actually happened, and don't say 'GitHub issue' or 'bug report' unless they say it first.",
+  mark_issue_reported: "Record that a journal entry has been sent to the maintainers, with the resulting URL. Call it only once the issue really exists, so later sessions don't ask the user to report the same thing twice."
 };
 
 // src/setup/check.ts
@@ -1134,6 +1203,14 @@ function packageRoot() {
   }
   return path3.dirname(fileURLToPath(import.meta.url));
 }
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(fs3.readFileSync(path3.join(packageRoot(), "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 function panelSourceDir() {
   const candidates = [
     // The live workspace copy comes first so a git checkout always installs
@@ -1456,6 +1533,208 @@ async function installPanel(opts = {}) {
   };
 }
 
+// src/issues/journal.ts
+import fs6 from "node:fs";
+import os3 from "node:os";
+import path6 from "node:path";
+var REPO = "Engine-Room-Games/after-effects-mcp";
+var NEW_ISSUE_URL = `https://github.com/${REPO}/issues/new`;
+var SECTION_SYMPTOM = "What went wrong";
+var SECTION_CAUSE = "Why";
+var SECTION_WORKAROUND = "What worked";
+function journalRoot() {
+  const override = process.env.AE_MCP_HOME?.trim();
+  if (override && override.length > 0) return { dir: override, scope: "project" };
+  const cwd = process.cwd();
+  const unusable = cwd === path6.parse(cwd).root || cwd === os3.homedir();
+  if (!unusable) {
+    try {
+      fs6.accessSync(cwd, fs6.constants.W_OK);
+      return { dir: path6.join(cwd, ".ae-mcp"), scope: "project" };
+    } catch {
+    }
+  }
+  return { dir: path6.join(os3.homedir(), ".after-effects-mcp"), scope: "home" };
+}
+function journalDir() {
+  return path6.join(journalRoot().dir, "issues");
+}
+function ensureJournalDir() {
+  const { dir } = journalRoot();
+  const issues = path6.join(dir, "issues");
+  fs6.mkdirSync(issues, { recursive: true });
+  const ignore = path6.join(dir, ".gitignore");
+  if (!fs6.existsSync(ignore)) fs6.writeFileSync(ignore, "*\n", "utf8");
+  return issues;
+}
+function slugify(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : `issue-${Date.now()}`;
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function entryPath(id) {
+  const dir = path6.resolve(journalDir());
+  const file = path6.resolve(dir, `${id}.md`);
+  if (path6.dirname(file) !== dir) throw new Error(`Invalid issue id: ${id}`);
+  return file;
+}
+function render(entry) {
+  const lines = [
+    "---",
+    `id: ${entry.id}`,
+    `title: ${oneLine(entry.title)}`,
+    `tools: ${entry.tools.join(", ")}`,
+    `firstSeen: ${entry.firstSeen}`,
+    `lastSeen: ${entry.lastSeen}`,
+    `occurrences: ${entry.occurrences}`,
+    `reported: ${entry.reported}`,
+    `issueUrl: ${entry.issueUrl ?? ""}`,
+    "---",
+    "",
+    `## ${SECTION_SYMPTOM}`,
+    "",
+    entry.symptom.trim(),
+    ""
+  ];
+  if (entry.cause && entry.cause.trim().length > 0) {
+    lines.push(`## ${SECTION_CAUSE}`, "", entry.cause.trim(), "");
+  }
+  lines.push(`## ${SECTION_WORKAROUND}`, "", entry.workaround.trim(), "");
+  return lines.join("\n");
+}
+function readSections(body) {
+  const marks = [];
+  for (const heading of [SECTION_SYMPTOM, SECTION_CAUSE, SECTION_WORKAROUND]) {
+    const m = new RegExp(`^##[ \\t]+${heading}[ \\t]*$`, "im").exec(body);
+    if (m) marks.push({ key: heading.toLowerCase(), from: m.index, to: m.index + m[0].length });
+  }
+  marks.sort((a, b) => a.from - b.from);
+  const sections = /* @__PURE__ */ new Map();
+  marks.forEach((mark, i) => {
+    const end = i + 1 < marks.length ? marks[i + 1].from : body.length;
+    sections.set(mark.key, body.slice(mark.to, end).trim());
+  });
+  return sections;
+}
+function parse(text, fallbackId) {
+  const meta = {};
+  let body = text;
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (fm) {
+    for (const line of fm[1].split(/\r?\n/)) {
+      const sep = line.indexOf(":");
+      if (sep <= 0) continue;
+      meta[line.slice(0, sep).trim()] = line.slice(sep + 1).trim();
+    }
+    body = text.slice(fm[0].length);
+  }
+  const sections = readSections(body);
+  const occurrences = Number.parseInt(meta.occurrences ?? "1", 10);
+  return {
+    id: meta.id || fallbackId,
+    title: meta.title || fallbackId.replace(/-/g, " "),
+    tools: (meta.tools ?? "").split(",").map((t) => t.trim()).filter((t) => t.length > 0),
+    firstSeen: meta.firstSeen || "",
+    lastSeen: meta.lastSeen || meta.firstSeen || "",
+    occurrences: Number.isFinite(occurrences) && occurrences > 0 ? occurrences : 1,
+    reported: meta.reported === "true",
+    issueUrl: meta.issueUrl && meta.issueUrl.length > 0 ? meta.issueUrl : void 0,
+    // A hand-edited file with no recognised headings still has its text kept,
+    // rather than being silently reduced to an empty entry.
+    symptom: sections.get(SECTION_SYMPTOM.toLowerCase()) ?? (sections.size === 0 ? body.trim() : ""),
+    cause: sections.get(SECTION_CAUSE.toLowerCase()) || void 0,
+    workaround: sections.get(SECTION_WORKAROUND.toLowerCase()) ?? ""
+  };
+}
+function readEntry(file) {
+  try {
+    return parse(fs6.readFileSync(file, "utf8"), path6.basename(file, ".md"));
+  } catch {
+    return null;
+  }
+}
+function logIssue(input) {
+  const id = slugify(input.title);
+  const file = entryPath(id);
+  const existing = fs6.existsSync(file) ? readEntry(file) : null;
+  const entry = {
+    id,
+    title: oneLine(input.title),
+    tools: input.tools ?? existing?.tools ?? [],
+    firstSeen: existing?.firstSeen || today(),
+    lastSeen: today(),
+    // Repeats are worth counting: an entry seen five times is the one most
+    // worth reporting, and the count is the only evidence of that.
+    occurrences: (existing?.occurrences ?? 0) + 1,
+    // Reporting state belongs to the entry, not to this sighting — a fresh
+    // description of a known problem must not un-report it.
+    reported: existing?.reported ?? false,
+    issueUrl: existing?.issueUrl,
+    symptom: input.symptom,
+    // A cause worked out once is not lost because a later sighting was logged
+    // without one.
+    cause: input.cause ?? existing?.cause,
+    workaround: input.workaround
+  };
+  ensureJournalDir();
+  fs6.writeFileSync(file, render(entry), "utf8");
+  return {
+    id,
+    path: file,
+    occurrences: entry.occurrences,
+    previouslyLogged: existing !== null,
+    reported: entry.reported,
+    issueUrl: entry.issueUrl
+  };
+}
+function listIssues(status = "all", tool) {
+  const { scope } = journalRoot();
+  const dir = journalDir();
+  let entries = [];
+  try {
+    entries = fs6.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path6.join(dir, f))).filter((e) => e !== null);
+  } catch {
+    entries = [];
+  }
+  const wanted = tool?.trim().toLowerCase();
+  const filtered = entries.filter((e) => {
+    const byStatus = status === "all" ? true : status === "reported" ? e.reported : !e.reported;
+    if (!byStatus) return false;
+    if (!wanted) return true;
+    return e.tools.some((t) => t.toLowerCase() === wanted) || e.title.toLowerCase().includes(wanted);
+  });
+  filtered.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences);
+  return {
+    dir,
+    scope,
+    repo: REPO,
+    newIssueUrl: NEW_ISSUE_URL,
+    serverVersion: packageVersion(),
+    platform: process.platform,
+    count: filtered.length,
+    issues: filtered
+  };
+}
+function markReported(id, url) {
+  const file = entryPath(slugify(id));
+  const entry = fs6.existsSync(file) ? readEntry(file) : null;
+  if (!entry) {
+    const known = listIssues("all").issues.map((e) => e.id);
+    throw new Error(
+      `No journal entry with id "${id}".` + (known.length > 0 ? ` Known ids: ${known.join(", ")}` : "")
+    );
+  }
+  entry.reported = true;
+  if (url) entry.issueUrl = oneLine(url);
+  fs6.writeFileSync(file, render(entry), "utf8");
+  return entry;
+}
+
 // src/util/pngImage.ts
 function imageContent(meta, base64) {
   return {
@@ -1470,13 +1749,22 @@ function imageContent(meta, base64) {
 var { OpSchemas: OpSchemas2 } = schemas_exports;
 var VISION_OPS = /* @__PURE__ */ new Set(["screenshot_frame", "screenshot_layer"]);
 var ASYNC_OPS = /* @__PURE__ */ new Set(["run_batch"]);
-var SERVER_OPS = /* @__PURE__ */ new Set(["await_job", "get_job", "cancel_job", "check_setup", "setup_panel"]);
+var SERVER_OPS = /* @__PURE__ */ new Set([
+  "await_job",
+  "get_job",
+  "cancel_job",
+  "check_setup",
+  "setup_panel",
+  "log_issue",
+  "list_known_issues",
+  "mark_issue_reported"
+]);
 var AwaitJobSchema = schemas_exports.AwaitJob;
 var GetJobSchema = schemas_exports.GetJob;
 var CancelJobSchema = schemas_exports.CancelJob;
 function createServer() {
   const server = new Server(
-    { name: "after-effects-mcp", version: "0.1.1" },
+    { name: "after-effects-mcp", version: "0.1.2" },
     { capabilities: { tools: {}, logging: {} } }
   );
   const bridge = new HttpClient();
@@ -1535,6 +1823,19 @@ function createServer() {
           const installed = await installPanel({ enableDebugMode: a.enableDebugMode, force: a.force });
           return textResult({ ...installed, setup: await checkSetup() });
         }
+        if (name === "log_issue") {
+          const a = schemas_exports.LogIssue.parse(rawArgs);
+          return textResult(logIssue(a));
+        }
+        if (name === "list_known_issues") {
+          const a = schemas_exports.ListKnownIssues.parse(rawArgs);
+          return textResult(listIssues(a.status ?? "all", a.tool));
+        }
+        if (name === "mark_issue_reported") {
+          const a = schemas_exports.MarkIssueReported.parse(rawArgs);
+          const entry = markReported(a.id, a.url);
+          return textResult({ ok: true, id: entry.id, reported: true, issueUrl: entry.issueUrl });
+        }
       } catch (e) {
         return errorResult(e.message);
       }
@@ -1663,7 +1964,7 @@ ${USAGE}`);
   await server.connect(transport);
   logger.info("MCP server running on stdio");
 }
-var VERSION = "0.1.1";
+var VERSION = "0.1.2";
 main().catch((e) => {
   logger.error("fatal", e.message);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engine-room/after-effects-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Control Adobe After Effects with AI — describe the animation you want and it gets built: layers, keyframes, effects, expressions and text, all editable afterwards.",
   "license": "MIT",

package/panel/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.1.1"
+<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.1.2"
                    ExtensionBundleName="AE MCP Bridge" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <ExtensionList>
-    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.1.1" />
+    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.1.2" />
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/panel/jsx/bundle.jsx

@@ -1,5 +1,5 @@
 // Auto-generated bundle. Do not edit directly — edit files in packages/jsx/.
-// Generated 2026-08-10T15:26:38.133Z
+// Generated 2026-08-11T09:11:46.741Z
 
 // ===== core.jsx =====
 

package/panel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineroom/ae-panel",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": true,
   "description": "Invisible CEP extension hosting an HTTP+WS bridge inside After Effects.",
   "dependencies": {