@lovinka/onyx-mcp

npm launcher for the Onyx MCP server — the local bridge that lets AI agents use vault credentials (HTTP calls, child-process env, browser logins over CDP) without the secret values ever entering the model's context.

The real server is a native Swift binary (macOS-only) published at https://onyx.lovinka.com/downloads/onyx-mcp-macos.zip. npm tarballs can't carry its framework bundles (symlinks), so this package is a thin, dependency-free launcher: on first run it downloads the zip, verifies it against the site's SHA256SUMS, extracts it with ditto (signatures and symlinks intact) into ~/Library/Application Support/Onyx/onyx-mcp-dist/, and execs it with stdio passed straight through.

Install

Fastest path — one guided command takes you from nothing to a verified setup:

npx -y @lovinka/onyx-mcp setup

On a terminal it's fully interactive (Enter accepts every default): it offers to download + install Onyx.app if missing (SHA-256-verified), installs the native MCP server, asks which client to register — Claude Code, Claude Desktop, both, or just print the config — opens the app and waits for your unlock, then finishes with the doctor report. In scripts/CI (or with --yes) it runs non-interactively: install server → register with Claude Code → verify.

Or wire it up yourself:

# Claude Code (user scope) — nothing else needed
claude mcp add --scope user onyx -- npx -y @lovinka/onyx-mcp

# or a global bin
npm i -g @lovinka/onyx-mcp

Not sure what's missing? npx -y @lovinka/onyx-mcp doctor checks the app, the MCP server, the vault (locked/unlocked), and the sync server, with a fix-it hint for each gap. To install the app too, use the one-shot script: curl -fsSL https://onyx.lovinka.com/downloads/install.sh | bash.

Any other MCP client:

{
  "mcpServers": {
    "onyx": { "command": "npx", "args": ["-y", "@lovinka/onyx-mcp"] }
  }
}

The launcher needs the Onyx macOS app running and unlocked — the server talks to it over an owner-only UNIX socket and holds no secrets itself. Get the app at https://onyx.lovinka.com/install.

Commands

| Command | Effect | |---|---| | onyx-mcp | Start the MCP server over stdio (auto-installs on first run) | | onyx-mcp setup | Guided onboarding (interactive on a TTY; --yes for automation): app + server install, client registration, verify | | onyx-mcp doctor | Read-only health check (app, MCP, vault, server) with fix-it hints | | onyx-mcp mcp-config | Print the MCP-client config snippet to register Onyx | | onyx-mcp install | Download + verify the native distribution if missing | | onyx-mcp update | Reinstall when the published build changed | | onyx-mcp where | Print the resolved binary path and install state | | onyx-mcp uninstall | Remove the managed distribution | | onyx-mcp --socket <p> … | Anything else is passed through to the native binary |

Configuration (env)

| Var | Default | Purpose | |---|---|---| | ONYX_BASE_URL | https://onyx.lovinka.com | Download origin (zip + SHA256SUMS) | | ONYX_MCP_DIR | ~/Library/Application Support/Onyx/onyx-mcp-dist | Managed install dir | | ONYX_MCP_BIN | — | Use an existing binary (e.g. /Applications/Onyx MCP/onyx-mcp) and skip the managed install |

Security model

• The launcher never sees or stores secrets; the native server resolves them through the running Onyx app, which enforces per-item ai_access tiers (injectable / human_gated + Touch ID / ai_hidden).
• Downloads are refused on any SHA-256 mismatch against the site's SHA256SUMS.
• Progress/log output goes to stderr only — stdout belongs to the MCP stdio channel.
• Don't run Onyx alongside untrusted MCP servers in the same AI session.

Development

npm install
npm test        # node --test (unit + local-HTTP install flow, no real network)
npm run build   # tsc -> dist/

Lives in the onyx repo under pkg/.