# shabib87/supernova-mcp-rag architecture

> Architecture diagram of the GitHub repository shabib87/supernova-mcp-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shabib87/supernova-mcp-rag
- Repository: https://github.com/shabib87/supernova-mcp-rag

## Overview

SuperNova MCP RAG Server lets a user search imaginary product documentation from an MCP client. Startup loads HTML documentation, extracts and chunks its text, then embeds the chunks into an in-memory vector store; the registered search tool queries that store and returns matching passages. The graph preserves the sampled entry point and helper modules alongside the documented indexing stages. Some library internals are represented from README documentation rather than inspected source.

Main entry points: [`mcp-rag-server/src/rag.ts`](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/rag.ts) (RAG pipeline), [`mcp-rag-server/src/mcp.ts`](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/mcp.ts) (MCP tool server), [`mcp-rag-server/src/index.ts`](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/index.ts) (Server entry), [`mcp-rag-server/src/helpers/getEnv.ts`](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/getEnv.ts) (Environment loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_entry["Server entry<br/>[index.ts]"]
  node_mcp["MCP tool server<br/>[mcp.ts]"]
end

subgraph group_indexing["Document Indexing"]
  node_rag["RAG pipeline<br/>[rag.ts]"]
  node_extract["HTML text extractor"]
  node_splitter["Text chunking"]
  node_embeddings["HF embeddings"]
  node_store[("Memory vector store")]
end

subgraph group_sources["Documentation Source"]
  node_html["SuperNova HTML docs"]
end

subgraph group_runtime["Runtime Helpers"]
  node_dirname["Path resolver<br/>[dirName.ts]"]
  node_env["Environment loader<br/>[getEnv.ts]"]
  node_console["Console redirect<br/>[redirectConsole.ts]"]
end

node_user(("Cursor user"))
node_hfapi["Hugging Face API"]

node_user -->|"asks via MCP"| node_mcp
node_entry -->|"starts"| node_mcp
node_entry -->|"loads"| node_console
node_mcp -->|"creates"| node_rag
node_mcp -->|"initializes"| node_rag
node_rag -->|"loads HTML"| node_html
node_rag -->|"extracts text"| node_extract
node_rag -->|"chunks text"| node_splitter
node_rag -->|"embeds chunks"| node_embeddings
node_embeddings -->|"requests embeddings"| node_hfapi
node_rag -->|"builds index"| node_store
node_mcp -->|"searches"| node_store
node_store -->|"returns matches"| node_mcp
node_mcp -->|"returns passages"| node_user
node_rag -->|"resolves path"| node_dirname
node_rag -->|"loads credentials"| node_env
node_env -->|"resolves env path"| node_dirname

click node_entry "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/index.ts"
click node_mcp "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/mcp.ts"
click node_rag "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/rag.ts"
click node_html "https://github.com/shabib87/supernova-mcp-rag/tree/main/docs/SuperNovaStorybook-Mobile-Swift"
click node_extract "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/extractTextFromHtml.ts"
click node_dirname "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/dirName.ts"
click node_env "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/getEnv.ts"
click node_console "https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/redirectConsole.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_mcp,node_user toneBlue
class node_rag,node_extract,node_splitter,node_embeddings,node_store toneAmber
class node_html,node_hfapi toneMint
class node_dirname,node_env,node_console toneRose
```

## Components

### MCP Interface

- [Server entry](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/index.ts): `mcp-rag-server/src/index.ts`
- [MCP tool server](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/mcp.ts): `mcp-rag-server/src/mcp.ts`

### Document Indexing

- [RAG pipeline](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/rag.ts): `mcp-rag-server/src/rag.ts`
- [HTML text extractor](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/extractTextFromHtml.ts): `mcp-rag-server/src/helpers/extractTextFromHtml.ts`
- **Text chunking**
- **HF embeddings**
- **Memory vector store**

### Documentation Source

- [SuperNova HTML docs](https://github.com/shabib87/supernova-mcp-rag/tree/main/docs/SuperNovaStorybook-Mobile-Swift): `docs/SuperNovaStorybook-Mobile-Swift`

### Runtime Helpers

- [Path resolver](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/dirName.ts): `mcp-rag-server/src/helpers/dirName.ts`
- [Environment loader](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/getEnv.ts): `mcp-rag-server/src/helpers/getEnv.ts`
- [Console redirect](https://github.com/shabib87/supernova-mcp-rag/blob/main/mcp-rag-server/src/helpers/redirectConsole.ts): `mcp-rag-server/src/helpers/redirectConsole.ts`

### Other components

- **Cursor user**
- **Hugging Face API**

## Connections

- Cursor user → MCP tool server: asks via MCP (evidence: `README.md`)
- Server entry → MCP tool server: starts (evidence: `mcp-rag-server/src/index.ts`)
- Server entry → Console redirect: loads (evidence: `mcp-rag-server/src/index.ts`)
- MCP tool server → RAG pipeline: creates (evidence: `mcp-rag-server/src/mcp.ts`)
- MCP tool server → RAG pipeline: initializes (evidence: `mcp-rag-server/src/mcp.ts`)
- RAG pipeline → SuperNova HTML docs: loads HTML (evidence: `mcp-rag-server/src/rag.ts`)
- RAG pipeline → HTML text extractor: extracts text (evidence: `mcp-rag-server/src/rag.ts`)
- RAG pipeline → Text chunking: chunks text (evidence: `README.md`)
- RAG pipeline → HF embeddings: embeds chunks (evidence: `README.md`)
- HF embeddings → Hugging Face API: requests embeddings (evidence: `README.md`)
- RAG pipeline → Memory vector store: builds index (evidence: `mcp-rag-server/src/rag.ts`)
- MCP tool server → Memory vector store: searches (evidence: `mcp-rag-server/src/mcp.ts`)
- Memory vector store → MCP tool server: returns matches (evidence: `mcp-rag-server/src/mcp.ts`)
- MCP tool server → Cursor user: returns passages (evidence: `README.md`)
- RAG pipeline → Path resolver: resolves path (evidence: `mcp-rag-server/src/rag.ts`)
- RAG pipeline → Environment loader: loads credentials (evidence: `mcp-rag-server/src/rag.ts`)
- Environment loader → Path resolver: resolves env path (evidence: `mcp-rag-server/src/helpers/getEnv.ts`)
