openutau-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# openutau-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.
+MCP server that lets AI assistants create/edit .ustx projects and render WAV with the
+OpenUtau engine — no GUI, no audio device, no .NET SDK required. Works on
+**Windows / macOS / Linux** (x64 & arm64).
+
+## Use with any MCP client
+
+```bash
+npx -y openutau-mcp
+```
+
+Client config example (ZCode / Claude Desktop style):
+
+```json
+{
+  "mcpServers": {
+    "openutau": {
+      "command": "npx",
+      "args": ["-y", "openutau-mcp"]
+    }
+  }
+}
+```
+
+## How it works
+
+This package is a thin launcher (zero npm dependencies, ~3KB). The platform
+engine ships in per-platform packages (`openutau-mcp-linux-x64`,
+`openutau-mcp-darwin-arm64`, `openutau-mcp-win-x64`, …) that npm installs
+automatically via `optionalDependencies` — only the one matching your OS and
+CPU is downloaded. On first run the engine (~80MB compressed) is extracted once
+to a user cache directory, then speaks MCP over stdio with your client. Later
+runs start instantly from cache.
+
+The engine is built from the [OpenUtau source](https://github.com/stakira/OpenUtau)
+(`OpenUtauMcp` project, .NET 10, self-contained): it hosts the real
+`OpenUtau.Core` render pipeline — phonemizers, resamplers (worldline), mixing —
+headlessly, and exposes it over MCP.
+
+Environment variables / flags:
+
+| Variable | Meaning |
+|---|---|
+| `OPENUTAU_MCP_HOME` | Override cache/install directory |
+| `OPENUTAU_MCP_SINGER_PATHS` | Extra voicebank search directories (path-separator separated) |
+| `OPENUTAU_MCP_DIST_URL` | Download base, only used if the platform package is missing |
+| `--engine-dir=/path` | Skip extraction, use a preinstalled engine copy |
+
+## Voicebanks
+
+Voicebanks are not bundled (licensed separately). Install into your OpenUtau
+data directory's `Singers/` folder:
+
+| Platform | Data directory |
+|---|---|
+| Linux | `~/.local/share/OpenUtau/` |
+| macOS | `~/Library/OpenUtau/` |
+| Windows (portable) | OpenUtau program directory |
+| Windows (installed) | `Documents/OpenUtau/` |
+
+e.g. `ln -s /path/to/voicebank ~/.local/share/OpenUtau/Singers/`
+
+## Tools
+
+`list_voicebanks`, `list_phonemizers`, `create_project`, `load_project`, `save_project`,
+`add_track`, `add_notes`, `set_pitch`, `set_note_expression`, `render`, `get_project_info`.
+
+Tips: one hanzi per note; pass `phonemizer: "ZH CVVC"` in `add_track` for Chinese lyrics;
+use per-note `vibrato` to avoid robotic renders.
+
+## Building the engines
+
+Engine sources live in the OpenUtau tree under `OpenUtauMcp/`. Build with the
+.NET 10 SDK:
+
+```bash
+dotnet publish OpenUtauMcp/OpenUtauMcp.csproj -c Release -r <rid> --self-contained true -o out/<rid>
+```
+
+Cross-publishing from Linux: the CPU ONNX Runtime native libraries must be
+added to the win/osx/linux-arm64 outputs manually (they come from the
+`Microsoft.ML.OnnxRuntime` nupkg — see `repack.sh` in the package repo).

package/bin.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Thin npm launcher for the OpenUtau MCP engine (self-contained .NET binary,
+// ~90MB compressed per platform). Engine tarballs ship in per-platform sibling
+// packages (openutau-mcp-<platform>-<arch>) selected by npm's optional
+// dependencies; on first run the tarball is extracted once to a user cache
+// directory, then spawned and bridged to MCP stdio. Zero npm dependencies.
+import { spawn, execFileSync } from "node:child_process";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { get as httpsGet } from "node:https";
+import { homedir, tmpdir } from "node:os";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const VERSION = "0.2.0";
+const PKG_DIR = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// engine/openutau-mcp-<plat>-v<VERSION>.tar.gz inside the platform package
+const PLATFORM = `${process.platform}-${process.arch}`;
+const TARBALL_NAME = `openutau-mcp-${PLATFORM}-v${VERSION}.tar.gz`;
+
+// Explicit engine dir wins; otherwise extract-and-cache under a per-OS cache dir.
+const engineDirFlag = process.argv.find(a => a.startsWith("--engine-dir="))?.split("=")[1];
+const cacheRoot = () => {
+  if (process.env.OPENUTAU_MCP_HOME) return process.env.OPENUTAU_MCP_HOME;
+  if (process.platform === "win32") {
+    return path.join(process.env.LOCALAPPDATA || path.join(homedir(), "AppData", "Local"), "openutau-mcp");
+  }
+  if (process.platform === "darwin") {
+    return path.join(homedir(), "Library", "Caches", "openutau-mcp");
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(homedir(), ".cache"), "openutau-mcp");
+};
+const CACHE = engineDirFlag ? path.resolve(engineDirFlag) : path.join(cacheRoot(), `v${VERSION}`);
+const ENGINE = process.platform === "win32" ? "OpenUtauMcp.exe" : "OpenUtauMcp";
+const EXE = path.join(CACHE, ENGINE);
+
+const log = msg => console.error(`[openutau-mcp] ${msg}`);
+
+function download(url, dest) {
+  if (url.startsWith("file://")) {
+    copyFileSync(url.slice("file://".length), dest);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const req = httpsGet(url, res => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return resolve(download(res.headers.location, dest));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const total = Number(res.headers["content-length"] || 0);
+      let got = 0, nextStep = 0.25;
+      const out = createWriteStream(dest);
+      res.on("data", chunk => {
+        got += chunk.length;
+        if (total && got / total >= nextStep) {
+          log(`${Math.round(got / 1048576)}MB / ${Math.round(total / 1048576)}MB`);
+          nextStep += 0.25;
+        }
+      });
+      res.on("error", reject);
+      out.on("error", reject);
+      out.on("finish", () => resolve());
+      res.pipe(out);
+    });
+    req.on("error", reject);
+  });
+}
+
+function findBundledTarball() {
+  // 1. Next to this package (dev layout): node_modules/<plat-pkg>/engine/.
+  try {
+    const platPkg = path.join(
+      path.dirname(require.resolve(`openutau-mcp-${PLATFORM}/package.json`)),
+      "engine", TARBALL_NAME);
+    if (existsSync(platPkg)) return platPkg;
+  } catch { /* platform package not installed */ }
+  // 2. Monorepo layout: sibling directories next to the main package.
+  const sibling = path.join(PKG_DIR, "..", `openutau-mcp-${PLATFORM}`, "engine", TARBALL_NAME);
+  if (existsSync(sibling)) return sibling;
+  // 3. Main package itself (legacy single-package layout).
+  const bundled = path.join(PKG_DIR, "engine", TARBALL_NAME);
+  if (existsSync(bundled)) return bundled;
+  return null;
+}
+
+async function ensureEngine() {
+  if (existsSync(EXE)) return;
+  const bundled = findBundledTarball();
+  if (bundled) {
+    mkdirSync(CACHE, { recursive: true });
+    log(`extracting bundled engine to ${CACHE}`);
+    execFileSync("tar", ["xzf", bundled, "-C", CACHE]);
+    if (process.platform !== "win32") {
+      execFileSync("chmod", ["+x", EXE]);
+    }
+    log(`engine ready`);
+    return;
+  }
+  const DIST_BASE = process.env.OPENUTAU_MCP_DIST_URL || "";
+  if (!DIST_BASE) {
+    throw new Error(
+      `no engine for ${PLATFORM}: platform package "openutau-mcp-${PLATFORM}" is not installed ` +
+      `and OPENUTAU_MCP_DIST_URL is not set`);
+  }
+  mkdirSync(CACHE, { recursive: true });
+  const url = `${DIST_BASE}/openutau-mcp-${PLATFORM}-v${VERSION}.tar.gz`;
+  const tarball = path.join(tmpdir(), TARBALL_NAME);
+  log(`engine not cached; downloading ${url}`);
+  await download(url, tarball);
+  log(`extracting to ${CACHE}`);
+  execFileSync("tar", ["xzf", tarball, "-C", CACHE]);
+  if (process.platform !== "win32") {
+    execFileSync("chmod", ["+x", EXE]);
+  }
+  log(`engine ready`);
+}
+
+function warnNoVoicebanks() {
+  let singers;
+  if (process.platform === "linux") {
+    singers = path.join(process.env.XDG_DATA_HOME || path.join(homedir(), ".local", "share"), "OpenUtau", "Singers");
+  } else if (process.platform === "darwin") {
+    singers = path.join(homedir(), "Library", "OpenUtau", "Singers");
+  } else {
+    singers = path.join(process.env.OPENUTAU_MCP_HOME || path.join(homedir(), "Documents", "OpenUtau"), "Singers");
+  }
+  if (existsSync(singers) && readdirSync(singers).some(n => !n.startsWith("."))) return;
+  log(`no voicebanks in ${singers}`);
+  log(`add one:  mkdir -p "${singers}" && ln -s /path/to/voicebank "${singers}/"`);
+  log(`or set OPENUTAU_MCP_SINGER_PATHS to a directory containing voicebanks`);
+}
+
+await ensureEngine();
+warnNoVoicebanks();
+
+const child = spawn(EXE, [], { cwd: CACHE, stdio: "inherit" });
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => child.kill("SIGTERM"));
+}
+child.on("error", err => {
+  if (process.platform === "darwin" && (err.code === "EPERM" || err.code === "EACCES")) {
+    log(`macOS blocked the engine (Gatekeeper). Run:  xattr -rc "${CACHE}"`);
+  } else {
+    log(`failed to start engine: ${err.message}`);
+  }
+  process.exit(1);
+});
+child.on("exit", code => process.exit(code ?? 1));

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "openutau-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for AI singing: create/edit .ustx projects and render WAV with OpenUtau engine (no GUI needed)",
+  "type": "module",
+  "bin": {
+    "openutau-mcp": "./bin.js"
+  },
+  "optionalDependencies": {
+    "openutau-mcp-linux-x64": "0.2.0",
+    "openutau-mcp-linux-arm64": "0.2.0",
+    "openutau-mcp-win-x64": "0.2.0",
+    "openutau-mcp-win-arm64": "0.2.0",
+    "openutau-mcp-darwin-arm64": "0.2.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "files": [
+    "bin.js",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "openutau",
+    "utau",
+    "singing",
+    "voicebank",
+    "tts"
+  ]
+}