# scalvert/docusaurus-plugin-mcp-server architecture

> Architecture diagram of the GitHub repository scalvert/docusaurus-plugin-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scalvert/docusaurus-plugin-mcp-server
- Repository: https://github.com/scalvert/docusaurus-plugin-mcp-server
- Video tour (about a minute): https://gitdiagram.com/scalvert/docusaurus-plugin-mcp-server/video

## Overview

This Docusaurus plugin turns built documentation into artifacts and serves them through an MCP endpoint. The main workflow is: the site build collects routes, extracts and converts page content, generates search and skill artifacts, and the running server exposes search and fetch tools to AI clients. The graph also shows the Node and web adapters, optional search-provider extension points, and the install-button UI. Some subsystem links are based on the README or SOURCE INDEX; unsampled implementation details are not assumed.

Main entry points: [`src/plugin/docusaurus-plugin.ts`](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/plugin/docusaurus-plugin.ts) (Plugin orchestration), [`src/mcp/server.ts`](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/server.ts) (MCP server), [`src/skills/packager.ts`](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/packager.ts) (Skill packager), [`src/adapters/web-request.ts`](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/web-request.ts) (Web request adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Site build"]
  node_plugin["Plugin orchestration"]
  node_routes["Route collection<br/>[route-collector.ts]"]
  node_htmlparse["HTML extraction<br/>[html-parser.ts]"]
  node_markdown["Markdown conversion"]
end

subgraph group_search["Search"]
  node_indexer["Local indexer"]
  node_searchcore["Search index and ranking<br/>[local-search.ts]"]
  node_providerloader["Provider loader<br/>[loader.ts]"]
  node_localprovider["Local search provider"]
end

subgraph group_mcp["MCP serving"]
  node_webadapter["Web request adapter<br/>[web-request.ts]"]
  node_nodeadapter["Node HTTP adapter<br/>[node.ts]"]
  node_cors["CORS handling<br/>[cors.ts]"]
  node_mcpserver["MCP server<br/>[server.ts]"]
  node_searchtool["docs_search tool<br/>[docs-search.ts]"]
  node_fetchtool["docs_fetch tool<br/>[docs-fetch.ts]"]
  node_skillsmcp["Skills protocol<br/>[skills.ts]"]
end

subgraph group_skills["Agent skills"]
  node_packager["Skill packager<br/>[packager.ts]"]
  node_builtin["Built-in skill<br/>[builtin.ts]"]
  node_sitemap["Skill site map<br/>[site-map.ts]"]
  node_frontmatter["Skill frontmatter<br/>[frontmatter.ts]"]
end

subgraph group_siteui["Site UI"]
  node_installbutton["MCP install button"]
end

node_sitebuilder(("Docusaurus build"))
node_mcpclient(("AI client"))

node_sitebuilder -->|"runs plugin"| node_plugin
node_plugin -->|"collects routes"| node_routes
node_plugin -->|"extracts content"| node_htmlparse
node_plugin -->|"converts content"| node_markdown
node_plugin -->|"loads indexer"| node_indexer
node_indexer -->|"builds index"| node_searchcore
node_plugin -->|"builds skills"| node_packager
node_packager -->|"renders template"| node_builtin
node_packager -->|"validates metadata"| node_frontmatter
node_packager -->|"generates site map"| node_sitemap
node_mcpclient -->|"sends requests"| node_webadapter
node_webadapter -->|"dispatches requests"| node_mcpserver
node_webadapter -->|"applies CORS"| node_cors
node_nodeadapter -->|"dispatches requests"| node_mcpserver
node_nodeadapter -->|"applies CORS"| node_cors
node_mcpserver -->|"loads provider"| node_providerloader
node_mcpserver -->|"registers tool"| node_searchtool
node_mcpserver -->|"registers tool"| node_fetchtool
node_mcpserver -->|"adds skills"| node_skillsmcp
node_providerloader -->|"loads provider"| node_localprovider
node_localprovider -->|"queries index"| node_searchcore
node_mcpclient -->|"requests search"| node_searchtool
node_mcpclient -->|"fetches page"| node_fetchtool
node_mcpclient -->|"configures connection"| node_installbutton

click node_plugin "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/plugin/docusaurus-plugin.ts"
click node_routes "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/plugin/route-collector.ts"
click node_htmlparse "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/processing/html-parser.ts"
click node_markdown "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/processing/html-to-markdown.ts"
click node_indexer "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/indexers/local-search-indexer.ts"
click node_searchcore "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/search/local-search.ts"
click node_providerloader "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/loader.ts"
click node_localprovider "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/search/local-search-provider.ts"
click node_webadapter "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/web-request.ts"
click node_nodeadapter "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/node.ts"
click node_cors "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/cors.ts"
click node_mcpserver "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/server.ts"
click node_searchtool "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/tools/docs-search.ts"
click node_fetchtool "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/tools/docs-fetch.ts"
click node_skillsmcp "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/skills.ts"
click node_packager "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/packager.ts"
click node_builtin "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/builtin.ts"
click node_sitemap "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/site-map.ts"
click node_frontmatter "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/frontmatter.ts"
click node_installbutton "https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/theme/McpInstallButton.tsx"

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_plugin,node_routes,node_htmlparse,node_markdown,node_mcpclient toneBlue
class node_indexer,node_searchcore,node_providerloader,node_localprovider toneAmber
class node_webadapter,node_nodeadapter,node_cors,node_mcpserver,node_searchtool,node_fetchtool,node_skillsmcp toneMint
class node_packager,node_builtin,node_sitemap,node_frontmatter toneRose
class node_installbutton,node_sitebuilder toneIndigo
```

## Components

### Site build

- [Plugin orchestration](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/plugin/docusaurus-plugin.ts): `src/plugin/docusaurus-plugin.ts`
- [Route collection](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/plugin/route-collector.ts): `src/plugin/route-collector.ts`
- [HTML extraction](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/processing/html-parser.ts): `src/processing/html-parser.ts`
- [Markdown conversion](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/processing/html-to-markdown.ts): `src/processing/html-to-markdown.ts`

### Search

- [Local indexer](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/indexers/local-search-indexer.ts): `src/providers/indexers/local-search-indexer.ts`
- [Search index and ranking](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/search/local-search.ts): `src/search/local-search.ts`
- [Provider loader](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/loader.ts): `src/providers/loader.ts`
- [Local search provider](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/providers/search/local-search-provider.ts): `src/providers/search/local-search-provider.ts`

### MCP serving

- [Web request adapter](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/web-request.ts): `src/adapters/web-request.ts`
- [Node HTTP adapter](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/node.ts): `src/adapters/node.ts`
- [CORS handling](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/adapters/cors.ts): `src/adapters/cors.ts`
- [MCP server](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [docs_search tool](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/tools/docs-search.ts): `src/mcp/tools/docs-search.ts`
- [docs_fetch tool](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/tools/docs-fetch.ts): `src/mcp/tools/docs-fetch.ts`
- [Skills protocol](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/mcp/skills.ts): `src/mcp/skills.ts`

### Agent skills

- [Skill packager](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/packager.ts): `src/skills/packager.ts`
- [Built-in skill](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/builtin.ts): `src/skills/builtin.ts`
- [Skill site map](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/site-map.ts): `src/skills/site-map.ts`
- [Skill frontmatter](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/skills/frontmatter.ts): `src/skills/frontmatter.ts`

### Site UI

- [MCP install button](https://github.com/scalvert/docusaurus-plugin-mcp-server/blob/main/src/theme/McpInstallButton.tsx): `src/theme/McpInstallButton.tsx`

### Other components

- **Docusaurus build**
- **AI client**

## Connections

- Docusaurus build → Plugin orchestration: runs plugin
- Plugin orchestration → Route collection: collects routes (evidence: `src/plugin/docusaurus-plugin.ts`)
- Plugin orchestration → HTML extraction: extracts content (evidence: `src/plugin/docusaurus-plugin.ts`)
- Plugin orchestration → Markdown conversion: converts content (evidence: `src/plugin/docusaurus-plugin.ts`)
- Plugin orchestration → Local indexer: loads indexer (evidence: `src/plugin/docusaurus-plugin.ts`)
- Local indexer → Search index and ranking: builds index (evidence: `src/providers/indexers/local-search-indexer.ts`)
- Plugin orchestration → Skill packager: builds skills (evidence: `src/plugin/docusaurus-plugin.ts`)
- Skill packager → Built-in skill: renders template (evidence: `src/skills/packager.ts`)
- Skill packager → Skill frontmatter: validates metadata (evidence: `src/skills/packager.ts`)
- Skill packager → Skill site map: generates site map (evidence: `src/skills/packager.ts`)
- AI client → Web request adapter: sends requests
- Web request adapter → MCP server: dispatches requests (evidence: `src/adapters/web-request.ts`)
- Web request adapter → CORS handling: applies CORS (evidence: `src/adapters/web-request.ts`)
- Node HTTP adapter → MCP server: dispatches requests (evidence: `src/adapters/node.ts`)
- Node HTTP adapter → CORS handling: applies CORS (evidence: `src/adapters/node.ts`)
- MCP server → Provider loader: loads provider (evidence: `src/mcp/server.ts`)
- MCP server → docs_search tool: registers tool (evidence: `src/mcp/server.ts`)
- MCP server → docs_fetch tool: registers tool (evidence: `src/mcp/server.ts`)
- MCP server → Skills protocol: adds skills (evidence: `src/mcp/server.ts`)
- Provider loader → Local search provider: loads provider (evidence: `src/providers/loader.ts`)
- Local search provider → Search index and ranking: queries index (evidence: `src/providers/search/local-search-provider.ts`)
- AI client → docs_search tool: requests search
- AI client → docs_fetch tool: fetches page
- AI client → MCP install button: configures connection