Skip to content

Instantly share code, notes, and snippets.

@unxmaal

unxmaal/claude_mcm_setup.md

Created May 16, 2026 13:32
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save unxmaal/cd5196b7b14f2245ddfa55f14c9251f8 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save unxmaal/cd5196b7b14f2245ddfa55f14c9251f8 to your computer and use it in GitHub Desktop.
Download ZIP
Claude and mcm-engine setup
Raw
claude_mcm_setup.md

Setting up Claude Code with mcm-engine on macOS

Step-by-step setup guide. Expect 15–25 minutes if you copy/paste in order.

You'll end up with:

  1. Homebrew — macOS package manager (installs developer tools from the Terminal).
  2. Claude Code — Anthropic's command-line AI assistant.
  3. uv — a fast Python package + tool manager.
  4. mcm-engine — an MCP server that gives Claude long-term memory (rules, prior findings, error history) across sessions.
  5. A configured project root at ~/projects. This is the directory Claude treats as your workspace; all the config files live here.

Throughout this doc, ~ means your home directory (/Users/<your-username>). The shell expands it automatically. You can paste commands literally — don't type your real home path.

Step 0 — Open Terminal

Cmd+Space → type Terminal → Enter. (iTerm2 works too if you have it.) Every command below gets pasted into this window.

If you're new to the Terminal: paste a command, press Enter, wait for the prompt (% or $) to come back, then paste the next one.

Step 1 — Install Homebrew

Paste this and press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installer will ask for your Mac password (it needs to put files in protected locations). Type your password and press Enter — characters won't appear as you type, that's normal.

When it finishes, it prints two lines telling you to run something like this (for Apple Silicon Macs, M1 onward):

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Run those exact lines as the installer instructs you. They put brew on your PATH so future Terminal sessions can find it.

Intel Mac? The installer will give you /usr/local/bin/brew instead of /opt/homebrew/bin/brew. Use whatever it prints — don't substitute.

Verify it worked:

brew --version

You should see Homebrew 4.x.x.

Step 2 — Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

This places the claude command in ~/.local/bin. Make sure that directory is on your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

claude --version

If you see a version number, you're good. The first time you run claude (without a flag), it'll walk you through signing in to your Anthropic account.

Step 3 — Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

uv installs itself into ~/.local/bin (same place Claude Code uses), so your PATH is already set from Step 2.

Verify:

uv --version

Step 4 — Clone mcm-engine

We'll mirror the GitHub URL structure under ~/projects so source clones stay organized: ~/projects/<host>/<org>/<repo>.

mkdir -p ~/projects/github/unxmaal
cd ~/projects/github/unxmaal
git clone https://github.com/unxmaal/mcm-engine.git

You now have the repo at ~/projects/github/unxmaal/mcm-engine. Future clones follow the same pattern — git clone https://github.com/<org>/<repo>.git into ~/projects/github/<org>/.

If git prompts you to install developer tools the first time, click Install and re-run the git clone after it finishes.

Step 5 — Create your Claude project root

mkdir -p ~/projects/.claude
mkdir -p ~/projects/rules
cd ~/projects

~/projects is the directory Claude treats as your workspace. The rules/ subdirectory is where your own knowledge files (markdown notes about how to do things in your projects) will live — mcm-engine indexes them and makes them searchable. Empty for now is fine.

Step 6 — Create a uv venv in ~/projects and activate it

cd ~/projects
uv venv
source .venv/bin/activate

You'll see (projects) (or similar) appear at the start of your shell prompt — that means the venv is active.

What this venv is for: It's where mcm-engine itself will be installed in the next step. Claude launches mcm-engine via uv run from ~/projects, which automatically picks up this .venv — so you don't have to activate it before running Claude in day-to-day use.

Note: When you open a new Terminal window later, this venv won't auto-activate. Run source ~/projects/.venv/bin/activate if you want to invoke mcm-engine directly from the shell. For just running claude, no activation needed.

Step 7 — Install mcm-engine into the venv

Make sure the venv from Step 6 is still active — your prompt should show (projects) at the front. If it's not, re-activate:

cd ~/projects
source .venv/bin/activate

Then install mcm-engine from the cloned source into the venv:

uv pip install ~/projects/github/unxmaal/mcm-engine

This places the mcm-engine command at ~/projects/.venv/bin/mcm-engine. Verify (while the venv is still active):

mcm-engine --help

If that prints help text, the install worked. Note that mcm-engine is only on your PATH while the venv is active — Claude will use uv run to invoke it without needing activation (see the .mcp.json in the next step).

Step 8 — Drop in the four config files

Make sure you're in ~/projects (run cd ~/projects if not). Create each of these files with the contents shown below.

The easiest way to create each file:

  1. Run nano <filename> (e.g. nano CLAUDE.md).
  2. Paste the contents.
  3. Press Ctrl+O, then Enter, to save.
  4. Press Ctrl+X to exit.

~/projects/CLAUDE.md

This is the system-level instruction set Claude reads when it starts a session in this directory. It tells Claude how to use mcm-engine.

# Claude Instructions

## INVARIANTS (non-negotiable)

These are hard rules. Violating any of these is a session failure.

- **MCP TOOLS BEFORE EVERYTHING**: `search` first. `search` everything before you do it so you don't flail around. `report_error` before attempting any fix. `search` before inventing any technique. NO EXCEPTIONS. Do not skip these because you think you already know the answer. The MCP nudge system tracks tool calls — warning at turn 3, blocking at turn 6+ if no MCP search/report_error call has been made.
- **FIXES GO INTO RULES**: Every confirmed fix or pattern gets stored. If you edit a file during debugging, that fix MUST end up in a rule file (`rules/`) via `add_rule`. Otherwise it will be re-discovered next session.
- **`add_rule` IMMEDIATELY AFTER FIX CONFIRMED**: The moment a build/test passes after a fix, call `add_rule` with `file_path` pointing to the authoritative rule file. Do not batch to session end — context pressure causes deferred `add_rule` calls to be dropped.
- **DB IS CACHE, FILES ARE AUTHORITATIVE**: Rule files in `rules/` are the source of truth. `add_rule` must include `file_path`.
- **DELEGATE LONG DEBUGS**: >2 failed fix attempts for the same error → stop and spawn a sub-agent. Pass it the error text, file paths, and tell it to use MCP tools first. Never let debug trace flood parent context.
- **REDIRECT BUILD OUTPUT**: Never let output flood context. Log to file. Use sub-agents for reading large logs.

---

## Session Protocol

1. Call `session_start` MCP tool
2. Work — use MCP tools for every error, every symbol, every lookup
3. `add_rule` immediately after each confirmed fix
4. Call `session_handoff` MCP tool before ending

---

## MCP Tool Quick Reference

These are your primary interface. Use them before reading files, before grepping, before guessing.

| When | Tool | What it does |
|------|------|--------------|
| Hit any error | `report_error` | Logs error AND auto-searches rules + errors in one call |
| Need to look something up | `search` | FTS5 search across all knowledge, rules, errors, negative knowledge |
| Confirmed a fix | `add_rule` | Stores the fix with `file_path` to authoritative rule file |
| Learned something | `add_knowledge` | Stores findings, decisions, insights |
| Found a dead end | `add_negative` | Stores anti-patterns so they're never repeated |
| Re-index rule files | `sync_rules` | Picks up new/changed/deleted `.md` files in `rules/` |
| Session start | `session_start` | Context summary, last handoff, active tasks |
| Session end | `session_handoff` | Snapshot state for next session |


## Context Management

**Tuned for 1M context windows.** Sessions can safely run 400+ turns. Focus is on knowledge capture quality, not checkpoint frequency.

- **Sub-agents for investigation**: Any task requiring >200 lines of output gets a sub-agent. Sub-agent investigates and returns a concise summary; parent applies the fix.
- **Re-orientation check every 8 tool calls**: Am I using MCP tools? Am I freestyling a fix that's probably already documented? Have I stored my findings? If unsure, call `session_start`.
- **Store knowledge continuously**: `report_error` when you hit it → fix it → build passes → `add_rule` right then. Don't accumulate findings to store later.
- **Checkpoint at 30 turns**: `save_snapshot` or `session_handoff` to reset the checkpoint counter.

**MCP enforcement thresholds** (configurable in `mcm-engine.yaml`):
- Store reminder: 6 turns
- Checkpoint: 30 turns
- Mandatory stop: 320 turns
- Nudge escalation: 2 ignores → blocking
- MCP-first enforcement: warning at turn 3, blocks if no search/report_error called

~/projects/mcm-engine.yaml

The mcm-engine server's config. Change project_name to whatever you want this workspace called — it shows up in session start messages.

project_name: josh
db_path: .claude/knowledge.db
rules_path: rules/
plugins: []
nudges:
  # Tuned for 1M context — sessions can safely run 400+ turns.
  # Compaction/handoff thresholds are relaxed; enforcement thresholds are tightened.
  store_reminder_turns: 6
  checkpoint_turns: 30
  mandatory_stop_turns: 320
  hyper_focus_threshold: 8
  rules_check_interval: 4
  # Block tool calls (return error) after mandatory_stop + grace without checkpoint.
  mandatory_stop_blocking: true
  mandatory_stop_grace: 10
  # After N ignored nudges of the same type, escalate to blocking.
  nudge_escalation_threshold: 2

server_name: mcm-engine

server_instructions: |

  BEHAVIORAL MANDATES (non-negotiable):

  0. Do not be lazy. Do not cheat. Focus on correctness and precision, not the "quickest way" to solve problems. Carefully examine any potential shortcut and consider how it will impact downstream work.

  1. MUST call `report_error` BEFORE attempting manual fixes for any build/link/runtime error.
     It logs the error AND auto-searches rules and errors in one call.

  2. MUST call `add_rule` IMMEDIATELY after confirming a fix works (build passes, test passes).
     Do NOT defer add_rule calls to session end — context pressure causes them to be dropped.
     Pattern: report_error when you hit it -> fix it -> build passes -> add_rule RIGHT THEN.

  3. MUST delegate to a sub-agent after 2 failed fix attempts for the same error.
     Long debug sessions destroy parent context.

  4. DB is CACHE, files are AUTHORITATIVE. Rule files (rules/**/*.md) are the source of truth.
     When using add_rule, provide file_path pointing to the authoritative rule file.

  Tool quick reference:
  - `search` (or `knowledge_query`): Search rules, knowledge, errors
  - `report_error`: Log error + auto-search for fixes (THE KILLER FEATURE)
  - `add_knowledge` (or `report_finding`): Store findings/decisions/insights
  - `add_negative`: Store anti-patterns and dead ends
  - `add_rule`: Create/index rule after fixing a problem
  - `sync_rules`: Bulk re-index all .md files in rules/
  - `session_start`: Initialize session with context
  - `session_handoff`: Snapshot state for next session

~/projects/.mcp.json

Tells Claude Code to launch the mcm-engine MCP server when you start a session here. uv run invokes mcm-engine inside ~/projects/.venv automatically, so you don't have to activate the venv before running claude.

{
  "mcpServers": {
    "mcm-engine": {
      "command": "uv",
      "args": ["run", "mcm-engine", "run"]
    }
  }
}

~/projects/.claude/settings.local.json

Project-level Claude Code settings. The enableAllProjectMcpServers line auto-approves the mcm-engine MCP server (otherwise Claude prompts you every session). The permissions.allow list pre-approves the mcm-engine tools so Claude doesn't ask permission every time it calls one.

{
  "permissions": {
    "allow": [
      "mcp__mcm-engine__session_start",
      "mcp__mcm-engine__session_handoff",
      "mcp__mcm-engine__search",
      "mcp__mcm-engine__add_knowledge",
      "mcp__mcm-engine__add_negative",
      "mcp__mcm-engine__add_rule",
      "mcp__mcm-engine__report_error",
      "mcp__mcm-engine__read_rule",
      "mcp__mcm-engine__sync_rules",
      "mcp__mcm-engine__get_resume_context",
      "mcp__mcm-engine__save_snapshot",
      "mcp__mcm-engine__pin_item",
      "mcp__mcm-engine__unpin_item",
      "mcp__mcm-engine__reinforce_knowledge",
      "mcp__mcm-engine__reinforce_rule",
      "mcp__mcm-engine__promote_to_rule",
      "mcp__mcm-engine__link_knowledge",
      "mcp__mcm-engine__get_related"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "mcm-engine"
  ]
}

Step 9 — Start Claude

cd ~/projects
claude

Inside the Claude prompt, type:

/mcp

You should see mcm-engine listed as connected. If yes — you're done.

Quick smoke test: type please call session_start on mcm-engine and Claude should call the tool and show counts (all zeros on a fresh setup, which is correct).

File map

After setup, ~/projects should look like:

~/projects/
├── .claude/
│   ├── knowledge.db          (created automatically on first session_start)
│   └── settings.local.json
├── .mcp.json
├── .venv/                    (created by uv venv)
├── CLAUDE.md
├── mcm-engine.yaml
├── rules/                    (your own rule .md files go here)
└── github/
    └── unxmaal/
        └── mcm-engine/       (cloned source — leave it alone after installing)

Future repos you clone follow the same ~/projects/<host>/<org>/<repo> pattern (e.g. ~/projects/github/anthropics/claude-code, ~/projects/gitlab/<org>/<repo>).

To update mcm-engine later:

cd ~/projects/github/unxmaal/mcm-engine
git pull
cd ~/projects
source .venv/bin/activate
uv pip install --force-reinstall ~/projects/github/unxmaal/mcm-engine

Day-to-day usage

  • Start a session: cd ~/projects && claude. Claude auto-loads CLAUDE.md and launches mcm-engine.
  • Write rules: drop markdown files under ~/projects/rules/<category>/<rule-name>.md. Ask Claude to call sync_rules (or it'll happen on its own) to index them — searchable thereafter.
  • End a session well: ask Claude to call session_handoff before you close — it snapshots state so the next session resumes cleanly.

Troubleshooting

mcm-engine: command not found (running it manually) — The venv isn't active. Run source ~/projects/.venv/bin/activate, then try again. Or invoke without activation via uv run mcm-engine --help from inside ~/projects.

Claude doesn't show mcm-engine in /mcp — Make sure .mcp.json is in ~/projects (not your home directory), and you ran claude from ~/projects. Claude looks for .mcp.json in the current directory.

Claude reports the mcm-engine server failed to start — From ~/projects, run uv run mcm-engine --help to reproduce what Claude is doing. Common causes: (1) ~/projects/.venv doesn't exist — re-run Steps 6–7. (2) uv isn't on PATH for GUI processes — quit Terminal entirely (Cmd+Q) and reopen, GUI-launched processes inherit a stale PATH otherwise. (3) mcm-engine wasn't installed into the venv — re-run uv pip install ~/projects/github/unxmaal/mcm-engine with the venv active.

Homebrew install failed with "command line tools" error — Run xcode-select --install, click Install in the dialog, wait for it to finish, then re-run the Homebrew installer.

Intel Mac (not Apple Silicon) — Wherever you see /opt/homebrew/..., substitute /usr/local/.... The Homebrew installer prints the right path for your machine in Step 1 — copy from there, don't guess.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment