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

[ch-liuzhide]

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 <client>" 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 -- <abs path> (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 <client> 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 <client>" 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 <client> 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 <client> install) or a verified absolute-path config snippet — and the "Install in <client>" 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: docs(integrations): copy-paste "connect in 10 lines" recipes for LlamaIndex / CrewAI / AutoGen / LangGraph #29 (copy-paste framework recipes, S3) — complementary docs effort.

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