comfyui-mcp
Version:
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),
718 lines • 27.2 kB
JavaScript
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync, } from "node:fs";
import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
import { config } from "../config.js";
import { assertSafeRepoName, nonInteractiveGitEnv, } from "./node-management.js";
import { ComfyUIError } from "../utils/errors.js";
import { logger } from "../utils/logger.js";
// ---------------------------------------------------------------------------
// Path-jailed live custom-node dev tools.
//
// Port of filliptm/ComfyUI_FL-MCP's coding_tools.py (read/search/write/patch/
// git, hard-jailed to custom_nodes/ with bounded output) onto our stack, plus
// Windows symlink/junction/ADS safety and the seam-injected deps pattern used
// by node-authoring.ts. LOCAL-ONLY: every tool needs config.comfyuiPath.
//
// Design + rationale: docs/design/node-dev-tools.md.
// ---------------------------------------------------------------------------
export class NodeDevError extends ComfyUIError {
constructor(message, details) {
super(message, "NODE_DEV_ERROR", details);
this.name = "NodeDevError";
}
}
/**
* Refusal returned when a git write (commit/push) is attempted while the
* COMFYUI_MCP_ALLOW_GIT_WRITES flag is off. Structured so an agent can
* self-correct (see docs/design/node-dev-tools.md). The gates framework is
* deferred to ROADMAP Theme G; this narrow flag is what Theme G will absorb.
*/
export class GitWritesDisabledError extends ComfyUIError {
constructor(action) {
super(`node_pack_git "${action}" is disabled by configuration. Set the ` +
`environment variable COMFYUI_MCP_ALLOW_GIT_WRITES=1 (or "true") to ` +
`allow git commit/push from this server, then retry. Read-only actions ` +
`(status/diff/log) are always available.`, "DISABLED_BY_CONFIG");
this.name = "GitWritesDisabledError";
}
toToolResult() {
return {
isError: true,
content: [
{
type: "text",
text: JSON.stringify({
error: "DISABLED_BY_CONFIG",
disabled_by_config: true,
required_flag: "COMFYUI_MCP_ALLOW_GIT_WRITES=1",
message: this.message,
}),
},
],
};
}
}
// ---------------------------------------------------------------------------
// FL-MCP output-bounding constants (its proven values).
// ---------------------------------------------------------------------------
export const READ_DEFAULT_LINES = 240;
export const READ_MAX_LINES = 800;
export const READ_DEFAULT_CHARS = 12_000;
export const READ_MAX_CHARS = 24_000;
/** Long lines are chunked at this width so a single minified line can't blow the budget. */
export const LONG_LINE_CHUNK = 1_000;
/** Per-match line cap for search results. */
export const SEARCH_LINE_MAX = 600;
/** Bound on any subprocess (git / patch) stdout+stderr surfaced to the caller. */
export const CMD_OUTPUT_MAX = 12_000;
export const LIST_DEFAULT_ENTRIES = 500;
export const LIST_MAX_ENTRIES = 2_000;
export const SEARCH_DEFAULT_RESULTS = 50;
export const SEARCH_MAX_RESULTS = 100;
/** Skip files larger than this in the builtin search walker. */
const SEARCH_MAX_FILE_BYTES = 1024 * 1024;
/** Hard cap on files the builtin walker will open in one search. */
const SEARCH_MAX_SCANNED_FILES = 20_000;
const GIT_TIMEOUT_MS = 60_000;
const GIT_PUSH_TIMEOUT_MS = 180_000;
const SKIP_DIRS = new Set([".git", "__pycache__", "node_modules"]);
function defaultSpawn(cmd, args, opts) {
const res = spawnSync(cmd, args, {
cwd: opts.cwd,
encoding: "utf-8",
timeout: opts.timeoutMs,
input: opts.input,
env: opts.env,
maxBuffer: 32 * 1024 * 1024,
windowsHide: true,
});
if (res.error) {
const e = res.error;
if (e.code === "ENOENT") {
throw new NodeDevError(`"${cmd}" was not found on PATH. Install ${cmd} to use this operation.`);
}
throw new NodeDevError(`Failed to execute ${cmd}: ${e.message}`);
}
return {
status: res.status,
stdout: res.stdout ?? "",
stderr: res.stderr ?? "",
};
}
export const defaultDeps = {
existsSync,
isDirectory: (p) => {
try {
return statSync(p).isDirectory();
}
catch {
return false;
}
},
isFile: (p) => {
try {
return statSync(p).isFile();
}
catch {
return false;
}
},
fileSize: (p) => {
try {
return statSync(p).size;
}
catch {
return 0;
}
},
listDir: (p) => readdirSync(p, { withFileTypes: true }).map((d) => ({
name: d.name,
isDir: d.isDirectory(),
})),
readFileText: (p) => readFileSync(p, "utf-8"),
readFileBuffer: (p) => readFileSync(p),
writeFileText: (p, contents) => writeFileSync(p, contents, "utf-8"),
mkdirp: (p) => {
mkdirSync(p, { recursive: true });
},
realpath: (p) => realpathSync.native(p),
hasRipgrep: () => {
try {
const res = spawnSync("rg", ["--version"], {
stdio: "ignore",
timeout: 5_000,
windowsHide: true,
});
return res.status === 0;
}
catch {
return false;
}
},
runGit: (args, opts) => defaultSpawn("git", args, { ...opts, env: nonInteractiveGitEnv() }),
runRipgrep: (args, opts) => defaultSpawn("rg", args, opts),
};
// ---------------------------------------------------------------------------
// Path jail
// ---------------------------------------------------------------------------
const WIN_RESERVED = new Set([
"CON",
"PRN",
"AUX",
"NUL",
...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`),
...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`),
]);
/**
* Reject inputs whose SHAPE is dangerous on Windows (NTFS alternate data
* streams, reserved device names, trailing dots/spaces, UNC paths, and
* drive-relative paths like "C:x"). Applied to raw input on every platform so
* behavior is uniform and a repo synced from Windows can't smuggle a hazard.
*/
function assertNoWindowsHazards(raw) {
// UNC path (\\server\share or //server/share).
if (/^[\\/]{2}/.test(raw)) {
throw new NodeDevError(`Refusing UNC path "${raw}": paths must stay inside custom_nodes/.`);
}
// Drive-relative path: a drive letter + colon NOT followed by a separator
// ("C:x" resolves against the drive's CWD, escaping the jail).
if (/^[a-zA-Z]:(?![\\/])/.test(raw)) {
throw new NodeDevError(`Refusing drive-relative path "${raw}": it is ambiguous and can escape ` +
`custom_nodes/. Use a path relative to custom_nodes/ or a full absolute path.`);
}
// Strip a leading absolute drive prefix ("C:") before scanning segments so
// the drive's own colon isn't flagged as an ADS.
const afterDrive = /^[a-zA-Z]:[\\/]/.test(raw) ? raw.slice(2) : raw;
for (const seg of afterDrive.split(/[\\/]/)) {
if (!seg)
continue;
if (seg.includes(":")) {
throw new NodeDevError(`Refusing NTFS alternate data stream in "${seg}": ':' is not allowed in a path segment.`);
}
const stem = seg.split(".")[0].toUpperCase();
if (WIN_RESERVED.has(seg.toUpperCase()) || WIN_RESERVED.has(stem)) {
throw new NodeDevError(`Refusing reserved Windows device name "${seg}".`);
}
if (/[ .]$/.test(seg)) {
throw new NodeDevError(`Refusing path segment "${seg}": trailing dot or space is unsafe on Windows.`);
}
}
}
export function customNodesRoot() {
if (!config.comfyuiPath) {
throw new NodeDevError("This operation requires a local ComfyUI install, but config.comfyuiPath " +
"is not set (running in remote --comfyui-url mode). Set COMFYUI_PATH to " +
"your local ComfyUI directory to read, search, or edit custom-node source.");
}
return resolve(config.comfyuiPath, "custom_nodes");
}
function isEscape(root, candidate) {
const rel = relative(root, candidate);
return (rel.startsWith("..") ||
isAbsolute(rel) ||
rel.split(/[\\/]/).includes(".."));
}
/** Realpath the deepest existing ancestor, re-appending the not-yet-existing tail. */
function realpathDeepestExisting(abs, deps) {
let cur = abs;
const tail = [];
// Guard against pathological loops.
for (let i = 0; i < 4096; i++) {
if (deps.existsSync(cur)) {
const real = deps.realpath(cur);
return tail.length ? join(real, ...tail.reverse()) : real;
}
const parent = dirname(cur);
if (parent === cur)
return abs;
tail.push(basename(cur));
cur = parent;
}
return abs;
}
/**
* The single auditable jail resolver. Returns the realpath'd absolute path and
* its path relative to the realpath'd custom_nodes root. Throws NodeDevError on
* any lexical- or symlink-based escape. rel === "" denotes the root itself;
* callers that must not touch the root reject an empty rel.
*/
export function resolveInJail(input, deps = defaultDeps) {
const raw = (input ?? "").trim();
if (!raw)
throw new NodeDevError("A path is required (received an empty string).");
assertNoWindowsHazards(raw);
const root = customNodesRoot();
const candidate = isAbsolute(raw) ? resolve(raw) : resolve(root, raw);
// 1. Lexical containment on the un-resolved candidate.
if (isEscape(root, candidate)) {
throw new NodeDevError(`Refusing "${input}": resolves to "${candidate}", which is outside custom_nodes/.`);
}
// 2. Symlink/junction safety: re-check containment on realpaths.
const realRoot = deps.existsSync(root) ? deps.realpath(root) : root;
const realCandidate = realpathDeepestExisting(candidate, deps);
if (isEscape(realRoot, realCandidate)) {
throw new NodeDevError(`Refusing "${input}": its real path "${realCandidate}" escapes custom_nodes/ ` +
`(via a symlink or junction).`);
}
return { abs: realCandidate, rel: relative(realRoot, realCandidate) };
}
/** Resolve a pack folder: name validated + jailed, must be a non-root dir. */
function resolvePackDir(pack, deps) {
const name = (pack ?? "").trim();
assertSafeRepoName(name);
const { abs, rel } = resolveInJail(name, deps);
if (!rel) {
throw new NodeDevError("Refusing to operate on the custom_nodes root itself.");
}
return { abs, name };
}
// ---------------------------------------------------------------------------
// Bounded-text helpers (pure — exported for direct testing)
// ---------------------------------------------------------------------------
/** Break any line longer than `width` into multiple lines of at most `width`. */
export function chunkLongLines(lines, width = LONG_LINE_CHUNK) {
const out = [];
for (const line of lines) {
if (line.length <= width) {
out.push(line);
continue;
}
for (let i = 0; i < line.length; i += width) {
out.push(line.slice(i, i + width));
}
}
return out;
}
/** Clip text to maxChars, appending a truncation notice when clipped. */
export function boundText(text, maxChars, notice = "\n\n[... output truncated — request a narrower range ...]") {
if (text.length <= maxChars)
return { text, truncated: false };
return { text: text.slice(0, maxChars) + notice, truncated: true };
}
// ---------------------------------------------------------------------------
// glob → RegExp (minimal: **, *, ?)
// ---------------------------------------------------------------------------
function globToRegExp(glob) {
let re = "";
for (let i = 0; i < glob.length; i++) {
const c = glob[i];
if (c === "*") {
if (glob[i + 1] === "*") {
re += ".*";
i++;
if (glob[i + 1] === "/")
i++;
}
else {
re += "[^/\\\\]*";
}
}
else if (c === "?") {
re += "[^/\\\\]";
}
else if ("\\^$.|+()[]{}".includes(c)) {
re += "\\" + c;
}
else if (c === "/") {
re += "[/\\\\]";
}
else {
re += c;
}
}
return new RegExp(`^${re}$`, "i");
}
export function listNodePackFiles(options, deps = defaultDeps) {
const { abs: packDir, name } = resolvePackDir(options.pack, deps);
if (!deps.isDirectory(packDir)) {
throw new NodeDevError(`Pack "${name}" does not exist under custom_nodes/.`);
}
const cap = Math.min(Math.max(1, options.maxEntries ?? LIST_DEFAULT_ENTRIES), LIST_MAX_ENTRIES);
const matcher = options.glob ? globToRegExp(options.glob) : null;
const entries = [];
let truncated = false;
const walk = (dir) => {
if (truncated)
return;
let items;
try {
items = deps.listDir(dir);
}
catch {
return;
}
for (const item of items) {
if (truncated)
return;
const full = join(dir, item.name);
const rel = relative(packDir, full).split(/[\\/]/).join("/");
if (item.isDir) {
if (SKIP_DIRS.has(item.name))
continue;
if (!matcher || matcher.test(rel)) {
entries.push({ path: rel, size: 0, dir: true });
if (entries.length >= cap) {
truncated = true;
return;
}
}
walk(full);
}
else {
if (matcher && !matcher.test(rel))
continue;
entries.push({ path: rel, size: deps.fileSize(full), dir: false });
if (entries.length >= cap) {
truncated = true;
return;
}
}
}
};
walk(packDir);
return {
pack: name,
root: packDir,
entries,
truncated,
is_git_repo: deps.isDirectory(join(packDir, ".git")),
has_pyproject: deps.isFile(join(packDir, "pyproject.toml")),
};
}
export function readNodeFile(options, deps = defaultDeps) {
const { abs, rel } = resolveInJail(options.path, deps);
if (!rel)
throw new NodeDevError("Refusing to read the custom_nodes root itself.");
if (!deps.existsSync(abs) || !deps.isFile(abs)) {
throw new NodeDevError(`File not found under custom_nodes/: "${options.path}".`);
}
const size = deps.fileSize(abs);
const raw = deps.readFileText(abs);
// Split on CRLF or LF so total_lines is correct on Windows files.
const allLines = raw.split(/\r\n|\n/);
const totalLines = allLines.length;
const startLine = Math.max(1, Math.floor(options.startLine ?? 1));
const lineCount = Math.min(Math.max(1, Math.floor(options.lineCount ?? READ_DEFAULT_LINES)), READ_MAX_LINES);
const maxChars = Math.min(Math.max(1, Math.floor(options.maxChars ?? READ_DEFAULT_CHARS)), READ_MAX_CHARS);
const startIdx = startLine - 1;
const slice = allLines.slice(startIdx, startIdx + lineCount);
const endLine = Math.min(totalLines, startIdx + slice.length);
const chunked = chunkLongLines(slice);
const bounded = boundText(chunked.join("\n"), maxChars);
return {
path: rel.split(/[\\/]/).join("/"),
content: bounded.text,
start_line: startLine,
end_line: endLine,
total_lines: totalLines,
size,
truncated: bounded.truncated || endLine < totalLines,
};
}
/** Resolve the directory a search runs over (default "." = the whole jail root). */
function resolveSearchDir(path, deps) {
const p = (path ?? ".").trim();
if (p === "." || p === "")
return customNodesRoot();
const { abs } = resolveInJail(p, deps);
return abs;
}
export function searchNodePacks(options, deps = defaultDeps) {
const query = options.query ?? "";
if (!query)
throw new NodeDevError("A non-empty search query is required.");
const cap = Math.min(Math.max(1, options.maxResults ?? SEARCH_DEFAULT_RESULTS), SEARCH_MAX_RESULTS);
const searchDir = resolveSearchDir(options.path, deps);
if (!deps.isDirectory(searchDir)) {
throw new NodeDevError(`Search path does not exist under custom_nodes/.`);
}
if (deps.hasRipgrep()) {
return searchWithRipgrep(query, searchDir, cap, options, deps);
}
return searchBuiltin(query, searchDir, cap, options, deps);
}
function searchWithRipgrep(query, searchDir, cap, options, deps) {
const args = [
"--line-number",
"--no-heading",
"--color",
"never",
"--path-separator",
"/",
"--max-count",
String(cap),
];
if (!options.caseSensitive)
args.push("-i");
if (options.glob)
args.push("-g", options.glob);
for (const d of SKIP_DIRS)
args.push("-g", `!${d}/`);
args.push("--regexp", query, "--", ".");
const res = deps.runRipgrep(args, { cwd: searchDir, timeoutMs: GIT_TIMEOUT_MS });
// rg exits 1 when there are no matches — not an error for us.
if (res.status !== 0 && res.status !== 1) {
throw new NodeDevError(`ripgrep failed (exit ${res.status}): ${res.stderr.slice(0, 500)}`);
}
const matches = [];
let truncated = false;
for (const raw of res.stdout.split(/\r?\n/)) {
if (!raw)
continue;
if (matches.length >= cap) {
truncated = true;
break;
}
const m = /^(.*?):(\d+):(.*)$/.exec(raw);
if (!m)
continue;
matches.push({
file: m[1],
line: Number(m[2]),
text: m[3].slice(0, SEARCH_LINE_MAX),
});
}
return { engine: "ripgrep", matches, truncated };
}
function searchBuiltin(query, searchDir, cap, options, deps) {
const re = new RegExp(query, options.caseSensitive ? "" : "i");
const globMatcher = options.glob ? globToRegExp(options.glob) : null;
const matches = [];
let truncated = false;
let scanned = 0;
const walk = (dir) => {
if (truncated)
return;
let items;
try {
items = deps.listDir(dir);
}
catch {
return;
}
for (const item of items) {
if (truncated)
return;
const full = join(dir, item.name);
if (item.isDir) {
if (SKIP_DIRS.has(item.name) || item.name.startsWith("."))
continue;
walk(full);
continue;
}
const rel = relative(searchDir, full).split(/[\\/]/).join("/");
if (globMatcher && !globMatcher.test(rel))
continue;
if (deps.fileSize(full) > SEARCH_MAX_FILE_BYTES)
continue;
if (++scanned > SEARCH_MAX_SCANNED_FILES) {
truncated = true;
return;
}
let buf;
try {
buf = deps.readFileBuffer(full);
}
catch {
continue;
}
if (buf.includes(0))
continue; // binary — skip
const lines = buf.toString("utf-8").split(/\r\n|\n/);
for (let i = 0; i < lines.length; i++) {
if (re.test(lines[i])) {
if (matches.length >= cap) {
truncated = true;
return;
}
matches.push({
file: rel,
line: i + 1,
text: lines[i].slice(0, SEARCH_LINE_MAX),
});
}
}
}
};
walk(searchDir);
return { engine: "builtin", matches, truncated };
}
export function writeNodeFile(options, deps = defaultDeps) {
const { abs, rel } = resolveInJail(options.path, deps);
if (!rel)
throw new NodeDevError("Refusing to write the custom_nodes root itself.");
const exists = deps.existsSync(abs);
if (exists && !options.overwrite) {
throw new NodeDevError(`File already exists: "${options.path}". Pass overwrite:true to replace it.`);
}
if (exists && !deps.isFile(abs)) {
throw new NodeDevError(`Refusing to overwrite non-file path "${options.path}".`);
}
const parent = dirname(abs);
if (!deps.existsSync(parent)) {
if (options.createDirs === false) {
throw new NodeDevError(`Parent directory does not exist for "${options.path}" and create_dirs is false.`);
}
deps.mkdirp(parent);
}
const content = options.content ?? "";
deps.writeFileText(abs, content);
logger.info("write_node_file", { path: rel, bytes: Buffer.byteLength(content) });
return {
path: rel.split(/[\\/]/).join("/"),
bytes: Buffer.byteLength(content, "utf-8"),
created: !exists,
};
}
/** Extract every file path a unified diff touches (from ---/+++ headers). */
export function parsePatchPaths(patch) {
const paths = new Set();
for (const line of patch.split(/\r?\n/)) {
const m = /^(?:---|\+\+\+) (.+)$/.exec(line);
if (!m)
continue;
let p = m[1].trim();
if (p === "/dev/null")
continue;
// Strip a trailing tab-prefixed timestamp some diff tools append.
p = p.replace(/\t.*$/, "");
// Strip a/ or b/ prefix.
p = p.replace(/^[ab]\//, "");
if (p)
paths.add(p);
}
return [...paths];
}
export function applyNodePatch(patch, deps = defaultDeps) {
if (!patch || !patch.trim()) {
throw new NodeDevError("An empty patch was provided.");
}
const root = customNodesRoot();
// Phase 1: jail-check EVERY touched path BEFORE any git call.
const touched = parsePatchPaths(patch);
if (touched.length === 0) {
throw new NodeDevError("Could not find any file headers (---/+++) in the patch. Provide a unified diff.");
}
for (const p of touched) {
const { rel } = resolveInJail(p, deps);
if (!rel) {
throw new NodeDevError(`Patch would touch the custom_nodes root itself ("${p}").`);
}
}
const input = patch.endsWith("\n") ? patch : patch + "\n";
// Phase 2a: git apply --check (dry run).
const check = deps.runGit(["apply", "--check"], {
cwd: root,
timeoutMs: GIT_TIMEOUT_MS,
input,
});
if (check.status !== 0) {
return {
success: false,
stage: "check",
touched,
stdout: boundText(check.stdout, CMD_OUTPUT_MAX).text,
stderr: boundText(check.stderr, CMD_OUTPUT_MAX).text,
};
}
// Phase 2b: git apply (real).
const apply = deps.runGit(["apply"], {
cwd: root,
timeoutMs: GIT_TIMEOUT_MS,
input,
});
return {
success: apply.status === 0,
stage: "apply",
touched,
stdout: boundText(apply.stdout, CMD_OUTPUT_MAX).text,
stderr: boundText(apply.stderr, CMD_OUTPUT_MAX).text,
};
}
/** Whether git writes (commit/push) are permitted by env flag. Default OFF. */
export function gitWritesEnabled() {
const v = (process.env.COMFYUI_MCP_ALLOW_GIT_WRITES ?? "").trim().toLowerCase();
return v === "1" || v === "true";
}
/** Jail-check a caller-supplied path and return it relative to the pack dir. */
function packRelativePath(packDir, p, deps) {
const { abs } = resolveInJail(p, deps);
const rel = relative(packDir, abs);
if (rel.startsWith("..") || isAbsolute(rel)) {
throw new NodeDevError(`Path "${p}" is outside the target pack.`);
}
return rel.split(/[\\/]/).join("/") || ".";
}
export function nodePackGit(options, deps = defaultDeps) {
const { abs: packDir, name } = resolvePackDir(options.pack, deps);
if (!deps.isDirectory(packDir)) {
throw new NodeDevError(`Pack "${name}" does not exist under custom_nodes/.`);
}
const action = options.action;
const maxChars = Math.min(Math.max(1, options.maxChars ?? CMD_OUTPUT_MAX), READ_MAX_CHARS);
const relPaths = (options.paths ?? []).map((p) => packRelativePath(packDir, p, deps));
let argv;
let timeoutMs = GIT_TIMEOUT_MS;
switch (action) {
case "status":
argv = ["status", "--short", "--branch"];
if (relPaths.length)
argv.push("--", ...relPaths);
break;
case "diff":
argv = ["diff"];
if (relPaths.length)
argv.push("--", ...relPaths);
break;
case "log":
argv = ["log", "--max-count=20", "--pretty=format:%h %an %ad %s", "--date=short"];
if (relPaths.length)
argv.push("--", ...relPaths);
break;
case "commit": {
if (!gitWritesEnabled())
throw new GitWritesDisabledError("commit");
const message = (options.message ?? "").trim();
if (!message) {
throw new NodeDevError("commit requires a non-empty message.");
}
// Stage first (selective or all), then commit.
const addArgs = relPaths.length
? ["add", "--end-of-options", "--", ...relPaths]
: ["add", "-A"];
const add = deps.runGit(addArgs, { cwd: packDir, timeoutMs });
if (add.status !== 0) {
return {
pack: name,
action,
argv: addArgs,
status: add.status,
stdout: boundText(add.stdout, maxChars).text,
stderr: boundText(add.stderr, maxChars).text,
success: false,
};
}
argv = ["commit", "-m", message];
break;
}
case "push":
if (!gitWritesEnabled())
throw new GitWritesDisabledError("push");
argv = ["push"];
timeoutMs = GIT_PUSH_TIMEOUT_MS;
break;
default:
throw new NodeDevError(`Unknown git action "${String(action)}".`);
}
const res = deps.runGit(argv, { cwd: packDir, timeoutMs });
return {
pack: name,
action,
argv,
status: res.status,
stdout: boundText(res.stdout, maxChars).text,
stderr: boundText(res.stderr, maxChars).text,
success: res.status === 0,
};
}
//# sourceMappingURL=node-dev.js.map