ai-assistant: docs/proposals: Add backend-and-mcp architecture proposal#889
Open
illume wants to merge 1 commit into
Open
ai-assistant: docs/proposals: Add backend-and-mcp architecture proposal#889illume wants to merge 1 commit into
illume wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an architecture proposal documenting how the ai-assistant should support backend-mediated command execution and MCP tooling across Desktop, Headless, In-cluster, and CLI modes, with an emphasis on a shared permission/consent security model.
Changes:
- Introduces a proposal for HTTP-backed
runCommandexecution via the Go backend (incl. streaming and consent). - Proposes a unified MCP execution model across runtime modes (stdio vs HTTP/SSE/streamable HTTP), including Helm-based configuration for in-cluster.
- Proposes consent and terminal-access mechanisms (COOP popup / terminal prompt / Helm pre-approval; WebSocket terminal streaming).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| | Layer | Electron (today) | Backend (proposed) | | ||
| |-------|-------------------|-------------------| | ||
| | **Plugin isolation** | Random permission secrets per command, distributed via IPC | Same secrets, distributed via `GET /api/v1/run-command/secrets` | |
| | Layer | Electron (today) | Backend (proposed) | | ||
| |-------|-------------------|-------------------| | ||
| | **Plugin isolation** | Random permission secrets per command, distributed via IPC | Same secrets, distributed via `GET /api/v1/run-command/secrets` | | ||
| | **Caller auth** | IPC (implicit — only renderer can call) | `X-HEADLAMP_BACKEND-TOKEN` header (headless) or Bearer/OIDC (in-cluster) | |
| |----------|---------|-----| | ||
| | In-page React dialog | ❌ | Plugin can call API directly, DOM-manipulate the dialog, or override `window.fetch` | | ||
| | Same-origin popup (no COOP) | ❌ | Same origin = plugin has full DOM access to popup | | ||
| | Cross-origin popup (different port) | ✅ | SOP isolates; popup immune to clickjacking | |
| | Server-side nonce | Direct POST to approve endpoint | | ||
| | SW registration blocking | Service Worker interception | | ||
|
|
||
| **Proof of Concept:** See [`consent-poc/`](./consent-poc/) — 159 Playwright tests across Chromium, Firefox, and WebKit validating all security layers plus a deliberately-vulnerable twin as negative control. |
|
|
||
| | Threat | Category | Mitigation | | ||
| |--------|----------|------------| | ||
| | Unauthenticated MCP call | Spoofing | Bearer/OIDC (in-cluster) or `HEADLAMP_BACKEND_TOKEN` (headless) | |
Comment on lines
+5
to
+11
| Three related proposals for extending Headlamp's command/tool execution beyond Electron: | ||
|
|
||
| 1. **Backend runCommand** — HTTP-based `runCommand` through the Go backend (headless + in-cluster) | ||
| 2. **MCP across all modes** — MCP tool execution in desktop, headless, in-cluster, and CLI | ||
| 3. **Terminal access** — Interactive shell via WebSocket on the backend server | ||
|
|
||
| All three share a common security model: permission secrets, backend token auth, and user consent. |
illume
force-pushed
the
docs/ai-assistant-backend-and-mcp-proposal
branch
2 times, most recently
from
965ab81 to
feda767
Compare
…hitecture proposal Architecture proposal for the backend integration layer. Covers how LangChain sessions, MCP server connections, and provider configuration are managed across the three execution contexts (browser extension, Electron desktop app, headless CLI): - The `ai-common` package provides the platform-agnostic session and tool layer. - In Electron, MCP servers are spawned in the main process; the renderer communicates via `window.desktopApi.mcp` IPC. - In the CLI, MCP servers are spawned as child processes of the Node runtime using the same `MCPClientCore` interface. - Provider configuration is stored in `ProviderConfigManager` (localStorage in browser, JSON file in CLI) and shared with `LangChainManager` at session start. Includes sequence diagrams for the session lifecycle, IPC call patterns, and the consent/approval flow. Signed-off-by: René Dudfield <renedudfield@microsoft.com> Co-authored-by: Ashu Ghildiyal <aghildiyal@microsoft.com> Signed-off-by: Ashu Ghildiyal <aghildiyal@microsoft.com>
illume
force-pushed
the
docs/ai-assistant-backend-and-mcp-proposal
branch
from
feda767 to
f23e10a
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/proposals/backend-and-mcp.md— an architecture proposal for the backend integration layer: how the AI assistant manages LangChain sessions, MCP server connections, and provider configuration in both browser and CLI contexts.Assisted by Copilot.
Part of the ai-assistant design proposals.