fui-studio-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,33 @@
+FUI Studio MCP Server: Licence
+
+Copyright (c) 2026 sIRwa2. All rights reserved.
+
+This licence covers the software in this package ("the Software"): the
+fui-studio-mcp program and the FUI Studio engine compiled into it. It does
+not cover the third-party components listed in THIRD_PARTY_NOTICES.md, which
+are under their own licences.
+
+1. Use. You may install and run the Software, free of charge, for any
+   purpose, personal or commercial.
+
+2. Your work is yours. Graphics, project files and exports you make with the
+   Software belong to you. This licence claims nothing in them.
+
+3. Restrictions. Except where the law allows it regardless of this licence,
+   you may not:
+   a. copy, sell, sublicense or redistribute the Software, in whole or in
+      part, other than installing it from the official npm package;
+   b. modify the Software, or reverse engineer, decompile or disassemble it,
+      or use its code in another product;
+   c. remove or alter this licence or the copyright notices.
+
+4. No warranty. The Software is provided "as is", without warranty of any
+   kind, express or implied, including fitness for a particular purpose and
+   non-infringement.
+
+5. No liability. In no event shall the copyright holder be liable for any
+   claim, damages or other liability arising from the Software or its use,
+   to the extent the law allows this exclusion.
+
+6. Changes. Later versions of the Software may come with different terms.
+   The terms in the version you installed apply to that version.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# fui-studio-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let an AI assistant build animated HUD and FUI graphics in **FUI Studio**:
+rings, ticks, readouts, crosshairs, scanning bars. You describe it in chat,
+the assistant builds it as a node graph, and you watch it appear in the
+studio, where you can keep editing by hand.
+
+It is an [MCP](https://modelcontextprotocol.io) server: your AI app starts it
+on your computer when it needs it. You don't run it yourself.
+
+## What you need
+
+- **Node.js 18 or newer** ([nodejs.org](https://nodejs.org)). Check with
+  `node --version`.
+- An AI app that supports MCP servers: Claude Desktop, Claude Code, Cursor,
+  VS Code, Windsurf and others.
+- To watch along: FUI Studio in **Chrome or Edge**. In Brave, first turn on
+  `brave://flags/#file-system-access-api`. Firefox and Safari can't open a
+  folder on your computer.
+
+## 1. Pick a projects folder
+
+Make a folder for your FUI projects, for example `FUI-Studio` in your home
+folder. The assistant saves there, and the studio watches the same folder.
+
+## 2. Add the server to your AI app
+
+Each snippet below uses `~/FUI-Studio`; change it if your folder is somewhere
+else. On Windows, write the full path, for example
+`C:\\Users\\you\\FUI-Studio`.
+
+**Claude Desktop**: Settings → Developer → Edit Config, which opens
+`claude_desktop_config.json`. Add:
+
+```json
+{
+  "mcpServers": {
+    "fui-studio": {
+      "command": "npx",
+      "args": ["-y", "fui-studio-mcp", "--projects", "~/FUI-Studio"]
+    }
+  }
+}
+```
+
+Then quit and reopen Claude Desktop.
+
+**Claude Code**: run once in a terminal:
+
+```sh
+claude mcp add fui-studio --scope user -- npx -y fui-studio-mcp --projects ~/FUI-Studio
+```
+
+**Cursor**: Settings → MCP → Add new MCP server, or edit `~/.cursor/mcp.json`
+and use the same `mcpServers` block as Claude Desktop.
+
+**Windsurf**: edit `~/.codeium/windsurf/mcp_config.json` and use the same
+`mcpServers` block as Claude Desktop.
+
+**VS Code (Copilot agent mode)**: create `.vscode/mcp.json` in your project,
+or run *MCP: Open User Configuration*:
+
+```json
+{
+  "servers": {
+    "fui-studio": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "fui-studio-mcp", "--projects", "~/FUI-Studio"]
+    }
+  }
+}
+```
+
+**Any other app**: the command is `npx -y fui-studio-mcp --projects <folder>`,
+over stdio. Instead of `--projects`, you can set the environment variable
+`FUI_PROJECTS`.
+
+> **Windows and Claude Desktop:** if the server doesn't start, use
+> `"command": "cmd"` and put `"/c", "npx"` in front of the other args.
+
+## 3. Open the same folder in the studio
+
+In FUI Studio, click **folder…** in the toolbar and choose your projects
+folder. Once the assistant has saved a project, open it from **Open**. From
+then on, every save the assistant makes shows up within a second, on the page
+you're looking at. One undo takes a change back.
+
+You can edit too:
+
+- If you have unsaved changes when the assistant saves, the studio asks
+  whether to *load theirs* or *keep mine*.
+- If you saved while the assistant was working, its next save is refused and
+  it reopens the file first, so your edits are never silently overwritten.
+
+## Try it
+
+> Make a 1920×1080 radar HUD: a tick ring, a sweeping arc that rotates once
+> every 4 seconds, and a readout with the bearing. Save it as radar.
+
+The assistant looks at its own work as it goes, using `render_preview`. You
+can ask for changes ("thinner ticks, more orange") or make them yourself in
+the studio and ask it to carry on.
+
+## Video (optional)
+
+Projects with a **Video** node need a 31 MB decoder that isn't installed by
+default. Without it, everything else renders and Video nodes stay empty. To
+add it, use these args instead:
+
+```json
+"args": ["-y", "-p", "fui-studio-mcp", "-p", "@ffmpeg/core@0.12.10", "fui-studio-mcp", "--projects", "~/FUI-Studio"]
+```
+
+## What the assistant can do
+
+These are the server's 21 tools:
+
+- **Projects:** `new_project`, `open_project`, `save_project`,
+  `list_projects`, `get_project`.
+- **Building:** `list_node_types`, `add_node`, `add_image`, `remove_node`,
+  `set_param`, `connect`, `disconnect`, `set_keyframe`, `list_nodes`.
+- **Layers and timing:** `list_layers`, `add_clip`, `remove_clip`.
+- **DaVinci Resolve titles:** `set_ograf_controls`.
+- **Output:** `render_preview`, `export` (SVG, PNG, .ograf, .drfx),
+  `render_sequence` (PNG frames).
+
+When it connects, the server gives the assistant a short guide to how
+projects fit together.
+
+## Troubleshooting
+
+- **The assistant says it has no projects folder.** Your config is missing
+  `--projects`.
+- **"npx: command not found", or the server won't start.** Install Node.js,
+  then restart your AI app. Apps started from the Dock or Start menu may not
+  see a Node installed through nvm; in that case, put the full path to `npx`
+  in `"command"`.
+- **The studio doesn't update.** Check that it has the same folder open
+  (**folder…**), and that you opened the very project the assistant is
+  saving.
+- **Which version is this?** Run `npx fui-studio-mcp --version`.
+
+## Licence
+
+Free to use, including commercially; what you make is yours. See `LICENSE`.
+Third-party components are listed in `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+fui-studio-mcp is licensed under the terms in `LICENSE`. It uses the
+components below, each under its own licence.
+
+## Installed alongside (npm dependencies)
+
+npm installs these as separate packages; their licence files come with them.
+
+| Package | Licence |
+| --- | --- |
+| @modelcontextprotocol/sdk | MIT |
+| @resvg/resvg-wasm | MPL-2.0 |
+| clipper-lib | Boost Software License 1.0 |
+| opentype.js | MIT |
+| polygon-clipping | MIT |
+| zod | MIT |
+
+## Optional: video
+
+`@ffmpeg/core` (ffmpeg.wasm) is not part of this package. Install it only if
+you want Video nodes to render; it is licensed GPL-2.0-or-later and carries its
+own notices.
+
+## Fonts (in `files/`)
+
+The bundled typefaces are under the SIL Open Font License 1.1, except the X11
+misc-fixed bitmap faces (public domain) and Symbols Nerd Font Mono (MIT, with
+its glyph sets under their own licences). Each licence is in `files/`:
+
+- `LICENSE-Anton-SC.txt`
+- `LICENSE-IBM-Plex.txt`
+- `LICENSE-Inter.txt`
+- `LICENSE-JetBrains-Mono.txt`
+- `LICENSE-Misc-Fixed.txt`
+- `LICENSE-Nerd-Fonts-Symbols.txt`
+- `LICENSE-Orbitron.txt`
+- `LICENSE-Press-Start-2P.txt`
+- `LICENSE-Rajdhani.txt`
+- `LICENSE-Silkscreen.txt`
+- `LICENSE-Tektur.txt`
+- `LICENSE-Noto-Sans-Symbols-2.txt`
+
+## The OGraf runtime (in `dist/`)
+
+Exported DaVinci Resolve titles embed a runtime script; the libraries it
+bundles and their licences are listed in `dist/LICENSES.txt` and
+`dist/outline/LICENSES.txt`, and are written into every export.

package/dist/LICENSES.txt

@@ -0,0 +1,51 @@
+FUI Studio OGraf runtime: third-party notices
+
+The component file in this package bundles the following libraries.
+
+========================================================================
+clipper-lib 6.4.2
+========================================================================
+
+License: BSL
+
+========================================================================
+polygon-clipping 0.15.7
+========================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2018 Mike Fogel <mike@fogel.ca> - covers everything not specially attributed to others below.
+
+Copyright (c) 2016 Alexander Milevski <info@w8r.name> - covers all portions originally part of github:w8r/martinez, from which this project was forked on Febuary 2, 2018.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+========================================================================
+zod 3.25.76
+========================================================================
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunk-CTQA7NSS.js

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/chunk-RAHWGTHJ.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import {
+  FONT_FACES,
+  bdfGlyphs,
+  bdfMeasure,
+  bdfOutline,
+  facesFor,
+  fileFormat,
+  fileName,
+  fontFaceCss,
+  localFontBytes,
+  parseBdf,
+  resolveFace
+} from "./chunk-W7L36Z34.js";
+
+// ../../packages/fonts/dist/chunk-MTHRWFM6.js
+import * as opentype from "opentype.js";
+var lib = typeof opentype.parse === "function" ? opentype : opentype.default;
+var parse2 = (buffer, opt) => lib.parse(buffer, opt);
+
+// ../../packages/fonts/dist/chunk-GW34POSA.js
+var FALLBACK_CAP_HEIGHT = 0.7;
+var FALLBACK_X_HEIGHT = 0.5;
+var PATH_PRECISION = 3;
+var internals = (font) => font;
+function forgetCcmp(font) {
+  const gsub = internals(font).tables.gsub;
+  if (!gsub) return;
+  const ccmp = new Set(gsub.features.map((f, i) => f.tag === "ccmp" ? i : -1).filter((i) => i >= 0));
+  if (ccmp.size === 0) return;
+  const strip = (langSys) => {
+    if (langSys) langSys.featureIndexes = langSys.featureIndexes.filter((i) => !ccmp.has(i));
+  };
+  for (const s of gsub.scripts) {
+    strip(s.script.defaultLangSys);
+    for (const l of s.script.langSysRecords ?? []) strip(l.langSys);
+  }
+}
+function toPathData(commands) {
+  const num = (v) => Math.round(v) === v ? String(Math.round(v)) : v.toFixed(PATH_PRECISION);
+  const pack = (...vs) => vs.map((v, i) => (v >= 0 && i > 0 ? " " : "") + num(v)).join("");
+  let d = "";
+  let open = false;
+  for (const c of commands) {
+    switch (c.type) {
+      case "M":
+        if (open) d += "Z";
+        d += "M" + pack(c.x, c.y);
+        open = true;
+        break;
+      case "L":
+        d += "L" + pack(c.x, c.y);
+        break;
+      case "C":
+        d += "C" + pack(c.x1, c.y1, c.x2, c.y2, c.x, c.y);
+        break;
+      case "Q":
+        d += "Q" + pack(c.x1, c.y1, c.x, c.y);
+        break;
+      case "Z":
+        d += "Z";
+        open = false;
+        break;
+    }
+  }
+  if (open) d += "Z";
+  return d;
+}
+function walk({ font, variation }, text, size, letterSpacing, each) {
+  const f = internals(font);
+  const options = { ...f.defaultRenderOptions, kerning: true, letterSpacing: letterSpacing !== 0 ? letterSpacing / size : 0 };
+  const glyphs = f.stringToGlyphs(text, options);
+  const scale = size / font.unitsPerEm;
+  const kerning = f.position.getKerningTables(f.position.getDefaultScriptName(), void 0);
+  let x = 0;
+  for (let i = 0; i < glyphs.length; i++) {
+    const base = glyphs[i];
+    const glyph = variation && f.variation ? f.variation.getTransform(base, variation) : base;
+    each(glyph, x);
+    if (glyph.advanceWidth) x += glyph.advanceWidth * scale;
+    if (i < glyphs.length - 1) {
+      const next = glyphs[i + 1];
+      const kern = kerning ? f.position.getKerningValue(kerning, base.index, next.index) : f.getKerningValue(base, next);
+      x += kern * scale;
+    }
+    if (options.letterSpacing) x += options.letterSpacing * size;
+  }
+  return x;
+}
+function createOutliner(bytesFor) {
+  const fonts = /* @__PURE__ */ new Map();
+  const bitmaps = /* @__PURE__ */ new Map();
+  const bitmapFor = (family, weight) => {
+    const { face } = resolveFace(family, weight);
+    if (!face.bitmap) return void 0;
+    const cached = bitmaps.get(face.file);
+    if (cached !== void 0) return cached;
+    const bytes = localFontBytes(face) ?? bytesFor(face);
+    if (!bytes) return null;
+    let font = null;
+    try {
+      font = parseBdf(bytes);
+    } catch {
+      font = null;
+    }
+    bitmaps.set(face.file, font);
+    return font;
+  };
+  const instanceFor = (family, weight, stretch) => {
+    const { face, variation } = resolveFace(family, weight, stretch);
+    const key = variation ? `${face.file}@${JSON.stringify(variation)}` : face.file;
+    const cached = fonts.get(face.file);
+    if (cached !== void 0) return cached && { font: cached, variation, key };
+    const bytes = localFontBytes(face) ?? bytesFor(face);
+    if (!bytes) return null;
+    let font = null;
+    try {
+      font = parse2(bytes);
+      forgetCcmp(font);
+    } catch {
+      font = null;
+    }
+    fonts.set(face.file, font);
+    return font && { font, variation, key };
+  };
+  const whole = ({ text, family, weight, stretch, size, letterSpacing }) => {
+    const bitmap = bitmapFor(family, weight);
+    if (bitmap !== void 0) return bitmap ? bdfOutline(bitmap, text, size, letterSpacing) : void 0;
+    if (text.length === 0) return { d: "", width: 0 };
+    const instance = instanceFor(family, weight, stretch);
+    if (!instance) return void 0;
+    const commands = [];
+    const width = walk(instance, text, size, letterSpacing, (glyph, x) => {
+      commands.push(...glyph.getPath(x, 0, size).commands);
+    });
+    return { d: toPathData(commands), width };
+  };
+  const glyphs = ({ text, family, weight, stretch, size, letterSpacing }) => {
+    const bitmap = bitmapFor(family, weight);
+    if (bitmap !== void 0) return bitmap ? bdfGlyphs(bitmap, text, size, letterSpacing) : void 0;
+    if (text.length === 0) return { glyphs: [], width: 0 };
+    const instance = instanceFor(family, weight, stretch);
+    if (!instance) return void 0;
+    const scale = size / instance.font.unitsPerEm;
+    const out = [];
+    const width = walk(instance, text, size, letterSpacing, (glyph, x) => {
+      out.push({
+        d: toPathData(glyph.getPath(0, 0, size).commands),
+        x,
+        advance: (glyph.advanceWidth ?? 0) * scale
+      });
+    });
+    return { glyphs: out, width };
+  };
+  const verticals = /* @__PURE__ */ new Map();
+  const verticalsFor = ({ font, variation, key }) => {
+    const hit = verticals.get(key);
+    if (hit) return hit;
+    const upem = font.unitsPerEm;
+    const f = internals(font);
+    const top = (ch) => {
+      const base = font.charToGlyph(ch);
+      if (!base || base.index === 0) return void 0;
+      const glyph = variation && f.variation ? f.variation.getTransform(base, variation) : base;
+      const yMax = glyph.getMetrics().yMax;
+      return typeof yMax === "number" && yMax > 0 ? yMax / upem : void 0;
+    };
+    const os2 = f.tables.os2;
+    const fromTable = (k) => {
+      const v = os2?.[k];
+      return typeof v === "number" && v > 0 ? v / upem : void 0;
+    };
+    const made = {
+      capHeight: top("H") ?? fromTable("sCapHeight") ?? FALLBACK_CAP_HEIGHT,
+      xHeight: top("x") ?? fromTable("sxHeight") ?? FALLBACK_X_HEIGHT
+    };
+    verticals.set(key, made);
+    return made;
+  };
+  const measure = ({ text, family, weight, stretch, size, letterSpacing }) => {
+    const bitmap = bitmapFor(family, weight);
+    if (bitmap !== void 0) return bitmap ? bdfMeasure(bitmap, text, size, letterSpacing) : void 0;
+    const instance = instanceFor(family, weight, stretch);
+    if (!instance) return void 0;
+    const v = verticalsFor(instance);
+    return {
+      width: text.length === 0 ? 0 : walk(instance, text, size, letterSpacing, () => {
+      }),
+      capHeight: v.capHeight * size,
+      xHeight: v.xHeight * size
+    };
+  };
+  return Object.assign(whole, { glyphs, measure });
+}
+
+// ../../packages/fonts/dist/node.js
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function fontsDir() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "files");
+}
+function fontPath(face, format) {
+  return join(fontsDir(), fileName(face, format));
+}
+function readFont(face, format) {
+  return readFileSync(fontPath(face, format));
+}
+function loadFaces(families, format = "woff2") {
+  return facesFor(families).map((face) => {
+    const actual = fileFormat(face, format);
+    return { ...face, format: actual, base64: readFont(face, actual).toString("base64") };
+  });
+}
+function fontDefs(families, format = "woff2") {
+  const css = fontFaceCss(loadFaces(families, format));
+  return css === "" ? "" : `<style>${css}</style>`;
+}
+function allTtfBuffers() {
+  return FONT_FACES.filter((f) => !f.bitmap).map((face) => ({ face, data: readFont(face, "ttf") }));
+}
+function nodeOutliner() {
+  return createOutliner((face) => {
+    const buf = readFont(face, fileFormat(face, "ttf"));
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  });
+}
+
+export {
+  loadFaces,
+  fontDefs,
+  allTtfBuffers,
+  nodeOutliner
+};