afx-team · KevinLi0w0 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
      3. Merge to main — publish.yml ships to PyPI on the pyproject.toml change
         and tags the release. -->
 
+## [Unreleased]
+
+### Added
+
+- **Per-client MCP installers**: `hebb gemini install`, `hebb goose install`,
+  `hebb opencode install` (with `--scope project|user`), and `hebb amp install`
+  (with `--scope project|user`) register the Hebb Mind MCP server in each
+  client's config file. Each has a matching `uninstall` command. All installers
+  resolve the absolute `hebb-mcp` path via `hebb_mcp_command()`, are idempotent,
+  preserve unrelated config entries, and use atomic writes.
+- **S1 command-drift CI guard** (`tests/unit/test_command_drift.py`): asserts
+  every `hebb` command referenced in MCP integration docs, generated hook
+  configs, and the `hebb-mcp` entrypoint resolves to a registered Click command
+  or importable module.
+
+### Documentation
+
+- Expanded MCP integration guide (`repo_pages/guide/mcp-integration.md` + zh
+  mirror) from 4 clients to a 19-client quick-connect matrix covering Claude
+  Code, Codex, Amp, Cline, Claude Desktop, Copilot, Cursor, Gemini CLI, Goose,
+  Kiro, LM Studio, opencode, VS Code, Warp, Windsurf, and UI-only clients
+  (Antigravity, Factory, Junie, Qodo Gen). Each entry includes the exact config
+  file path, format, and absolute-path guidance.
+
 ## [0.3.0] - 2026-06-29
 
 ### Added

diff --git a/pyproject.toml b/pyproject.toml
@@ -41,7 +41,7 @@ dependencies = [
     "httpx>=0.27.0",
     "PyJWT>=2.8.0",
     "networkx>=3.1",
-    "mcp>=1.0.0",
+    "mcp>=1.0.0,<2.0.0",
     # Repairs malformed LLM JSON (doubled braces, truncation, trailing commas).
     # Pure-Python, MIT, no mandatory transitive deps.
     "json-repair>=0.30.0",

diff --git a/repo_pages/guide/mcp-integration.md b/repo_pages/guide/mcp-integration.md
@@ -1,10 +1,10 @@
 ---
-description: "Connect Claude Code, Codex, Cursor, and Claude Desktop to long-term AI agent memory over MCP — write, recall via hybrid vector+keyword search, and consolidate."
+description: "Connect Claude Code, Codex, Cursor, Windsurf, VS Code, and 15+ MCP-compatible clients to long-term AI agent memory — write, recall via hybrid vector+keyword search, and consolidate."
 ---
 
 # MCP Integration
 
-Hebb Mind provides an MCP (Model Context Protocol) server that exposes memory operations as tools. Claude Code, Codex, Cursor, and other MCP-compatible clients can use it directly.
+Hebb Mind provides an MCP (Model Context Protocol) server that exposes memory operations as tools. Any MCP-compatible client can use it directly. Below is the full quick-connect matrix — find your client and paste the snippet.
 
 ## Prerequisites
 
@@ -24,27 +24,76 @@ hebb service install    # registers the background service (no admin by default)
 | `consolidate` | Trigger memory consolidation | none |
 | `ingest_conversation` | Ingest a conversation export (Claude Code JSONL / ChatGPT JSON / plain text) — auto-detects format, normalizes turns, stores each turn | `content`, `format_hint?`, `importance?` |
 
-## Configuration
-
-The MCP server automatically discovers the service address from `hebb.json`. For the common case (service running locally), no configuration is needed — just add the command.
+## Quick-Connect Matrix
 
 ::: tip Use the absolute path to `hebb-mcp`
-The snippets below show `command: "hebb-mcp"` for brevity, but a **bare** `hebb-mcp` can fail to launch under GUI-launched apps (Claude Desktop, Cursor) that don't inherit your shell `PATH` — the MCP server then silently never starts. Run `which hebb-mcp` (Windows: `where hebb-mcp`) and use the **absolute path** as the `command`. The `hebb claude-code install` / `hebb codex install` commands already do this for you.
+All snippets below use `/absolute/path/to/hebb-mcp` as a placeholder. A **bare** `hebb-mcp` can fail to launch under GUI-launched apps (Claude Desktop, Cursor, Windsurf, LM Studio, etc.) that don't inherit your shell `PATH`. Run `which hebb-mcp` (Windows: `where hebb-mcp`) and replace the placeholder with the real path. The `hebb claude-code install` / `hebb codex install` commands already resolve this for you.
 :::
 
-If the service runs on a remote host or non-default address, set `HEBB_URL`:
+If the Hebb Mind service runs on a remote host or non-default address, add an `env` block with `HEBB_URL`:
+
+```json
+"env": { "HEBB_URL": "http://192.168.1.100:8321" }
+```
+
+### Clients with first-class installers
+
+#### Claude Code
+
+```bash
+hebb claude-code install --scope user   # hooks + MCP, absolute path auto-resolved
+```
+
+MCP-only (project-level `.mcp.json` or global `~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
+```
+
+#### Codex
 
-### Claude Code
+```bash
+hebb codex install   # project MCP + lifecycle hooks (default)
+codex mcp list
+```
 
-Recommended:
+Native Codex command:
 
 ```bash
-hebb claude-code install --scope user
+codex mcp add hebb -- "$(which hebb-mcp)"
+```
+
+### Clients with config snippets
+
+#### Amp
+
+Amp CLI stores MCP servers in `.amp/settings.json` (project-scoped) or `~/.config/amp/settings.json` (global). Use the `amp mcp add` command:
+
+```bash
+amp mcp add hebb -- /absolute/path/to/hebb-mcp
+```
+
+Or edit `.amp/settings.json` directly:
+
+```json
+{
+  "amp.mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
 ```
 
-MCP-only:
+#### Claude Desktop
 
-Add to your project's `.mcp.json` (replace `/absolute/path/to/hebb-mcp` with the output of `which hebb-mcp`):
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`). Claude Desktop is a GUI app — the absolute path is required:
 
 ```json
 {
@@ -56,41 +105,163 @@ Add to your project's `.mcp.json` (replace `/absolute/path/to/hebb-mcp` with the
 }
 ```
 
-Or add globally in `~/.claude.json`.
+#### Cline
 
-If the service runs on a non-default address, set the URL explicitly:
+Cline stores MCP config at two locations depending on how you use it: `~/.cline/mcp.json` for the Cline CLI, or the VS Code extension's MCP settings file (open via Cline panel → MCP Servers icon → Configure tab → Configure MCP Servers). Add:
 
 ```json
 {
   "mcpServers": {
     "hebb": {
       "command": "/absolute/path/to/hebb-mcp",
-      "env": {
-        "HEBB_URL": "http://192.168.1.100:8321"
-      }
+      "disabled": false,
+      "autoApprove": []
     }
   }
 }
 ```
 
-### Codex
+#### Copilot (VS Code)
 
-Recommended:
+Copilot in VS Code uses the same `.vscode/mcp.json` as VS Code native MCP (see below). Alternatively, use the command palette:
 
-```bash
-hebb codex install   # project MCP + lifecycle hooks (default)
-codex mcp list
+```text
+MCP: Add Server → stdio → name: hebb → command: /absolute/path/to/hebb-mcp
+```
+
+#### Cursor
+
+Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-scoped). Open via **Settings → Tools & MCP → New MCP Server**, or create the file:
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
 ```
 
-Native Codex command (pass the absolute path so it resolves regardless of how Codex is launched):
+#### Gemini CLI
+
+Edit `~/.gemini/settings.json` and add a `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
+```
+
+#### Goose
+
+Edit `~/.config/goose/config.yaml` (macOS/Linux) or `%APPDATA%\Block\goose\config\config.yaml` (Windows). Add under `extensions`:
+
+```yaml
+extensions:
+  hebb:
+    type: stdio
+    name: hebb
+    enabled: true
+    cmd: /absolute/path/to/hebb-mcp
+    args: []
+    envs: {}
+    timeout: 300
+```
+
+Or use the CLI wizard: `goose configure` → Add Extension → Stdio Extension → name: `hebb`, command: `/absolute/path/to/hebb-mcp`.
+
+#### Kiro
+
+Edit `.kiro/settings/mcp.json` (workspace) or `~/.kiro/settings/mcp.json` (user-level). Open via command palette: **Kiro: Open workspace MCP config**:
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp",
+      "args": [],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+#### LM Studio
+
+LM Studio follows Cursor's `mcp.json` notation. The config file is at `~/.lmstudio/mcp.json` (macOS/Linux) or `%USERPROFILE%\.lmstudio\mcp.json` (Windows). Open via the **Program** tab → **Install → Edit mcp.json**:
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
+```
+
+#### opencode
+
+Edit `opencode.json` (project-level) or `~/.config/opencode/opencode.json` (global). Add under the `mcp` key:
+
+```json
+{
+  "mcp": {
+    "hebb": {
+      "type": "local",
+      "command": ["/absolute/path/to/hebb-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Or use the CLI: `opencode mcp add` → name: `hebb`, type: `local`, command: `/absolute/path/to/hebb-mcp`.
+
+#### VS Code (native MCP)
+
+VS Code (1.102+) supports MCP natively. Edit `.vscode/mcp.json` (workspace) or open via command palette: **MCP: Open User Configuration**. Note: VS Code uses `"servers"` (not `"mcpServers"`):
+
+```json
+{
+  "servers": {
+    "hebb": {
+      "type": "stdio",
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
+```
+
+Or from the command line:
 
 ```bash
-codex mcp add hebb -- "$(which hebb-mcp)"
+code --add-mcp '{"name":"hebb","command":"/absolute/path/to/hebb-mcp"}'
+```
+
+#### Warp
+
+Warp supports MCP servers via Settings → MCP (GUI). Add a new stdio server:
+
+```json
+{
+  "mcpServers": {
+    "hebb": {
+      "command": "/absolute/path/to/hebb-mcp"
+    }
+  }
+}
 ```
 
-### Claude Desktop
+#### Windsurf
 
-Add to `claude_desktop_config.json` (typically at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). Claude Desktop is a GUI app, so the **absolute path** to `hebb-mcp` (from `which hebb-mcp`) is required:
+Edit `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows). Open via command palette: **Windsurf: Configure MCP Servers**:
 
 ```json
 {
@@ -102,9 +273,18 @@ Add to `claude_desktop_config.json` (typically at `~/Library/Application Support
 }
 ```
 
-### Cursor
+### Other clients
+
+The following clients support MCP but have UI-only or evolving configuration surfaces. Use the standard `mcpServers` JSON shape and paste it into the client's MCP settings UI:
+
+| Client | Config location | Notes |
+|--------|----------------|-------|
+| **Antigravity** | Editor MCP settings (UI) | Google's agentic IDE; configure via Settings → MCP |
+| **Factory** | Factory MCP config (UI) | Confirm format in Factory docs |
+| **Junie (JetBrains)** | IDE MCP settings (UI) | JetBrains AI assistant; Settings → Tools → MCP |
+| **Qodo Gen** | IDE plugin MCP config (UI) | VS Code extension; configure via plugin settings |
 
-Open **Settings → Features → MCP** and add (Cursor is a GUI app — use the absolute path from `which hebb-mcp`):
+For each, add:
 
 ```json
 {
@@ -119,7 +299,7 @@ Open **Settings → Features → MCP** and add (Cursor is a GUI app — use the
 ## How It Works
 
 ```
-Claude Code / Codex / Cursor
+Claude Code / Codex / Cursor / Windsurf / VS Code / ...
         │ (stdio)
         v
   hebb-mcp (MCP server)