waxmcp

waxmcp is an npm launcher for the Wax MCP server.

Usage

npx -y waxmcp@latest mcp serve

For Claude Code, register with wax-cli (not this launcher):

swift run --traits MCPServer wax-cli mcp install --scope user

This launcher (npx waxmcp) serves MCP. It does not implement mcp install --scope.

Shared HTTP (required when more than one client uses ~/.wax/memory.wax):

npx -y waxmcp@latest --transport http --http-host 127.0.0.1 --http-port 3000 --http-endpoint /mcp --embedder minilm

Then add the URL to Codex / Cursor / Hermes. Full host snippets: repo Resources/docs/wax-mcp-hosts.md.

That install flow:

1. npx waxmcp install stages the bundled runtime into a stable local directory
2. wax-cli mcp install registers the staged wax-mcp binary with Claude Code
3. The skill is staged to ~/.local/share/waxmcp/skills/wax-mcp
4. claude install-skill is best-effort; other hosts copy the skill or paste project-rules

So regular MCP sessions do not keep launching through raw npx, and agents get a session lifecycle playbook (also embedded in MCP server instructions).

# If skill auto-install did not run (Claude):
claude install-skill ~/.local/share/waxmcp/skills/wax-mcp

wax-mcp skill = agent operator playbook for MCP tools. wax skill (separate, in the monorepo) = Swift framework integration guidance.

Note: the bundled npm runtime currently ships darwin-arm64 artifacts (Apple Silicon). Intel Mac (darwin-x64) builds are not packaged because MetalANNS Float16 requires Apple Silicon. The underlying wax-mcp server itself supports local Swift builds on macOS and Linux, including --transport http for gateway deployments.

To publish a new version:

cd /path/to/Wax/Resources/npm/waxmcp
npm version patch   # or minor/major/1.2.3 (requires npm publish access)
npm publish --access public

This repo also ships a release script that updates version, syncs Sources/WaxMCPServer/main.swift's serverVersion, and rebuilds the Darwin binaries and resource bundles:

cd /path/to/Wax
./scripts/release-waxmcp.sh 0.1.18
git add Resources/npm/waxmcp/package.json Sources/WaxMCPServer/main.swift Resources/npm/waxmcp/dist
git commit -m "release: bump waxmcp version"

package.json and Sources/WaxMCPServer/main.swift are required to stay in lockstep; the release workflow checks this before publishing.

Artifacts are packaged with wax-cli.sha256 and wax-mcp.sha256 checksums generated by the release scripts for each platform binary.

MCP mode (default)

When invoked with no arguments or with mcp serve, the launcher directly invokes the wax-mcp binary using this search order:

1. $WAX_MCP_BIN
2. Bundled dist/darwin-${arch}/wax-mcp on macOS arm64/x64
3. wax-mcp in PATH
4. ./.build/debug/wax-mcp (current working directory)

You can also serve Wax over HTTP instead of stdio:

./.build/debug/wax-mcp --no-embedder --transport http --http-host 127.0.0.1 --http-port 3000

CLI mode

For all other subcommands (remember, recall, search, etc.), the launcher invokes the wax-cli binary using this search order:

1. $WAX_CLI_BIN
2. Bundled dist/darwin-${arch}/wax-cli on macOS arm64/x64
3. wax-cli in PATH
4. ./.build/debug/wax-cli (current working directory)

Vector-capable CLI commands now auto-start and reuse a background daemon by default, so coding agents can keep calling normal wax-cli/waxmcp commands without learning a separate workflow.

You can still run the daemon directly when you want an explicit long-lived session:

waxmcp daemon --store-path ~/.wax/memory.wax

The daemon keeps one MemoryOrchestrator open, so repeated remember / search / recall requests do not reload the CoreML embedder every time. Simple text-only usage still runs one-shot. Hybrid/vector searches now fail explicitly if vector search is unavailable instead of silently degrading to text-only mode.

Local development

cd /path/to/Wax
swift build --product wax-cli --traits MCPServer
swift build --product wax-mcp --traits MCPServer
export WAX_CLI_BIN=/path/to/Wax/.build/debug/wax-cli
npx --yes ./Resources/npm/waxmcp mcp doctor