# srbhptl39/mcp-superassistant architecture

> Architecture diagram of the GitHub repository srbhptl39/mcp-superassistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srbhptl39/mcp-superassistant
- Repository: https://github.com/srbhptl39/mcp-superassistant

## Overview

##### Project type and purpose
- This is a browser-based tool: a Chrome extension (“MCP SuperAssistant”) shipped from a monorepo.
- It injects a sidebar UI into various AI chat platforms (ChatGPT, Gemini, Perplexity, Grok, AIStudio, OpenRouter) to detect and execute MCP tool calls.
- It also includes a local-proxy “MCP SuperAssistant Proxy” to forward SSE calls to real MCP servers (CORS, health checks).

##### File structure
- Top-level:
- chrome-extension/ → extension manifest, background & content scripts, UI code, build config (Vite).
- pages/content/ → content-script React/Vite app that renders the sidebar in AI pages, plus pre-script engine.
- packages/ → reusable TS modules (dev-utils, env, hmr, i18n, module-manager, shared UI/hooks/utils, storage, tailwind-config, vite-config, zipper).
- root config: pnpm-workspace.yaml, turbo.json, tsconfig.json, build & CI workflows (.github), husky, eslint, prettier.

##### Key insights from README
- Extension detects MCP calls in AI responses → injects UI via content script.
- Uses SSE to communicate with a local proxy (npx @…/proxy) → forwards to actual MCP server.
- Built with Chrome-extension-boilerplate (React + Vite), TS, pnpm + turborepo.

##### Main components
A. Browser / AI Platform
- ChatGPT, Gemini, Perplexity, etc. (web pages).
B. Chrome Extension
1. Content Script (pages/content build output)
- Injects Sidebar UI (React)
- Detects tool calls in DOM
- Communicates with Background via chrome.runtime messaging
2. Background Script (chrome-extension/src/background)
- Holds connection to local proxy server via SSE/HTTP
- Forwards detected tool requests → local proxy
- Receives results → relays to Content Script
C. Local Proxy Server
- “MCP SuperAssistant Proxy” (npm package)
- SSE endpoint, CORS, health-checks
D. Actual MCP Server
- External Anthropic MCP endpoint
E. Monorepo Build System
- pnpm workspace + Turbo
- Packages (shared, ui, env, hmr, i18n…) feed into extension and content script builds
- Vite config from packages/vite-config
- Tailwind config from packages/tailwind-config

##### Relationships & interactions
1. User loads supported AI platform → content script injects sidebar UI.
2. User triggers tool execution → content script sends “execute” message to Background.
3. Background opens SSE/HTTP to Local Proxy.
4. Proxy forwards to Actual MCP Server → gets tool execution result.
5. Proxy streams results back via SSE → Background → Content Script.
6. Content Script inserts results back into AI chat DOM.
7. Under the hood, build tools (pnpm/Turbo) compile all packages + extension.

##### Architectural patterns & design principles
- Chrome Extension MVC: Content Script (View + Controller) ↔ Background (Model + Service)
- Monorepo with modular packages to maximize code reuse (env, i18n, storage, UI, dev-utils).
- HMR and watch plugins (packages/hmr) for rapid dev in both content script and extension.
- Config-as-code: shared tsconfig, eslint, prettier, tailwind across packages.
- Plugin architecture for adapters to multiple AI platforms (adapterRegistry in pages/content).

##### Relevant technologies & libraries
- TypeScript, React, Vite
- Chrome Extension Manifest v3, SSE, chrome.runtime messaging
- pnpm workspace, Turbo monorepo
- Tailwind CSS, postcss
- Rollup (for render_prescript)
- Packages: @srbhptl39/dev-utils, env, hmr, i18n, module-manager, shared, storage, ui, vite-config, tailwind-config, zipper

##### Diagramming recommendations
- Use clear labels: “Content Script”, “Background Script”, “Local Proxy Server”, “MCP Server”, “AI Platform Page”.
- content→background (chrome.runtime.sendMessage)
- background→proxy (HTTP/SSE)
- proxy→MCP server (HTTP)
- proxy→background (SSE)
- background→content (chrome.runtime.sendMessage)
- content→DOM injection
- Browser-side (blue)
- Extension scripts (orange)
- Local services (green)
- External services (gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Context
    AI["AI Platform Page"]:::browser
    CS["Content Script"]:::extension
    sidebar["Sidebar UI Components"]:::extension
    adaptersReg["Adapter Registry (adapterRegistry.ts)"]:::extension
    adaptersDir["Adapters Directory"]:::extension
    prescript["Pre-Script Engine"]:::extension
    BG["Background Script"]:::extension
    mcpclient["MCP Client Interfaces"]:::extension
    manifest["Manifest (manifest.ts)"]:::extension
    viteExt["Vite Config (vite.config.mts)"]:::extension

    %% Local and External Services
    Proxy["Local Proxy Server"]:::service
    MCP["Actual MCP Server"]:::external

    %% Monorepo Build System
    subgraph "Monorepo Workspace" 
        ws["pnpm-workspace.yaml"]:::build
        turbo["turbo.json"]:::build
        subgraph "Packages"
            devutils["@srbhptl39/dev-utils"]:::build
            env["packages/env"]:::build
            hmr["packages/hmr"]:::build
            i18n["packages/i18n"]:::build
            modmgr["packages/module-manager"]:::build
            shared["packages/shared"]:::build
            uiLib["packages/ui"]:::build
            storage["packages/storage"]:::build
            vitePkg["packages/vite-config"]:::build
            tailwind["packages/tailwind-config"]:::build
            zipper["packages/zipper"]:::build
        end
    end

    %% Data Flows
    AI -->|"Inject UI"| CS
    CS -->|"uses Sidebar UI"| sidebar
    CS -->|"uses Adapter Registry"| adaptersReg
    CS -->|"uses Adapters"| adaptersDir
    CS -->|"uses Pre-Script"| prescript
    CS -->|"sendMessage execute"| BG
    BG -->|"SSE/HTTP"| Proxy
    Proxy -->|"HTTP"| MCP
    Proxy -->|"SSE stream"| BG
    BG -->|"sendMessage result"| CS
    CS -->|"DOM injection"| AI

    %% Build System Flows
    ws --> Packages
    turbo --> Packages
    Packages --> CS
    Packages --> BG
    Packages --> viteExt

    %% Click Events
    click CS "https://github.com/srbhptl39/mcp-superassistant/tree/main/pages/content/src"
    click sidebar "https://github.com/srbhptl39/mcp-superassistant/tree/main/pages/content/src/components/sidebar"
    click adaptersReg "https://github.com/srbhptl39/mcp-superassistant/blob/main/pages/content/src/adapters/adapterRegistry.ts"
    click adaptersDir "https://github.com/srbhptl39/mcp-superassistant/tree/main/pages/content/src/adapters"
    click prescript "https://github.com/srbhptl39/mcp-superassistant/tree/main/pages/content/src/render_prescript"
    click BG "https://github.com/srbhptl39/mcp-superassistant/blob/main/chrome-extension/src/background/index.ts"
    click mcpclient "https://github.com/srbhptl39/mcp-superassistant/tree/main/chrome-extension/src/mcpclient"
    click manifest "https://github.com/srbhptl39/mcp-superassistant/blob/main/chrome-extension/manifest.ts"
    click viteExt "https://github.com/srbhptl39/mcp-superassistant/blob/main/chrome-extension/vite.config.mts"
    click ws "https://github.com/srbhptl39/mcp-superassistant/blob/main/pnpm-workspace.yaml"
    click turbo "https://github.com/srbhptl39/mcp-superassistant/blob/main/turbo.json"
    click devutils "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/dev-utils"
    click env "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/env"
    click hmr "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/hmr"
    click i18n "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/i18n"
    click modmgr "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/module-manager"
    click shared "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/shared"
    click uiLib "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/ui"
    click storage "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/storage"
    click vitePkg "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/vite-config"
    click tailwind "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/tailwind-config"
    click zipper "https://github.com/srbhptl39/mcp-superassistant/tree/main/packages/zipper"

    %% Styles
    classDef browser fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef extension fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef build fill:#DDA0DD,stroke:#333,stroke-width:1px
```
