feat(integrations): MCP quick-connect matrix across the agent ecosystem (per-client install)

## Context

**Goal axis: 易接入 (easy to integrate)** — the main lever for "easy for every agent to adopt." Most of today's agent ecosystem are MCP consumers, so for the large majority of clients, integration reduces to *registering the `hebb-mcp` stdio server in that client's config format*, ideally behind a one-shot command — exactly the pattern popular MCP servers ship as an "Install in ``" matrix (e.g. Context7). This is an **epic / tracking issue** to drive Hebb Mind to a complete, verified quick-connect matrix across the agent ecosystem.

This is the MCP-client quick-connect variant of the roadmap's "易接入" line. It is complementary to — not a duplicate of — the native-adapter epic (roadmap H1: LangChain/LlamaIndex/LangGraph/CrewAI/AutoGen serialization-level adapters) and the copy-paste recipe docs (#29, S3). Those wrap our REST/MCP for *framework SDKs*; this epic delivers *per-client MCP registration* for editor/agent shells. It directly executes the D1 "push MCP as the standard wedge + thin per-client install" bet from the roadmap.

## Current state (verified against tree)

The MCP server and the absolute-path install pattern already exist and are solid; only **two** clients have a first-class installer and **four** are documented.

- **MCP server entrypoint**: `hebb-mcp = "hebb.mcp.server:main"` — `pyproject.toml:65`. Implementation in `src/hebb/mcp/server.py`; stdio transport via `mcp.run(transport="stdio")` at `src/hebb/mcp/server.py:199`. Exposes four tools: `write_memory`, `search_memory`, `consolidate`, `ingest_conversation` (`src/hebb/mcp/server.py:54,90,141,160`). Also launchable as `hebb mcp serve` (`src/hebb/cli/commands/mcp_cmd.py:13`).
- **Absolute-path resolution (the hard constraint)**: `hebb_mcp_command()` resolves the absolute `hebb-mcp` path via `shutil.which`, falling back to `[sys.executable, "-m", "hebb.mcp.server"]` — `src/hebb/utils/cli_paths.py:37`. The module docstring (`src/hebb/utils/cli_paths.py:1`) documents *why*: GUI-launched apps / launchd / systemd / Task Scheduler do **not** inherit the shell PATH, and `pip install --user` lands scripts off-PATH.
- **Existing first-class installers** (the pattern to generalize):
- Claude Code — `hebb claude-code install`, group registered at `src/hebb/integrations/claude_code/cli.py:8`, logic in `src/hebb/integrations/claude_code/install.py:111`. **Bespoke, not plain MCP**: it installs hooks (`SessionStart`→recall, `UserPromptSubmit`→prompt, `Stop`→summary; `install.py:24-52`) *and* registers the MCP server, preferring `claude mcp add` and falling back to `settings.json` (`install.py:152-159,175`).
- Codex — `hebb codex install`, `src/hebb/integrations/codex/cli.py:26`. **Plain MCP**: `codex mcp remove`/`codex mcp add hebb -- ` (`cli.py:38-39`).
- Both are registered on the root CLI at `src/hebb/cli/main.py:38-39`.
- **Existing docs** cover only four clients, already with absolute-path guidance: Claude Code, Codex, Claude Desktop, Cursor — `repo_pages/guide/mcp-integration.md:37,76,91,105` (zh mirror exists: `repo_pages/zh/guide/mcp-integration.md`). The "use `which hebb-mcp`" tip is at `repo_pages/guide/mcp-integration.md:31`.
- **No quick-connect installer** exists for any client other than Claude Code and Codex, and no matrix/table enumerates the ecosystem.
- **The S1 command-drift CI guard does not yet exist.** It is a *proposed* item in the roadmap (assert every `hebb …` string in `plugin.json` / `.codex/hooks.json` / docs resolves to a registered Click command). `tests/unit/test_audit_hooks.py` is unrelated — it guards recall response-shape drift (F2), not command drift.

## Proposed approach

1. Generalize the existing installer pattern (`hebb codex install` is the clean template; `hebb claude-code install` is the bespoke template) into per-client `hebb install` commands where the client exposes a CLI or a stable on-disk config.
2. For clients without a CLI (GUI / UI-only config), ship a **documented, verified absolute-path config snippet** instead, always built from `which hebb-mcp` per the user-path-ownership constraint.
3. Render the whole ecosystem as an "Install in ``" matrix in `repo_pages/guide/mcp-integration.md` (+ zh mirror), one row per client.
4. Split per-client implementation into follow-up issues hanging off this epic; this issue tracks the matrix and the shared constraints.

## Client matrix (one task per client)

For each client, classify the MCP config mechanism and the planned delivery: **(a)** a `hebb install` command, **(b)** a documented absolute-path config snippet, or **(c)** not an MCP client → bespoke handling.

| Client | MCP config mechanism | Planned delivery |
|--------|----------------------|------------------|
| Amp | `amp` CLI / settings | (a) installer or (b) snippet — confirm CLI surface |
| Antigravity | editor MCP config (UI/JSON) | (b) snippet — confirm format |
| Claude Code | `claude mcp add` + hooks in `settings.json` | (c) bespoke — **shipped** (`hebb claude-code install`), hooks + MCP |
| Claude Desktop | `claude_desktop_config.json` (GUI) | (b) snippet — **documented**, formalize as matrix row |
| Cline | VS Code extension `cline_mcp_settings.json` | (b) snippet (consider (a)) |
| Codex | `codex mcp add` (TOML, global) | (a) **shipped** (`hebb codex install`), plain MCP |
| Copilot (VS Code) | `.vscode/mcp.json` / settings | (b) snippet — confirm GA config path |
| Cursor | `~/.cursor/mcp.json` / Settings → MCP (GUI) | (b) snippet — **documented**, formalize |
| Factory | Factory MCP config | (b) snippet — confirm format |
| Gemini CLI | `~/.gemini/settings.json` (`mcpServers`) | (a) installer or (b) snippet |
| Goose | `~/.config/goose/config.yaml` or `goose` CLI | (a) installer or (b) snippet |
| Junie (JetBrains) | IDE MCP settings (UI) | (b) snippet — confirm format |
| Kiro | `.kiro/settings/mcp.json` | (b) snippet |
| LM Studio | `mcp.json` (GUI) | (b) snippet |
| opencode | `opencode.json` / `~/.config/opencode` | (a) installer or (b) snippet |
| Qodo Gen | IDE plugin MCP config | (b) snippet — confirm format |
| VS Code | `.vscode/mcp.json` (native MCP, GUI) | (b) snippet (consider (a)) |
| Warp | Warp MCP settings (UI) | (b) snippet |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` (GUI) | (b) snippet |

Per-client tasks:

- [ ] Amp — confirm MCP mechanism; deliver (a) or (b)
- [ ] Antigravity — confirm MCP mechanism; deliver (b)
- [ ] Claude Code — **done** (bespoke hooks + MCP); add matrix row + verify still current
- [ ] Claude Desktop — formalize documented snippet into matrix row; verify absolute path
- [ ] Cline — deliver (b) snippet (evaluate (a) installer)
- [ ] Codex — **done** (plain MCP); add matrix row + verify still current
- [ ] Copilot — confirm GA config path; deliver (b)
- [ ] Cursor — formalize documented snippet into matrix row; verify absolute path
- [ ] Factory — confirm MCP mechanism; deliver (b)
- [ ] Gemini CLI — deliver (a) or (b)
- [ ] Goose — deliver (a) or (b)
- [ ] Junie — confirm MCP mechanism; deliver (b)
- [ ] Kiro — deliver (b) snippet
- [ ] LM Studio — deliver (b) snippet
- [ ] opencode — deliver (a) or (b)
- [ ] Qodo Gen — confirm MCP mechanism; deliver (b)
- [ ] VS Code — deliver (b) snippet (evaluate (a) installer)
- [ ] Warp — deliver (b) snippet
- [ ] Windsurf — deliver (b) snippet

## Acceptance criteria

- [ ] Every client above has **either** a one-command installer (`hebb install`) **or** a verified absolute-path config snippet — and the "Install in ``" matrix renders in `repo_pages/guide/mcp-integration.md` with EN + zh (`repo_pages/zh/guide/mcp-integration.md`) updated together.
- [ ] **Hard constraint (user-path-ownership):** every quick-connect command/snippet for a cross-process surface registers the **resolved absolute `hebb-mcp` path** (via `which hebb-mcp` / `where hebb-mcp` / `hebb_mcp_command()`), never a bare `hebb-mcp`. A bare name silently fails to launch under GUI apps / launchd / Task Scheduler that don't inherit the shell PATH.
- [ ] New per-client installers route absolute-path resolution through `hebb.utils.cli_paths.hebb_mcp_command()` and are idempotent (replace any prior `hebb` MCP entry on re-run), matching `codex/cli.py` and `claude_code/install.py`.
- [ ] Clients needing bespoke (non-plain-MCP) handling are called out explicitly; clients that are not MCP consumers are marked (c) with the rationale.
- [ ] The proposed **S1 command-drift CI guard** is created (or extended once it lands) to also cover any generated client config / snippet, asserting every emitted `hebb …` / `hebb-mcp` reference resolves to a registered Click command or the real entrypoint.
- [ ] Per-client follow-up issues are split off this epic and linked back here.

## Scope / out of scope

- **In scope:** registering the existing `hebb-mcp` stdio server (4 tools) into each client; per-client installers; absolute-path snippets; the EN/zh matrix; the CI guard coverage.
- **Out of scope:** the native serialization-level adapter matrix (roadmap H1 — LangChain/LlamaIndex/LangGraph/CrewAI/AutoGen), the JS/TS SDK (roadmap H2), and new MCP tools/capabilities. The D1 positioning bet ("MCP as standard + thin per-client install vs N native adapters") should be resolved in parallel, as it bounds how far installer automation goes vs documented snippets.

## References

- `reports/design/capability-gap-roadmap-2026-06-11.md` — item H1 (native adapter matrix), S3 (per-framework recipes), and the D1 "push MCP as the standard wedge + thin per-client install" bet that this epic executes.
- `reports/audit/core-system-audit-2026-06-07.md` — integration/distribution + absolute-path (launchd/GUI PATH) findings.
- `reports/audit/newuser-experience-audit-2026-06-08.md` — new-user onboarding / first-connect friction.
- Code: `src/hebb/mcp/server.py`, `src/hebb/integrations/codex/cli.py`, `src/hebb/integrations/claude_code/install.py`, `src/hebb/utils/cli_paths.py`, `repo_pages/guide/mcp-integration.md`.
- Related: #29 (copy-paste framework recipes, S3) — complementary docs effort.

Filed from the capability-gap roadmap (reports/design/capability-gap-roadmap-2026-06-11.md).