/wax-mcp

name: wax-mcp
description: >
  Operator install and diagnose playbook for waxmcp hosts (HTTP vs stdio,
  LaunchAgent, Hermes plugin, doctor, vector-health). Use only when installing,
  repairing, or rewiring a host. Do not use at session start. Do not use when
  MCP remember/recall/stats are already available — follow the live server
  instructions instead of loading this skill.

Wax MCP

The MCP server `instructions` field is the playbook. Do not restate a second lifecycle here. Do not invoke this skill at session start.

Daily tools: `remember`, `recall`, `stats`. Follow the live server instructions instead of restating them here. Aliases stay callable. `WAX_MCP_TOOLS=legacy` restores the previous eight-tool playbook. `WAX_MCP_TOOLS=full` lists the rest. `WAX_MCP_AUTO_SESSION=0` restores explicit-open.

Recall defaults to the current project after project/repo resolution. Pass `scope=global` only for cross-project retrieval (person facts, standing preferences). Global searches the entire local store with no current-project rank boost. It is not an authorization boundary.

Pasteable host rules (pointer only): `references/project-rules.md`.

This is not the Swift framework skill. For embedding Wax in Swift apps, use `Resources/skills/public/wax`.

Install / Host Setup

Stage binaries once:

npx -y waxmcp@latest install

Then wire the **host**, not a new prompt:

| Host | What to do | |------|------------| | Claude Code | `swift run --traits MCPServer wax-cli mcp install --scope user` then `claude install-skill ~/.local/share/waxmcp/skills/wax-mcp` | | Codex | `wax-cli mcp install` prints the stdio block (writes it with `--write-toml-config`) + copies the skill; manual: HTTP URL in `~/.codex/config.toml` | | Cursor | `wax-cli mcp install` merges the stdio entry automatically; manual: HTTP URL in `~/.cursor/mcp.json` + paste `references/project-rules.md` | | Hermes | Native `memory.provider: wax-memory` only (`npx -y waxmcp@latest install-hermes-plugin`). Never `plugins.enabled`. Never also `mcp_servers.wax`; do not also register generic MCP or this generic skill. Call `wax_remember` / `wax_recall` / `wax_stats` with no Wax UUID. | | OpenClaw | HTTP + memory plugin + paste the SOUL.md stanza into workspace `SOUL.md` (replace existing `## Memory (Wax)`) | | Grok CLI | `wax-cli mcp install --hosts grok` prints the stdio block (writes it with `--write-toml-config`); daily: HTTP URL `http://127.0.0.1:3000/mcp`. Do not use `GROK_CONFIG` / `GROK_CONFIG_PATH` to retarget Wax. Isolated labs: project `.grok/config.toml` + `--leader-socket` (or `--no-leader` / `GROK_HOME`) — see `Resources/docs/wax-mcp-hosts.md`. | | OpenCode | `wax-cli mcp install --hosts opencode` merges the stdio entry automatically (JSONC stays manual); manual: HTTP URL in `opencode.json` + paste `references/project-rules.md` | | Muse Code | `wax-cli mcp install` registers Muse automatically (unless `--skip-muse`); manual: `mcp_servers.wax` in `~/.config/muse/settings.json` (`schema_version: 1`): stdio `wax-cli mcp serve` when solo, shared `http://127.0.0.1:3000/mcp` with two or more clients + paste the AGENTS.md fence from `references/project-rules.md` | | Other | HTTP URL + paste the AGENTS.md fence from `references/project-rules.md` |

Optional: `wax-cli mcp install --write-host-rule PATH` writes the generated host-rule blob. It never overwrites a host rule unless that flag is set.

Two or more clients must share **one** HTTP server on `http://127.0.0.1:3000/mcp`. Snippets and smoke test: `Resources/docs/wax-mcp-hosts.md`.

The npm launcher serves MCP. It does **not** implement `mcp install --scope`.

Diagnose / recover

npx -y waxmcp@latest doctor
npx -y waxmcp@latest vector-health

`vector-health` is green only when both `vectorSearchEnabled` and `queryEmbeddingAvailable` are true. After `install`, restart HTTP if it is already a service — do not start a second writer:

launchctl kickstart -k "gui/$(id -u)/ai.wax.mcp-http"
# or: ~/.local/share/waxmcp/bin/start-wax-mcp-http.sh

Native Hermes, after `install-hermes-plugin` from this tree:

hermes wax-memory doctor
hermes plugins doctor wax-memory

`hermes wax-memory` registers `status`, `doctor`, and `config` only. If those doctors fail to register or import, reinstall the plugin. Do not add `wax-memory` to `plugins.enabled`.

# Claude skill (if wax-cli install did not auto-register)
claude install-skill ~/.local/share/waxmcp/skills/wax-mcp
# or from source
claude install-skill https://github.com/christopherkarani/Wax/tree/main/Resources/skills/public/wax-mcp

References

• `references/project-rules.md` — pasteable project instruction block
• Repo setup doc: `Resources/docs/wax-mcp-setup.md`