feat(setup): define Claude Desktop/Cowork MCPB integration contract

[gaduviera]

📋 Pre-flight Checks

• I have searched existing issues and this is not a duplicate
• I understand this issue needs status:approved before a PR can be opened

🔍 Problem Description

Engram already exposes a local MCP stdio server and provides first-class setup flows for Claude Code, OpenCode, Pi, Gemini CLI, and Codex. Claude Desktop also supports local MCP servers through MCP Bundles (.mcpb, formerly DXT), including use from regular Claude chats and Cowork spaces, but Engram currently has no documented or generated installation artifact for that host.

Today a Claude Desktop user must manually edit host configuration or build a machine-specific MCPB. That creates several problems:

• users must understand the MCP transport and Claude Desktop configuration internals;
• absolute binary paths are easy to get wrong or become stale after upgrades;
• there is no explicit contract describing what Engram owns versus what Claude Desktop owns;
• the Claude Code plugin and Claude Desktop integration can be confused even though their capabilities differ significantly.

A local proof of concept confirmed that Claude Desktop/Cowork can successfully use the existing Engram MCP server with engram mcp --tools=agent. PR #468 explored an implementation, but was closed so the setup and packaging contract could be approved first. This issue is that design proposal.

💡 Proposed Solution

Add an explicit Claude Desktop setup target:

engram setup claude-desktop

The command would generate an installable MCPB at a stable Engram-owned location:

~/.engram/mcpb/engram-claude-desktop.mcpb

The user would then open the file with Claude Desktop or install it through Claude Desktop's Extensions settings.

Intended Claude Desktop contract

The generated bundle registers one local stdio MCP server that launches Engram with the agent-facing tool profile:

<resolved-engram-command> mcp --tools=agent

Expected behavior:

• Engram memory tools become available in regular Claude Desktop chats and Cowork spaces.
• The bundle uses --tools=agent; admin tools are not exposed by default.
• The setup command is idempotent: rerunning it replaces/regenerates the same bundle.
• The command prints the generated path and installation/restart instructions.
• If the Engram launcher location changes, rerunning setup repairs the bundle.
• The bundle contains no database, observations, cloud token, credentials, or user conversation data.

Ownership boundary

Engram owns:

• ~/.engram/mcpb/engram-claude-desktop.mcpb;
• the generated MCPB manifest and its Engram launch arguments;
• validation that the bundle is structurally valid;
• documentation explaining installation, regeneration, limitations, and removal.

Claude Desktop owns:

• importing/installing the MCPB;
• its internal extension registry and copied extension files;
• MCP process lifecycle, permissions, enable/disable state, and UI;
• removal of the installed extension from Claude Desktop.

The setup command should not edit claude_desktop_config.json, automatically install the extension, restart Claude Desktop, or modify other Claude Desktop state. This keeps the integration incremental and avoids taking ownership of undocumented host internals.

Binary resolution and upgrades

The generated manifest needs a command that Claude Desktop can launch outside an interactive shell. The implementation should reuse Engram's approved stable-command resolution policy rather than blindly embedding a versioned package-manager path. In particular, it should remain compatible with the Homebrew upgrade-path work discussed in #498.

If no stable executable command can be resolved, setup should fail with a clear message rather than emit a bundle known to be broken.

Relationship to existing setup flows

• Claude Code plugin: remains the richer integration. It provides hooks, skills, session lifecycle behavior, Memory Protocol guidance, and compaction recovery.
• Claude Desktop MCPB: is intentionally a thin MCP transport adapter. It exposes existing Engram MCP tools but does not claim Claude Code hook/skill behavior.
• Other engram setup targets: remain unchanged. Claude Desktop is added as another explicit host adapter under internal/setup and the setup CLI/TUI listing.
• Cloud: no automatic cloud configuration, enrollment, authentication, or token embedding is introduced. The MCP server continues using the user's existing Engram configuration.

Proposed implementation surface after approval

A focused PR would be limited to:

• internal/setup: MCPB manifest generation and archive writing;
• cmd/engram: target registration and post-install instructions;
• tests for path selection, manifest fields, archive contents, idempotent regeneration, and error handling;
• README/agent setup/plugin documentation clarifying the capability boundary.

It would not add a second MCP server implementation or change memory/store semantics.

Acceptance criteria

• engram setup claude-desktop generates a valid .mcpb on supported desktop platforms.
• The manifest launches Engram with exactly mcp --tools=agent.
• Generation is deterministic/idempotent and does not modify Claude Desktop configuration.
• No secrets or memory data are included in the archive.
• The generated bundle is recognized by the official MCPB tooling and installs successfully in Claude Desktop.
• Documentation distinguishes Claude Desktop MCP access from the Claude Code lifecycle plugin.
• Tests cover Windows paths with spaces and stable command behavior across package-manager upgrades.

📦 Affected Area

CLI (commands, flags)

🔄 Alternatives Considered

1. Document manual claude_desktop_config.json editing only.

   • Smaller implementation, but preserves the main usability and path-resolution problems and relies on host internals.

2. Automatically edit Claude Desktop configuration.

   • Avoids a manual install step, but makes Engram responsible for another application's private configuration and merge behavior. This is a larger, riskier ownership contract.

3. Ship one universal prebuilt MCPB containing the Engram binary.

   • More portable, but duplicates release artifacts, complicates signing and multi-platform packaging, increases bundle size, and creates a second update channel for Engram.

4. Use the Claude Code plugin in Claude Desktop.

   • Not equivalent: Claude Desktop does not provide the same hook/skill lifecycle as Claude Code.

5. Keep the external proof-of-concept only.

   • Works for one machine, but hardcoded paths and no upstream contract make it unsuitable for normal users.

📎 Additional Context

• Prior exploratory implementation: feat(setup): add Claude Desktop MCPB bundle #468
• Maintainer guidance on that PR explicitly requested an approved design issue covering the Claude Desktop contract, owned files, and fit beside existing setup flows.
• MCPB documentation: https://github.com/modelcontextprotocol/mcpb
• The proof of concept was validated on Claude Desktop/Cowork for Windows and successfully exposed the existing Engram agent-profile MCP tools.

Open design questions for maintainers:

1. Is ~/.engram/mcpb/ the preferred Engram-owned output location, or should generated integration artifacts live elsewhere?
2. Should the first approved version target all MCPB-supported desktop platforms, or start with Windows/macOS where Claude Desktop is most commonly installed?
3. Should setup only generate the bundle, as proposed, or may it optionally invoke the host installer in a future separate change?
4. Is engram setup claude-desktop the preferred target name, or should the host be named claude-cowork/claude-desktop-mcpb?