kineto-mcp 0.1.2

package/README.md

@@ -0,0 +1,53 @@
+# kineto-mcp
+
+**Give your coding agent a camera.**
+
+[Kineto](https://github.com/DanielFidalgo/kineto) is a video *compiler*, not a
+screen recorder. You describe a scene as a JSON document; it compiles to an
+MP4. Deterministic, no browser, no display, no render farm.
+
+This package ships Kineto's **MCP server**, so an agent can render, inspect and
+correct video on its own.
+
+## Use it
+
+```sh
+claude mcp add --scope user kineto npx kineto-mcp
+```
+
+That is the whole install — `npx` fetches the binary for your platform on
+first use. Then, in any session:
+
+> Turn these screenshots into a 20-second clip with captions.
+
+> Render a release video from the last ten commits.
+
+> Explain this architecture as a diagram, then make it move.
+
+Prefer a binary on your PATH? `cargo install kineto`, or take an archive from
+[Releases](https://github.com/DanielFidalgo/kineto/releases).
+
+> Use `--scope user`, not the default. Project scope registers the server for
+> one directory only, which is a confusing way to discover that your other
+> sessions cannot see it.
+
+## What the agent gets
+
+Tools to render a document, an asciinema recording, or a storyboard; to
+preview single frames as images so it can *see* what it made; and to check a
+document for the mistakes that are invisible in JSON and obvious on screen —
+text too small to read, colours with no contrast, elements off-canvas.
+
+Reading a frame back is what closes the loop. An agent that can look at its
+own output stops producing slide decks.
+
+## Requirements
+
+Node 18+. **ffmpeg** on `PATH` for encoding — frames render without it.
+
+Prebuilt binaries cover macOS and Linux on arm64 and x64. On anything else,
+`cargo install kineto` builds from source.
+
+## License
+
+MIT OR Apache-2.0

package/bin/kineto-mcp.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Locates the platform binary npm installed and hands control to it.
+//
+// `stdio: "inherit"` is not a detail here. Kineto's MCP server speaks JSON-RPC
+// over stdin/stdout, so the child must receive the real file descriptors --
+// piping through Node would put a buffering layer inside the protocol, and any
+// stray write from this script would corrupt the stream. Nothing here may
+// print to stdout, ever.
+//
+// spawnSync rather than spawn: it blocks until the child exits and forwards
+// the descriptors directly, so there is no parent-side event loop to keep
+// alive and no chance of the wrapper outliving the server.
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+
+// npm installs exactly one of these, chosen by the `os`/`cpu` fields the
+// build script writes into each platform package.
+import { PACKAGES } from "../targets.mjs";
+
+const require = createRequire(import.meta.url);
+
+const key = `${process.platform} ${process.arch}`;
+const pkg = PACKAGES[key];
+
+if (!pkg) {
+  process.stderr.write(
+    `kineto: no prebuilt binary for ${key}.\n` +
+      `Supported: ${Object.keys(PACKAGES).join(", ")}.\n` +
+      `Build from source instead: cargo install kineto\n`,
+  );
+  process.exit(1);
+}
+
+// Node resolves a module's realpath, so under any symlinked layout --
+// `npm link`, npm workspaces, pnpm's default store -- `import.meta.url` points
+// at the package's true location rather than the tree it was installed into,
+// and resolution from there misses its own siblings. A registry install is not
+// symlinked and hits the first branch; the fallbacks are what keep the linked
+// cases working. argv[1] before cwd: under `npx` the cache directory holds the
+// dependency, and the user's cwd is unrelated.
+function resolveBinary(spec) {
+  const bases = [null, dirname(process.argv[1] ?? "."), process.cwd()];
+  for (const base of bases) {
+    try {
+      return base === null ? require.resolve(spec) : require.resolve(spec, { paths: [base] });
+    } catch {
+      // Try the next base; the caller reports failure once all are exhausted.
+    }
+  }
+  return null;
+}
+
+const binary = resolveBinary(`${pkg}/bin/kineto-mcp`);
+if (!binary) {
+  // Optional dependencies fail silently by design, so this is a normal
+  // outcome of --no-optional, a partially populated cache, or an install that
+  // raced. Naming the package is what makes it fixable.
+  process.stderr.write(
+    `kineto: ${pkg} is not installed.\n` +
+      `It is an optional dependency selected by platform; installing with\n` +
+      `--no-optional or --omit=optional skips it. Try: npm install ${pkg}\n`,
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  process.stderr.write(`kineto: failed to run ${binary}: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+// A signalled child has a null status. Reporting 0 there would tell the caller
+// the server exited cleanly when it was killed.
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "kineto-mcp",
+  "version": "0.1.2",
+  "description": "Kineto MCP server: give your coding agent a camera. Compiles declarative scene documents to MP4, animated WebP or PNG. No browser, no display.",
+  "keywords": [
+    "mcp",
+    "video",
+    "mp4",
+    "render",
+    "deterministic",
+    "agent"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "bin": {
+    "kineto-mcp": "bin/kineto-mcp.mjs"
+  },
+  "files": [
+    "bin/kineto-mcp.mjs",
+    "targets.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/guard-publish.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "optionalDependencies": {
+    "kineto-mcp-darwin-arm64": "0.1.2",
+    "kineto-mcp-darwin-x64": "0.1.2",
+    "kineto-mcp-linux-arm64": "0.1.2",
+    "kineto-mcp-linux-x64": "0.1.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/targets.mjs

@@ -0,0 +1,24 @@
+// The supported platforms, in one place.
+//
+// Unscoped: the npm organisation `kineto` was not available, and every name
+// here is. It also lines the package up with the binary and the MCP
+// serverInfo identity, which are both already `kineto-mcp`.
+//
+// The shim maps a running process to a package name; the build script maps a
+// rust target to that same package. Those two lists silently disagreeing is a
+// real failure mode -- add a platform to the builder alone and npm publishes a
+// package nothing resolves; add it to the shim alone and the shim points at a
+// package that was never built. Both import this, and a test asserts the shim
+// covers exactly these.
+
+export const TARGETS = [
+  { rust: "aarch64-apple-darwin", npm: "darwin-arm64", os: "darwin", cpu: "arm64" },
+  { rust: "x86_64-apple-darwin", npm: "darwin-x64", os: "darwin", cpu: "x64" },
+  { rust: "aarch64-unknown-linux-gnu", npm: "linux-arm64", os: "linux", cpu: "arm64" },
+  { rust: "x86_64-unknown-linux-gnu", npm: "linux-x64", os: "linux", cpu: "x64" },
+];
+
+/// `process.platform process.arch` -> package name, as the shim needs it.
+export const PACKAGES = Object.fromEntries(
+  TARGETS.map((t) => [`${t.os} ${t.cpu}`, `kineto-mcp-${t.npm}`]),
+);