@bitflower/va-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bitflower
+
+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/README.md

@@ -0,0 +1,90 @@
+# @bitflower/va-mcp
+
+Install the **Virtual Architect** MCP server and its SessionStart playbook
+into a Claude Code project, with a single command. The installer registers
+the `virtual-architect` MCP server with your local `claude` CLI and drops a
+SessionStart hook into the project so every Claude Code session in that
+directory can call Virtual Architect tools and starts with a short usage
+playbook in context. It runs entirely on your machine and makes no network
+call to discover or download anything at install time.
+
+## Install
+
+```
+npx @bitflower/va-mcp install \
+    --url https://va.example.com/mcp \
+    --api-key va_live_<your-key>
+```
+
+Targets the current directory by default; pass `--project-dir <path>` to
+target another project. Run `install` with no flags to be prompted
+interactively (the API key is masked as you type).
+
+For reproducible installs (CI, shared setup scripts), pin a version:
+
+```
+npx @bitflower/va-mcp@0.1.0 install --url <url> --api-key <key>
+```
+
+## Uninstall
+
+```
+npx @bitflower/va-mcp uninstall
+```
+
+Deregisters the MCP server and removes the SessionStart hook entry. The
+hook script file is left on disk for you to delete manually.
+
+## Help and version
+
+```
+npx @bitflower/va-mcp --help
+npx @bitflower/va-mcp --version
+```
+
+## Requirements
+
+- The `claude` CLI on your `$PATH` — <https://docs.claude.com/en/docs/claude-code>
+- Node.js 18 or newer
+- A Virtual Architect deployment URL and API key
+
+## gitignore precondition
+
+If the target directory is a git repository, add
+`.claude/settings.local.json` to your `.gitignore` **before** running the
+installer — it refuses otherwise, so per-machine hook configuration never
+gets committed:
+
+```
+grep -qxF '.claude/settings.local.json' .gitignore || echo '.claude/settings.local.json' >> .gitignore
+```
+
+The check is deliberately conservative: it recognizes only an exact-path or
+directory-prefix entry — glob patterns (e.g. `.claude/*`), `!`-negation lines,
+and nested `.gitignore` files are **not** evaluated. See the
+[full guide](../../documentation/mcp-installer-guide.md) for the exact matcher
+semantics. The check is skipped for non-git directories. In a monorepo, put
+the entry in the **project-local** `.gitignore` (the one in the target
+directory), not the repo-root `.gitignore` — the installer reads only the
+target directory's file.
+
+## No catalog lookup or remote calls at install time
+
+The installer performs no catalog lookup or remote download. It talks only
+to your local `claude` CLI and writes into the target project, so it works
+without outbound network access (beyond `npx` fetching the package itself).
+
+## Notes
+
+- **Idempotent:** re-running `install` with the same arguments produces the
+  same on-disk state and does not duplicate the hook entry.
+- **Windows:** use WSL. A native Windows hook format is not part of this
+  release.
+- **Bearer token:** your API key is passed only to the `claude` CLI and is
+  never written to any file the installer creates.
+
+## Full guide
+
+See **[documentation/mcp-installer-guide.md](../../documentation/mcp-installer-guide.md)**
+for prerequisites in depth, the data-flow and bearer-exposure warnings,
+verification steps, key rotation, and LAN access.

package/dist/index.js

@@ -0,0 +1,584 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { realpathSync as realpathSync2 } from "fs";
+import { pathToFileURL } from "url";
+import { Command, CommanderError } from "commander";
+
+// package.json
+var package_default = {
+  name: "@bitflower/va-mcp",
+  version: "1.0.0",
+  description: "Install the Virtual Architect MCP server and SessionStart playbook into a Claude Code project.",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/bitflower/pathrag-ui-virtual-architect.git",
+    directory: "clients/va-mcp"
+  },
+  type: "module",
+  bin: {
+    "va-mcp": "./dist/index.js"
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "npm run build"
+  },
+  keywords: [
+    "mcp",
+    "claude-code",
+    "virtual-architect"
+  ],
+  license: "MIT",
+  publishConfig: {
+    access: "public"
+  },
+  dependencies: {
+    commander: "^12.1.0"
+  },
+  devDependencies: {
+    "@types/node": "^20.14.0",
+    tsup: "^8.3.0",
+    typescript: "^5.6.0",
+    vitest: "^2.1.0"
+  }
+};
+
+// src/errors.ts
+var InstallerError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InstallerError";
+  }
+};
+
+// src/install.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+
+// src/claude-binary.ts
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+// src/constants.ts
+var SERVER_NAME = "virtual-architect";
+var CLAUDE_INSTALL_HINT = "Install Claude Code: https://docs.claude.com/en/docs/claude-code";
+var ANTHROPIC_DATA_FLOW_WARNING = "WARNING: MCP responses flow through Claude \u2192 Anthropic. Review the data-flow implications before deploying for regulated workloads.";
+var BEARER_EXPOSURE_WARNING = "WARNING: 'claude mcp add' accepts the bearer token only via argv, so during this install the API key is briefly visible to other local processes (ps / /proc/<pid>/cmdline). Acceptable on a single-user workstation; treat the key as exposed if other users share this host.";
+
+// src/claude-binary.ts
+var CLAUDE_BIN = "claude";
+function claudeCandidateNames() {
+  if (process.platform === "win32") {
+    return [`${CLAUDE_BIN}.exe`, `${CLAUDE_BIN}.cmd`, `${CLAUDE_BIN}.bat`, CLAUDE_BIN];
+  }
+  return [CLAUDE_BIN];
+}
+function isExecutableFile(filePath) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return false;
+  }
+  if (!stat.isFile()) return false;
+  if (process.platform === "win32") return true;
+  return (stat.mode & 73) !== 0;
+}
+function findClaudeBinary() {
+  const rawPath = process.env.PATH ?? "";
+  if (rawPath === "") return null;
+  const names = claudeCandidateNames();
+  for (const dir of rawPath.split(path.delimiter)) {
+    if (dir === "") continue;
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (isExecutableFile(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function defaultSpawn(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    // Capture (do not inherit) so the token-bearing stderr never reaches our
+    // console; we deliberately drop it.
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return { status: result.status, error: result.error };
+}
+function runClaudeMcpAdd(url, apiKey, cwd, spawn = defaultSpawn) {
+  const args = [
+    "mcp",
+    "add",
+    "-t",
+    "http",
+    SERVER_NAME,
+    url,
+    "--header",
+    `Authorization: Bearer ${apiKey}`
+  ];
+  const { status, error } = spawn(CLAUDE_BIN, args, cwd);
+  if (error) {
+    throw new InstallerError(
+      `could not run 'claude mcp add' (${error.message}). Re-run the command manually with the CLI's --debug flag to diagnose.`
+    );
+  }
+  if (status !== 0) {
+    throw new InstallerError(
+      `'claude mcp add' exited ${status}. Re-run the command manually with the CLI's --debug flag to see details.`
+    );
+  }
+}
+function runClaudeMcpRemove(cwd, spawn = defaultSpawn) {
+  const { status, error } = spawn(CLAUDE_BIN, ["mcp", "remove", SERVER_NAME], cwd);
+  if (error) {
+    throw new InstallerError(
+      `could not run 'claude mcp remove' (${error.message}). Re-run the command manually with the CLI's --debug flag to diagnose.`
+    );
+  }
+  return status === 0;
+}
+
+// src/claude-config.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+
+// src/hook-template.ts
+var HOOK_SCRIPT_NAME = "mcp_sessionstart_hook.sh";
+var HOOK_COMMAND_RELPATH = `.claude/hooks/${HOOK_SCRIPT_NAME}`;
+var HOOK_SCRIPT_CONTENT = `#!/usr/bin/env bash
+# Virtual Architect \u2014 MCP SessionStart hook.
+#
+# Emits the static tool-usage playbook to stdout. Claude Code injects
+# whatever this script writes to stdout into the agent's initial
+# context for the session.
+#
+# No HTTP calls, no MCP fetches, no curl. Hardcoded text only \u2014 keep
+# session start instantaneous and offline-safe.
+set -euo pipefail
+
+cat <<'PLAYBOOK'
+How to use VA's MCP tools:
+- For any natural-language question, START with \`query(question)\` \u2014
+  it runs Virtual Architect's curated retrieval and returns the most
+  relevant grounded paths. Prefer this over search_entities unless you
+  already have a specific entity name in hand.
+- For "what is X connected to?" questions, call search_entities(X) to
+  find the canonical ID, then get_relationships(id).
+- To orient before drilling in, \`list_documents()\` shows what's indexed;
+  follow up with \`query(topic)\` or \`get_document_entities(document_id)\`.
+- Never speculate about entities or relationships not returned by a tool.
+  If a tool returns empty, say so \u2014 do not fabricate.
+PLAYBOOK
+`;
+
+// src/claude-config.ts
+function settingsLocalPath(projectDir) {
+  return path2.join(projectDir, ".claude", "settings.local.json");
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function loadSettings(settingsPath) {
+  let raw;
+  try {
+    raw = fs2.readFileSync(settingsPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw new InstallerError(`cannot read ${settingsPath}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw || "{}");
+  } catch (err) {
+    throw new InstallerError(
+      `existing ${settingsPath} is not valid JSON: ${err.message}`
+    );
+  }
+  if (!isPlainObject(parsed)) {
+    throw new InstallerError(`existing ${settingsPath} is not a JSON object.`);
+  }
+  return parsed;
+}
+function writeSettings(settingsPath, settings) {
+  fs2.mkdirSync(path2.dirname(settingsPath), { recursive: true });
+  fs2.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+}
+function ensureObject(parent, key) {
+  if (!(key in parent)) parent[key] = {};
+  const value = parent[key];
+  if (!isPlainObject(value)) {
+    throw new InstallerError(`settings "${key}" is not an object.`);
+  }
+  return value;
+}
+function ensureArray(parent, key) {
+  if (!(key in parent)) parent[key] = [];
+  const value = parent[key];
+  if (!Array.isArray(value)) {
+    throw new InstallerError(`settings "${key}" is not an array.`);
+  }
+  return value;
+}
+function entryReferences(entry, commandNeedle) {
+  if (!isPlainObject(entry)) return false;
+  const hooks = entry.hooks;
+  if (!Array.isArray(hooks)) return false;
+  return hooks.some(
+    (hook) => isPlainObject(hook) && typeof hook.command === "string" && hook.command.includes(commandNeedle)
+  );
+}
+function addSessionStartHook(settings, hookRelpath) {
+  const hooks = ensureObject(settings, "hooks");
+  const sessionStart = ensureArray(hooks, "SessionStart");
+  if (sessionStart.some((entry2) => entryReferences(entry2, hookRelpath))) return;
+  const entry = {
+    hooks: [{ type: "command", command: `./${hookRelpath}` }]
+  };
+  sessionStart.push(entry);
+}
+function removeSessionStartHook(settings, hookRelpath) {
+  const hooks = settings.hooks;
+  if (!isPlainObject(hooks)) return false;
+  const sessionStart = hooks.SessionStart;
+  if (!Array.isArray(sessionStart)) return false;
+  const kept = sessionStart.filter((entry) => !entryReferences(entry, hookRelpath));
+  if (kept.length === sessionStart.length) return false;
+  if (kept.length > 0) {
+    hooks.SessionStart = kept;
+  } else {
+    delete hooks.SessionStart;
+  }
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+  return true;
+}
+function mergeSettingsLocal(projectDir) {
+  const settingsPath = settingsLocalPath(projectDir);
+  const settings = loadSettings(settingsPath);
+  addSessionStartHook(settings, HOOK_COMMAND_RELPATH);
+  writeSettings(settingsPath, settings);
+}
+function pruneSettingsLocal(projectDir) {
+  const settingsPath = settingsLocalPath(projectDir);
+  if (!fs2.existsSync(settingsPath)) return false;
+  const settings = loadSettings(settingsPath);
+  if (!removeSessionStartHook(settings, HOOK_COMMAND_RELPATH)) return false;
+  writeSettings(settingsPath, settings);
+  return true;
+}
+
+// src/gitignore-check.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+var SETTINGS_RELPATH = ".claude/settings.local.json";
+function stripSlashes(value) {
+  return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function isInsideGitWorkTree(startDir) {
+  let dir = path3.resolve(startDir);
+  for (; ; ) {
+    if (fs3.existsSync(path3.join(dir, ".git"))) return true;
+    const parent = path3.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+function isPathIgnored(projectDir, relpath) {
+  let content;
+  try {
+    content = fs3.readFileSync(path3.join(projectDir, ".gitignore"), "utf8");
+  } catch {
+    return false;
+  }
+  const rel = stripSlashes(relpath);
+  const slash = rel.lastIndexOf("/");
+  const parent = slash >= 0 ? rel.slice(0, slash) : null;
+  const matchesTarget = (candidate) => candidate === rel || parent !== null && candidate === parent;
+  let ignored = false;
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("!")) {
+      if (matchesTarget(stripSlashes(line.slice(1)))) return false;
+      continue;
+    }
+    if (matchesTarget(stripSlashes(line))) ignored = true;
+  }
+  return ignored;
+}
+function checkGitignorePrecondition(projectDir) {
+  if (!isInsideGitWorkTree(projectDir)) return;
+  if (isPathIgnored(projectDir, SETTINGS_RELPATH)) return;
+  throw new InstallerError(
+    `refusing to write ${SETTINGS_RELPATH} into a git work tree. The installer's plain-text gitignore scan found no exact-path or directory-prefix entry that ignores it (globs like '.claude/*' and '!' negation lines are NOT evaluated \u2014 we err on the safe side and refuse if there is any chance the file ends up tracked). To proceed, add an exact entry to ${path3.join(projectDir, ".gitignore")}:
+
+    ${SETTINGS_RELPATH}
+`
+  );
+}
+
+// src/output.ts
+function emit(sink, message) {
+  sink.write(`${message}
+`);
+}
+
+// src/project.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+function resolveProjectDir(projectDir) {
+  let resolved;
+  try {
+    resolved = fs4.realpathSync(path4.resolve(projectDir));
+  } catch {
+    throw new InstallerError(`project directory does not exist: ${projectDir}`);
+  }
+  if (!fs4.statSync(resolved).isDirectory()) {
+    throw new InstallerError(`project directory is not a directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+// src/install.ts
+function writeHookScript(projectDir) {
+  const hooksDir = path5.join(projectDir, ".claude", "hooks");
+  fs5.mkdirSync(hooksDir, { recursive: true });
+  const target = path5.join(hooksDir, HOOK_SCRIPT_NAME);
+  fs5.writeFileSync(target, HOOK_SCRIPT_CONTENT);
+  fs5.chmodSync(target, 493);
+}
+function install(opts, deps = {}) {
+  const findClaude = deps.findClaude ?? findClaudeBinary;
+  const stderr = deps.stderr ?? process.stderr;
+  const projectDir = resolveProjectDir(opts.projectDir);
+  checkGitignorePrecondition(projectDir);
+  if (findClaude() === null) {
+    throw new InstallerError(
+      `the 'claude' CLI was not found on PATH. ${CLAUDE_INSTALL_HINT}`
+    );
+  }
+  emit(stderr, ANTHROPIC_DATA_FLOW_WARNING);
+  emit(stderr, BEARER_EXPOSURE_WARNING);
+  runClaudeMcpAdd(opts.url, opts.apiKey, projectDir, deps.spawn);
+  writeHookScript(projectDir);
+  mergeSettingsLocal(projectDir);
+  emit(
+    stderr,
+    `Installed the Virtual Architect MCP server '${SERVER_NAME}' for the project at ${projectDir}.`
+  );
+  emit(stderr, `Next: cd '${projectDir}' && claude`);
+}
+
+// src/interactive.ts
+import * as readline from "readline";
+var VA_KEY_PREFIX = "va_live_";
+var MAX_ATTEMPTS = 3;
+function isHttpUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
+function readLine(question, io) {
+  const rl = readline.createInterface({ input: io.input, output: io.output });
+  return new Promise((resolve3, reject) => {
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) {
+        reject(
+          new InstallerError(
+            "input stream closed before a value was provided. Re-run with --url/--api-key."
+          )
+        );
+      }
+    });
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      resolve3(answer.trim());
+    });
+  });
+}
+function readSecret(question, io) {
+  const rl = readline.createInterface({ input: io.input, output: io.output, terminal: true });
+  let muted = false;
+  const mutableRl = rl;
+  mutableRl._writeToOutput = (chunk) => {
+    if (!muted || chunk.includes("\n") || chunk.includes("\r")) {
+      io.output.write(chunk);
+    }
+  };
+  return new Promise((resolve3, reject) => {
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) {
+        reject(
+          new InstallerError(
+            "input stream closed before a value was provided. Re-run with --url/--api-key."
+          )
+        );
+      }
+    });
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      io.output.write("\n");
+      resolve3(answer.trim());
+    });
+    muted = true;
+  });
+}
+async function promptUrl(io) {
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const value = await readLine("Virtual Architect deployment URL: ", io);
+    if (isHttpUrl(value)) return value;
+    io.output.write("  Please enter a valid http(s) URL.\n");
+  }
+  throw new InstallerError(
+    "no valid deployment URL provided after several attempts. Re-run with --url <https://\u2026>."
+  );
+}
+async function promptApiKey(io) {
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const value = await readSecret("Virtual Architect API key (input hidden): ", io);
+    if (value.startsWith(VA_KEY_PREFIX)) return value;
+    io.output.write(`  The API key should start with "${VA_KEY_PREFIX}".
+`);
+  }
+  throw new InstallerError(
+    "no valid API key provided after several attempts. Re-run with --api-key <key>."
+  );
+}
+async function promptForMissing(partial, io = {}) {
+  const resolvedIo = {
+    input: io.input ?? process.stdin,
+    output: io.output ?? process.stderr
+  };
+  let url = partial.url;
+  if (url === void 0) {
+    url = await promptUrl(resolvedIo);
+  } else if (!isHttpUrl(url)) {
+    throw new InstallerError(`--url must be a valid http(s) URL, got: ${url}`);
+  }
+  let apiKey = partial.apiKey;
+  if (apiKey === void 0) {
+    apiKey = await promptApiKey(resolvedIo);
+  } else if (!apiKey.startsWith(VA_KEY_PREFIX)) {
+    throw new InstallerError(`--api-key must start with "${VA_KEY_PREFIX}".`);
+  }
+  return { url, apiKey, projectDir: partial.projectDir };
+}
+
+// src/uninstall.ts
+function uninstall(opts, deps = {}) {
+  const stderr = deps.stderr ?? process.stderr;
+  const projectDir = resolveProjectDir(opts.projectDir);
+  const removed = runClaudeMcpRemove(projectDir, deps.spawn);
+  if (removed) {
+    emit(stderr, `Deregistered the Virtual Architect MCP server '${SERVER_NAME}'.`);
+  } else {
+    emit(
+      stderr,
+      `The Virtual Architect MCP server '${SERVER_NAME}' was not registered for this project \u2014 nothing to deregister.`
+    );
+  }
+  const pruned = pruneSettingsLocal(projectDir);
+  if (pruned) {
+    emit(stderr, "Removed the SessionStart hook from .claude/settings.local.json.");
+  } else {
+    emit(stderr, "No SessionStart hook entry found in .claude/settings.local.json.");
+  }
+  emit(stderr, "The hook script under .claude/hooks/ was left in place.");
+}
+
+// src/index.ts
+var PROGRAM_NAME = "va-mcp";
+function buildProgram(deps) {
+  const run = { fn: null };
+  const program = new Command();
+  program.name(PROGRAM_NAME).description(
+    "Install the Virtual Architect MCP server and SessionStart playbook into a Claude Code project."
+  ).version(package_default.version, "-v, --version", "output the version number").configureOutput({
+    writeOut: (str) => deps.stdout.write(str),
+    writeErr: (str) => deps.stderr.write(str)
+  }).exitOverride();
+  program.command("install").description("Register the server with Claude Code and install the SessionStart hook.").option("--url <url>", "Virtual Architect deployment URL").option("--api-key <key>", "Virtual Architect API key (prompted if omitted)").option("--project-dir <dir>", "target project directory", process.cwd()).action((flags) => {
+    run.fn = async () => {
+      const resolved = await promptForMissing(
+        { url: flags.url, apiKey: flags.apiKey, projectDir: flags.projectDir },
+        { output: deps.stderr }
+      );
+      install(resolved, { stderr: deps.stderr });
+    };
+  });
+  program.command("uninstall").description("Deregister the server and remove the SessionStart hook entry.").option("--project-dir <dir>", "target project directory", process.cwd()).action(({ projectDir }) => {
+    run.fn = () => {
+      uninstall({ projectDir }, { stderr: deps.stderr });
+      return Promise.resolve();
+    };
+  });
+  return { program, run };
+}
+async function main(argv, deps = {}) {
+  const resolved = {
+    stdout: deps.stdout ?? process.stdout,
+    stderr: deps.stderr ?? process.stderr
+  };
+  if (argv.length === 0) {
+    const { program: program2 } = buildProgram(resolved);
+    resolved.stdout.write(program2.helpInformation());
+    return 0;
+  }
+  const { program, run } = buildProgram(resolved);
+  try {
+    await program.parseAsync(argv, { from: "user" });
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      return err.exitCode;
+    }
+    throw err;
+  }
+  try {
+    if (run.fn) await run.fn();
+  } catch (err) {
+    if (err instanceof InstallerError) {
+      emit(resolved.stderr, `${PROGRAM_NAME}: ${err.message}`);
+      return 1;
+    }
+    throw err;
+  }
+  return 0;
+}
+async function cli() {
+  const code = await main(process.argv.slice(2));
+  process.exit(code);
+}
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync2(entry)).href;
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  void cli();
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bitflower/va-mcp",
+  "version": "1.0.0",
+  "description": "Install the Virtual Architect MCP server and SessionStart playbook into a Claude Code project.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitflower/pathrag-ui-virtual-architect.git",
+    "directory": "clients/va-mcp"
+  },
+  "type": "module",
+  "bin": {
+    "va-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "virtual-architect"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}