@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/[email protected] 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. 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 setup guide: in-depth prerequisites, data-flow and bearer-exposure warnings, verification, key rotation, and LAN access are documented for Virtual Architect users as part of the platform docs.