# darcas/refero-design-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/darcas/refero-design-mcp
- Repository: https://github.com/darcas/refero-design-mcp

## Overview

Refero Design MCP is a stdio server for discovering public design styles, building a lazy local index, and returning parsed JSON or sectioned design.md. The main workflow checks index coverage, searches or matches styles, then retrieves a selected style through a tool or resource. Sitemap discovery, page extraction, cached state, scoring, and rendering are distinct stages; the README also documents the style-ID listing capability. Edges follow shown calls and documented source behavior; several tool implementations and extractors were not excerpted, so their internal links are omitted.

Main entry points: [`src/server/tools/index.ts`](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/index.ts) (Tool registry), [`src/index/store.ts`](https://github.com/darcas/refero-design-mcp/blob/main/src/index/store.ts) (Style store), [`src/server/tools/@shared.ts`](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/%40shared.ts) (Tool helpers), [`src/server/tools/searchStyles.ts`](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/searchStyles.ts) (Style search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP surface"]
  node_assembly["Server assembly<br/>[index.ts]"]
  node_toolregistry["Tool registry<br/>[index.ts]"]
  node_search["Style search<br/>[searchStyles.ts]"]
  node_match["Style matching<br/>[matchStyle.ts]"]
  node_status["Index status<br/>[indexStatus.ts]"]
  node_listids["Style ID listing<br/>[listStyleIds.ts]"]
  node_getdesign["Design Markdown tool<br/>[getDesignMd.ts]"]
  node_getstyle["Style JSON tool<br/>[getStyle.ts]"]
  node_resource["Design resource<br/>[designMd.ts]"]
  node_shared["Tool helpers<br/>[@shared.ts]"]
end

subgraph group_discovery["Discovery and index"]
  node_expand["Index expansion<br/>[index.ts]"]
  node_store[("Style store<br/>[store.ts]")]
  node_sitemap["Sitemap parser<br/>[sitemap.ts]"]
end

subgraph group_design["Design processing"]
  node_rsc["Page extractor<br/>[rsc.ts]"]
  node_scoring["Relevance scoring<br/>[scoring.ts]"]
  node_renderer["Markdown renderer<br/>[designMd.ts]"]
  node_truncate["Markdown truncation<br/>[truncate.ts]"]
  node_types["Style schemas<br/>[types.ts]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_http["HTTP client<br/>[http.ts]"]
  node_concurrency["Concurrency limiter<br/>[concurrency.ts]"]
end

node_client(("MCP client"))
node_site{{"Refero public pages"}}
node_disk[("Local cache files")]

node_client -->|"connects via stdio"| node_assembly
node_assembly -->|"registers tools"| node_toolregistry
node_assembly -->|"registers resource"| node_resource
node_toolregistry -->|"registers"| node_status
node_toolregistry -->|"registers"| node_search
node_toolregistry -->|"registers"| node_match
node_toolregistry -->|"registers"| node_getdesign
node_toolregistry -->|"registers"| node_getstyle
node_toolregistry -->|"registers"| node_listids
node_toolregistry -->|"passes expansion"| node_expand
node_search -->|"expands index"| node_expand
node_search -->|"reads summaries"| node_store
node_search -->|"ranks and formats"| node_shared
node_match -->|"uses scoring helpers"| node_shared
node_match -->|"expands index"| node_expand
node_status -->|"uses tool helpers"| node_shared
node_listids -->|"uses tool helpers"| node_shared
node_getdesign -->|"uses tool helpers"| node_shared
node_getdesign -->|"renders document"| node_renderer
node_getstyle -->|"uses tool helpers"| node_shared
node_resource -->|"loads style"| node_store
node_resource -->|"renders document"| node_renderer
node_expand -->|"fetches uncached styles"| node_store
node_expand -->|"limits parallel work"| node_concurrency
node_expand -->|"reads fetch limits"| node_config
node_store -->|"fetches pages"| node_http
node_store -->|"parses sitemap"| node_sitemap
node_store -->|"extracts page data"| node_rsc
node_store -->|"reads and writes cache"| node_disk
node_store -->|"uses cache settings"| node_config
node_sitemap -->|"requests sitemap"| node_http
node_http -->|"uses request settings"| node_config
node_http -->|"requests public pages"| node_site
node_shared -->|"scores summaries"| node_scoring
node_renderer -->|"truncates output"| node_truncate
node_renderer -->|"uses style structures"| node_types
node_rsc -->|"validates extracted data"| node_types

click node_assembly "https://github.com/darcas/refero-design-mcp/blob/main/src/server/index.ts"
click node_toolregistry "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/index.ts"
click node_search "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/searchStyles.ts"
click node_match "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/matchStyle.ts"
click node_status "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/indexStatus.ts"
click node_listids "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/listStyleIds.ts"
click node_getdesign "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/getDesignMd.ts"
click node_getstyle "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/getStyle.ts"
click node_resource "https://github.com/darcas/refero-design-mcp/blob/main/src/server/resources/designMd.ts"
click node_shared "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/%40shared.ts"
click node_expand "https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/index.ts"
click node_store "https://github.com/darcas/refero-design-mcp/blob/main/src/index/store.ts"
click node_sitemap "https://github.com/darcas/refero-design-mcp/blob/main/src/sources/sitemap.ts"
click node_rsc "https://github.com/darcas/refero-design-mcp/blob/main/src/sources/rsc.ts"
click node_scoring "https://github.com/darcas/refero-design-mcp/blob/main/src/core/scoring.ts"
click node_renderer "https://github.com/darcas/refero-design-mcp/blob/main/src/core/designMd.ts"
click node_truncate "https://github.com/darcas/refero-design-mcp/blob/main/src/core/truncate.ts"
click node_types "https://github.com/darcas/refero-design-mcp/blob/main/src/types.ts"
click node_config "https://github.com/darcas/refero-design-mcp/blob/main/src/config.ts"
click node_http "https://github.com/darcas/refero-design-mcp/blob/main/src/http.ts"
click node_concurrency "https://github.com/darcas/refero-design-mcp/blob/main/src/core/concurrency.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_assembly,node_toolregistry,node_search,node_match,node_status,node_listids,node_getdesign,node_getstyle,node_resource,node_shared,node_client toneBlue
class node_expand,node_store,node_sitemap,node_disk toneAmber
class node_rsc,node_scoring,node_renderer,node_truncate,node_types toneMint
class node_config,node_http,node_concurrency toneRose
class node_site toneIndigo
```

## Components

### MCP surface

- [Server assembly](https://github.com/darcas/refero-design-mcp/blob/main/src/server/index.ts): `src/server/index.ts`
- [Tool registry](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/index.ts): `src/server/tools/index.ts`
- [Style search](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/searchStyles.ts): `src/server/tools/searchStyles.ts`
- [Style matching](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/matchStyle.ts): `src/server/tools/matchStyle.ts`
- [Index status](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/indexStatus.ts): `src/server/tools/indexStatus.ts`
- [Style ID listing](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/listStyleIds.ts): `src/server/tools/listStyleIds.ts`
- [Design Markdown tool](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/getDesignMd.ts): `src/server/tools/getDesignMd.ts`
- [Style JSON tool](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/getStyle.ts): `src/server/tools/getStyle.ts`
- [Design resource](https://github.com/darcas/refero-design-mcp/blob/main/src/server/resources/designMd.ts): `src/server/resources/designMd.ts`
- [Tool helpers](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/%40shared.ts): `src/server/tools/@shared.ts`

### Discovery and index

- [Index expansion](https://github.com/darcas/refero-design-mcp/blob/main/src/server/tools/index.ts): `src/server/tools/index.ts`
- [Style store](https://github.com/darcas/refero-design-mcp/blob/main/src/index/store.ts): `src/index/store.ts`
- [Sitemap parser](https://github.com/darcas/refero-design-mcp/blob/main/src/sources/sitemap.ts): `src/sources/sitemap.ts`

### Design processing

- [Page extractor](https://github.com/darcas/refero-design-mcp/blob/main/src/sources/rsc.ts): `src/sources/rsc.ts`
- [Relevance scoring](https://github.com/darcas/refero-design-mcp/blob/main/src/core/scoring.ts): `src/core/scoring.ts`
- [Markdown renderer](https://github.com/darcas/refero-design-mcp/blob/main/src/core/designMd.ts): `src/core/designMd.ts`
- [Markdown truncation](https://github.com/darcas/refero-design-mcp/blob/main/src/core/truncate.ts): `src/core/truncate.ts`
- [Style schemas](https://github.com/darcas/refero-design-mcp/blob/main/src/types.ts): `src/types.ts`

### Runtime infrastructure

- [Runtime configuration](https://github.com/darcas/refero-design-mcp/blob/main/src/config.ts): `src/config.ts`
- [HTTP client](https://github.com/darcas/refero-design-mcp/blob/main/src/http.ts): `src/http.ts`
- [Concurrency limiter](https://github.com/darcas/refero-design-mcp/blob/main/src/core/concurrency.ts): `src/core/concurrency.ts`

### Other components

- **MCP client**
- **Refero public pages**
- **Local cache files**

## Connections

- MCP client → Server assembly: connects via stdio (evidence: `README.md`)
- Server assembly → Tool registry: registers tools (evidence: `src/server/index.ts`)
- Server assembly → Design resource: registers resource (evidence: `src/server/index.ts`)
- Tool registry → Index status: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Style search: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Style matching: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Design Markdown tool: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Style JSON tool: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Style ID listing: registers (evidence: `src/server/tools/index.ts`)
- Tool registry → Index expansion: passes expansion (evidence: `src/server/tools/index.ts`)
- Style search → Index expansion: expands index (evidence: `src/server/tools/searchStyles.ts`)
- Style search → Style store: reads summaries (evidence: `src/server/tools/searchStyles.ts`)
- Style search → Tool helpers: ranks and formats (evidence: `src/server/tools/searchStyles.ts`)
- Style matching → Tool helpers: uses scoring helpers (evidence: `src/server/tools/matchStyle.ts`)
- Style matching → Index expansion: expands index (evidence: `src/server/tools/index.ts`)
- Index status → Tool helpers: uses tool helpers (evidence: `src/server/tools/indexStatus.ts`)
- Style ID listing → Tool helpers: uses tool helpers (evidence: `src/server/tools/listStyleIds.ts`)
- Design Markdown tool → Tool helpers: uses tool helpers (evidence: `src/server/tools/getDesignMd.ts`)
- Design Markdown tool → Markdown renderer: renders document (evidence: `src/server/tools/getDesignMd.ts`)
- Style JSON tool → Tool helpers: uses tool helpers (evidence: `src/server/tools/getStyle.ts`)
- Design resource → Style store: loads style (evidence: `src/server/resources/designMd.ts`)
- Design resource → Markdown renderer: renders document (evidence: `src/server/resources/designMd.ts`)
- Index expansion → Style store: fetches uncached styles (evidence: `src/server/tools/index.ts`)
- Index expansion → Concurrency limiter: limits parallel work (evidence: `src/server/tools/index.ts`)
- Index expansion → Runtime configuration: reads fetch limits (evidence: `src/server/tools/index.ts`)
- Style store → HTTP client: fetches pages (evidence: `src/index/store.ts`)
- Style store → Sitemap parser: parses sitemap (evidence: `src/index/store.ts`)
- Style store → Page extractor: extracts page data (evidence: `src/index/store.ts`)
- Style store → Local cache files: reads and writes cache (evidence: `src/index/store.ts`)
- Style store → Runtime configuration: uses cache settings (evidence: `src/index/store.ts`)
- Sitemap parser → HTTP client: requests sitemap (evidence: `src/sources/sitemap.ts`)
- HTTP client → Runtime configuration: uses request settings (evidence: `src/http.ts`)
- HTTP client → Refero public pages: requests public pages (evidence: `README.md`)
- Tool helpers → Relevance scoring: scores summaries (evidence: `src/server/tools/@shared.ts`)
- Markdown renderer → Markdown truncation: truncates output (evidence: `src/core/designMd.ts`)
- Markdown renderer → Style schemas: uses style structures (evidence: `src/core/designMd.ts`)
- Page extractor → Style schemas: validates extracted data (evidence: `src/sources/rsc.ts`)
