igniteui-doc-mcp

MCP server that serves pre-compressed Ignite UI component documentation via full-text search. Supports two modes: remote (proxies to a backend API) and local (bundled SQLite database via sql.js). Includes multi-step pipelines for processing raw documentation into optimized, LLM-friendly markdown for Angular, React, WebComponents, and Blazor.

Setup

cd packages/igniteui-mcp/igniteui-doc-mcp
git submodule update --init --recursive
npm install

Create a .env file with your OpenAI API key (required for compress and validate steps):

OPENAI_API_KEY=sk-...

Building the Database

The MCP server uses a SQLite database with FTS4 full-text search to serve documentation. The database is built from the compressed markdown files in dist/docs_final/ using the build-db.ts script.

npm run build:db

Building the API markdown

The repository already tracks the required documentation and source repositories as git submodules. A fresh clone still needs git submodule update --init --recursive to materialize them locally.

Required submodules for local API markdown generation include:

angular/igniteui-angular
webcomponents/igniteui-webcomponents

Before using the MCP server from a source checkout, generate the local API markdowns:

npm run build:docs:all

This step builds the Angular and Web Components API markdown used by the local MCP API tools. If you skip it, API lookups may be incomplete or unavailable even if the server itself builds successfully.

If you want to refresh submodules to newer upstream commits, run:

git submodule update --remote --merge

Building the MCP Server

Compile the TypeScript source code for the MCP server:

npm run build

Running the MCP Server

# Local mode (default) — uses bundled SQLite database
node dist/index.js

# Remote mode — proxies to a backend API
node dist/index.js --remote https://your-backend-url.com

# Remote mode via env var
IGNITEUI_MCP_DOCS_BACKEND_URL=https://your-backend-url.com node dist/index.js --remote

# Custom DB path for local mode
DB_PATH=/path/to/igniteui-docs.db node dist/index.js

# Enable debug logging
node dist/index.js --debug

Local mode requires dist/igniteui-docs.db. Run the pipeline and npm run build:db to generate it.

Configuring MCP Clients

To use the server with an MCP client (VS Code, Claude Desktop, Cursor, etc.), add it to your MCP configuration file.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "igniteui-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/igniteui-doc-mcp/dist/index.js"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "igniteui-cli": {
      "command": "node",
      "args": ["/absolute/path/to/igniteui-doc-mcp/dist/index.js"]
    }
  }
}

With custom DB path (any client — add env block):

{
  "command": "node",
  "args": ["/absolute/path/to/igniteui-doc-mcp/dist/index.js"],
  "env": {
    "DB_PATH": "/absolute/path/to/igniteui-docs.db"
  }
}

With remote backend (any client):

{
  "command": "node",
  "args": ["/absolute/path/to/igniteui-doc-mcp/dist/index.js", "--remote", "https://your-backend-url.com"]
}

Note: The server uses local mode by default — fully self-contained with no backend API or network access needed. The SQLite database (db/igniteui-docs.db) is checked into git, so after npm run build it is copied to dist/ and ready to use.

Pipeline Overview

Each platform (Angular, React, WebComponents, Blazor) has an incremental pipeline that only recompresses docs that actually changed, saving LLM API costs and time:

export → inject → diff → compress (changed only) → update baseline → build:db

Step	Input	Output	Requires API
Export	Source docs (docfx/xplat)	`dist/docs_processing/<platform>/`	No
Inject	`dist/docs_processing/<platform>/`	`dist/docs_prepeared/<platform>/`	No
Diff	`dist/docs_prepeared/<platform>/` vs `docs_baseline/<platform>/`	`dist/diff-manifest.json`	No
Compress	`dist/docs_prepeared/<platform>/` (changed only)	`dist/docs_final/<platform>/`	Yes
Update Baseline	`dist/docs_prepeared/<platform>/`	`docs_baseline/<platform>/`	No
Validate	`dist/docs_prepeared/` + `dist/docs_final/`	`dist/validation_report_<platform>.json`	Yes
Build DB	`dist/docs_final/` + `dist/docs_prepeared/`	`dist/igniteui-docs.db`	No

The diff step compares the fresh inject output against a tracked baseline (docs_baseline/) using SHA-256 content hashes (with line-ending normalization for cross-platform consistency). Only files classified as changed or added are sent to the compress step. Deleted files are removed from the output directory. Unchanged files are skipped entirely.

Export — Parses the table of contents (Angular: toc.yml, others: toc.json) to get the definitive list of published docs. For React, WebComponents, and Blazor it first runs the xplat gulp build which handles variable replacement, platform filtering, and API link resolution. Flattens hierarchical directory output into single-level filenames (e.g. grids/grid/editing.md → grid-editing.md) and injects toc metadata (_tocName, _premium) into each file's frontmatter.

Inject — Replaces <code-view> HTML tags with actual component source code from the platform's examples repository. Resolves samples via the github-src attribute. Includes a post-inject data trimming step that keeps only 3 representative items from large data arrays and replaces the rest with // ... N more items, preventing individual files from exceeding 300KB.

Compress — Sends each doc through an LLM with a platform-specific system prompt to reduce size by ~50% while preserving structure, code examples, and API references. Each platform's prompt specifies the correct component prefix (Igx/Igr/Igc/Igb), naming conventions, code block languages, and comment syntax. Counts tokens per file via js-tiktoken and writes _compression_log.csv and _compression_stats.json alongside output. When run with --manifest, only processes files listed as changed or added.

Update Baseline — Copies successfully compressed prepared docs to docs_baseline/<platform>/ and removes deleted files. This tracked baseline enables the diff step on subsequent runs. On the first run (or with --full), all prepared files are copied.

Validate — LLM-as-Judge evaluation that samples compressed docs and scores them against the originals on 4 dimensions: completeness, accuracy, hallucination, and structure. Uses OpenAI structured output for guaranteed valid JSON responses.

Run Full Pipeline

The default pipeline is incremental — it only compresses docs that changed since the last run:

npm run pipeline:angular
npm run pipeline:react
npm run pipeline:webcomponents
npm run pipeline:blazor

To force a full rebuild (e.g. after prompt changes or model upgrades), use the :full variant which skips the diff step and reprocesses everything:

npm run pipeline:angular:full
npm run pipeline:react:full
npm run pipeline:webcomponents:full
npm run pipeline:blazor:full

Run Individual Steps

# Angular
npm run export:angular           # parse toc.yml, expand grid templates, inject metadata
npm run inject:angular           # replace <code-view> tags with TS/HTML/SCSS source code
npm run diff:angular             # compare against baseline, output diff-manifest.json
npm run compress:angular         # LLM-compress docs (~50% reduction, Igx prefix)
npm run update-baseline:angular  # sync baseline with freshly processed docs
npm run validate:angular         # LLM-as-Judge quality scoring

# Blazor
npm run build:xplat-blazor       # run xplat gulp build for Blazor
npm run export:blazor            # flatten built docs, filter by toc.json, inject metadata
npm run inject:blazor            # replace <code-view> tags with Razor/C#/CSS source code
npm run diff:blazor              # compare against baseline, output diff-manifest.json
npm run compress:blazor          # LLM-compress docs (~50% reduction, Igb prefix)
npm run update-baseline:blazor   # sync baseline with freshly processed docs
npm run validate:blazor          # LLM-as-Judge quality scoring

# React
npm run build:xplat-react        # run xplat gulp build for React
npm run export:react             # flatten built docs, filter by toc.json, inject metadata
npm run inject:react             # replace <code-view> tags with TSX/CSS source code
npm run diff:react               # compare against baseline, output diff-manifest.json
npm run compress:react           # LLM-compress docs (~50% reduction, Igr prefix)
npm run update-baseline:react    # sync baseline with freshly processed docs
npm run validate:react           # LLM-as-Judge quality scoring

# WebComponents
npm run build:xplat-wc           # run xplat gulp build for WebComponents
npm run export:webcomponents     # flatten built docs, filter by toc.json, inject metadata
npm run inject:webcomponents     # replace <code-view> tags with HTML/TS/CSS source code
npm run diff:webcomponents       # compare against baseline, output diff-manifest.json
npm run compress:webcomponents   # LLM-compress docs (~50% reduction, Igc prefix)
npm run update-baseline:webcomponents  # sync baseline with freshly processed docs
npm run validate:webcomponents   # LLM-as-Judge quality scoring

Scripts Reference

export-angular-docs.ts

Reads toc.yml to determine which files to process, expands grid templates, and copies docs with metadata to the processing directory.

npm run export:angular
# or directly:
npx tsx scripts/export-angular-docs.ts [lang]

Parameter	Description	Default
`[lang]`	Language code (positional, first arg)	`en`

inject-angular-docs.ts

Replaces <code-view> tags in exported docs with actual Angular component source code (TypeScript, HTML, SCSS).

npm run inject:angular
# or directly:
npx tsx scripts/inject-angular-docs.ts

No CLI parameters.

compress-angular-docs.ts / compress-react-docs.ts / compress-wc-docs.ts / compress-blazor-docs.ts

Uses an LLM to compress prepared docs into concise, structured markdown. Each script has a platform-specific system prompt (Angular uses Igx prefix, React uses Igr, WebComponents uses Igc + Component suffix, Blazor uses Igb). All compress scripts count tokens per file using js-tiktoken (o200k_base encoding). Requires OPENAI_API_KEY in .env.

npm run compress:angular
npm run compress:react
npm run compress:webcomponents
npm run compress:blazor

Parameter	Description	Default
`--model <name>`	OpenAI model to use	`gpt-5.4-mini`
`--api-base <url>`	Custom OpenAI API base URL	OpenAI default
`--min-size <kb>`	Skip files smaller than this (KB)	`0`
`--delay <seconds>`	Delay between API calls	`0.5`
`--dry-run`	Show what would be processed without calling the API	off
`--resume-from <file>`	Continue processing from a specific file (e.g. `grid.md`)	none
`--only <file>`	Process a single file only (e.g. `button.md`)	none
`--batch submit\|poll\|retry`	Use OpenAI Batch API (50% cheaper, async)	off (sequential)
`--manifest <path>`	Diff manifest JSON — only compress changed/added files	none (process all)

Output files (written to dist/docs_final/<platform>/):

Compressed .md files
_compression_stats.json — aggregate stats including total_tokens
_compression_log.csv — per-file log with columns: file,original_kb,compressed_kb,reduction_pct,tokens
_batch_state.json — batch mode state (batch ID, status, failed/invalid files)
_batch_input.jsonl — batch mode JSONL input file

Examples:

# Process only button.md
npm run compress:angular -- --only button.md

# Resume from grid.md after a failure
npm run compress:angular -- --resume-from grid.md

# Dry run with a different model
npm run compress:angular -- --model gpt-5.1 --dry-run

# Skip small files
npm run compress:angular -- --min-size 2

# Batch mode (50% cost reduction via OpenAI Batch API)
npm run compress:react -- --batch submit           # Step 1: upload & create batch
npm run compress:react -- --batch poll             # Step 2: poll, download & validate results
npm run compress:react -- --batch retry            # Step 3: retry failed/invalid files (optional)

# Batch with filters
npm run compress:react -- --batch submit --only grid.md --model gpt-5.4-mini

# Incremental mode (only compress changed files from diff manifest)
npm run compress:angular -- --manifest dist/diff-manifest.json

diff-docs.ts

Compares freshly prepared docs (dist/docs_prepeared/<platform>/) against the tracked baseline (docs_baseline/<platform>/) using SHA-256 content hashes. Normalizes line endings to \n before hashing for cross-platform consistency (Windows CRLF vs Linux LF). Outputs a JSON manifest classifying each file as changed, added, deleted, or unchanged.

npm run diff:angular
# or directly:
npx tsx scripts/diff-docs.ts --framework angular

Parameter	Description	Default
`--framework <name>`	(Required) Platform to diff (`angular`, `react`, `blazor`, `webcomponents`)	none

Output: dist/diff-manifest.json

{
  "framework": "angular",
  "changed": ["grid.md", "button.md"],
  "added": ["new-component.md"],
  "deleted": ["deprecated-component.md"],
  "unchanged": ["accordion.md", "action-strip.md", "..."]
}

When docs_baseline/<platform>/ doesn't exist (first run), all files are classified as added.

update-baseline.ts

After successful compression, updates the tracked baseline by copying changed/added files from dist/docs_prepeared/<platform>/ to docs_baseline/<platform>/ and removing deleted files.

npm run update-baseline:angular
# or directly:
npx tsx scripts/update-baseline.ts --framework angular --manifest dist/diff-manifest.json

Parameter	Description	Default
`--framework <name>`	(Required) Platform to update	none
`--manifest <path>`	Path to diff manifest JSON	none
`--full`	Copy ALL prepared files (ignores manifest, for bootstrap/force rebuild)	off

Either --manifest or --full is required.

validate-docs.ts

LLM-as-Judge validation that scores compressed docs against their originals on completeness, accuracy, hallucination, and structure quality. Platform-independent — pass the input directory as a parameter. Requires OPENAI_API_KEY in .env.

npm run validate:angular
# or directly:
npx tsx --env-file=.env scripts/validate-docs.ts --input ./dist/docs_final/angular [options]

Parameter	Description	Default
`--input <dir>`	(Required) Path to compressed docs directory	none
`--original <dir>`	Path to original (pre-compress) docs directory	Inferred by replacing `docs_final` with `docs_prepeared` in `--input`
`--output <path>`	Path for the JSON report file	`dist/validation_report_<platform>.json`
`--model <name>`	OpenAI model for judging	`gpt-5.4`
`--api-base <url>`	Custom OpenAI API base URL	OpenAI default
`--sample <count>`	Number of files to validate (stratified by size)	`10`
`--delay <seconds>`	Delay between API calls	`1`
`--only <file>`	Validate a single file only (e.g. `button.md`)	none

Examples:

# Validate 20 random files
npm run validate:angular -- --sample 20

# Validate a specific file
npm run validate:angular -- --only button.md

# Validate all files
npm run validate:angular -- --sample 9999

Output is saved to dist/validation_report_angular.json (platform derived from --input path).

build-db.ts

Builds a SQLite database with FTS4 full-text search from compressed docs. Reads dist/docs_final/<framework>/ for doc content and dist/docs_prepeared/<framework>/ for _tocName metadata. Produces dist/igniteui-docs.db (~20MB for ~1,200 docs).

npm run build:db
# or directly:
npx tsx scripts/build-db.ts [options]

Parameter	Description	Default
`--framework <name>`	Rebuild only one framework (`angular`, `react`, `blazor`, `webcomponents`)	all frameworks

Full rebuild drops and recreates all tables. Per-framework rebuild deletes only that framework's rows and reinserts them.

Examples:

# Full rebuild for all frameworks
npm run build:db

# Rebuild only react rows (preserves other frameworks)
npm run build:db -- --framework react

Cleanup Scripts

npm run clear                # Delete entire dist/ directory
npm run clear:build          # Delete only working dirs (docs_processing/ + docs_prepeared/), preserves docs_final/ and DB
npm run clear:angular        # Delete all Angular build artifacts (docs_processing, docs_prepeared, docs_final)
npm run clear:react          # Delete only React build artifacts
npm run clear:blazor         # Delete only Blazor build artifacts
npm run clear:webcomponents  # Delete only WebComponents build artifacts

clear:build is used by the incremental pipeline — it clears the working directories while preserving dist/docs_final/ (needed for unchanged files) and dist/igniteui-docs.db.

Per-platform clear removes the platform subdirectory from docs_processing/, docs_prepeared/, and docs_final/. Use these for a full rebuild of a single platform.

API Reference Documentation

The MCP server provides API reference lookup via the get_api_reference and search_api tools. API docs are generated from framework submodules using TypeDoc and stored in docs/<framework>/.

Each framework uses one of two source strategies:

Framework	Strategy	Source	Output
Angular	`markdown-index`	`angular/igniteui-angular` (TypeDoc → markdown)	`docs/angular/api/*.md` + `index.json`
React	`typedoc-json`	Pre-built TypeDoc JSON model	`docs/react/igniteui-react.json`
Web Components	`markdown-index`	`webcomponents/igniteui-webcomponents` (TypeDoc → markdown)	`docs/webcomponents/api/*.md` + `index.json`
Blazor	—	Not yet supported	—

Building API Docs

npm run build:docs:angular         # Angular: TypeDoc → markdown + search index
npm run build:docs:webcomponents   # Web Components: build lib → TypeDoc → markdown + search index
npm run build:docs:all             # Build both Angular and Web Components

Each build:docs:<platform> script:

Initializes the required git submodule (git submodule update --init)
Compiles the MCP server TypeScript (npm run build)
Runs scripts/build-docs.mjs <platform> which:
- Checks the submodule is built (for Web Components, runs npm install && npm run build:publish if needed)
- Runs TypeDoc with the config from typedoc/<platform>.typedoc.json
- Generates markdown files in docs/<platform>/api/
- Builds a search index (index.json) with component names, types, keywords, and summaries

React uses a pre-built TypeDoc JSON model (docs/react/igniteui-react.json) that is checked into git. It does not need a build:docs step — the JSON is parsed at runtime by ReactJsonParser.

Rebuilding After Upstream Changes

When the upstream Angular or Web Components library releases a new version:

Update the submodule to the new version:

cd angular/igniteui-angular    # or webcomponents/igniteui-webcomponents
git fetch && git checkout <new-tag>
cd ../..

Rebuild the API docs:

npm run build:docs:angular     # or build:docs:webcomponents

Commit the updated docs/ output and submodule reference.

Web Components First-Time Build

The Web Components submodule requires a one-time library build before TypeDoc can generate docs. The build-docs.mjs script handles this automatically:

If dist/index.d.ts is missing, it runs npm install && npm run build:publish
After TypeDoc completes, it cleans up node_modules if it installed them
Subsequent runs skip the build step if dist/index.d.ts exists

If the automatic build fails, build manually:

cd webcomponents/igniteui-webcomponents
npm install && npm run build:publish
cd ../..
npm run build:docs:webcomponents

MCP Server

Build the database, compile TypeScript, and start:

npm run build:db   # build SQLite database from compressed docs
npm run build      # compile TypeScript
npm run start      # start MCP server

MCP Client Configuration

{
  "mcpServers": {
    "igniteui-docs": {
      "command": "node",
      "args": ["path/to/igniteui-doc-mcp/dist/index.js"]
    }
  }
}

The server uses local mode by default, loading dist/igniteui-docs.db (SQLite with FTS4) into memory via sql.js to serve ~1,200 docs across all 4 frameworks. Use --remote <url> to proxy to a backend API instead. Use --debug to enable request logging.

Testing with MCP Inspector

npm run inspector                                    # standalone MCP server
npx @modelcontextprotocol/inspector ig mcp           # via CLI (after build:mcp-bundle + build)

Tools

Tool	Parameters	Description
`list_components`	`framework` (required), `filter?`	List docs for a framework, optionally filtered by keyword (LIKE match against filename, component, toc_name, keywords, summary)
`get_doc`	`framework` (required), `name` (required)	Return full markdown content of a specific doc. `name` is without `.md` extension
`search_docs`	`query` (required), `framework` (required)	FTS4 full-text search with Porter stemming. Returns top 20 results with snippet excerpts
`get_project_setup_guide`	`framework` (required)	Return setup guides for creating a new Ignite UI project. For Angular/React/WC: CLI docs. For Blazor: dotnet + NuGet guides
`get_api_reference`	`framework` (required), `name` (required)	Retrieve the full API reference for a component or class. Returns formatted markdown with properties, methods, and events
`search_api`	`framework` (required), `query` (required)	Search API entries by keyword, feature, or partial component name. Returns up to 10 results ranked by match count

get_project_setup_guide

Returns framework-specific setup guides for creating a new Ignite UI project.

For Angular, React, Web Components: Returns Ignite UI CLI documentation with step-by-step instructions for project scaffolding. For Blazor: Returns a guide for creating a Blazor app using dotnet new and adding Ignite UI Blazor dependencies via NuGet.

Supported frameworks: angular, react, webcomponents, blazor

Parameters:

Parameter	Required	Description
`framework`	Yes	`angular`, `react`, `webcomponents`, or `blazor`

Example:

{
  "framework": "angular"
}

Directory Structure

igniteui-doc-mcp/
  angular/                          # Angular git submodules
    igniteui-docfx/                 # Documentation source (markdown + toc.yml)
    igniteui-angular-samples/       # Angular sample apps (component source code)
    igniteui-angular-examples/      # Additional examples (charts, maps, etc.)
  react/                            # React git submodules
    igniteui-react-examples/        # React example projects
  webcomponents/                    # WebComponents git submodules
    igniteui-wc-examples/           # WebComponents example projects
  blazor/                           # Blazor git submodules
    igniteui-blazor-examples/       # Blazor example projects
  common/                           # Cross-platform git submodules
    igniteui-xplat-docs/            # Shared docs for React, Blazor, WebComponents
  docs_baseline/                    # Tracked in git: post-inject snapshots for incremental diff
    angular/                        # Last-processed prepared docs (per platform)
    react/
    blazor/
    webcomponents/
  scripts/                          # Pipeline scripts
    build-db.ts                     # Build SQLite DB from compressed docs
    diff-docs.ts                    # Compare prepared docs against baseline (SHA-256)
    update-baseline.ts              # Sync baseline after successful compression
  src/                              # MCP server source
    index.ts                        # MCP server (sql.js + FTS4 queries)
    sql.js.d.ts                     # Type declarations for sql.js
  dist/                             # Build artifacts (gitignored)
    docs_processing/<platform>/     # Export output
    docs_prepeared/<platform>/      # Inject output (code samples embedded)
    docs_final/<platform>/          # Compress output (LLM-compressed)
      _compression_stats.json       # Aggregate compression stats (includes total_tokens)
      _compression_log.csv          # Per-file log (file, sizes, tokens)
    diff-manifest.json              # Diff output (changed/added/deleted/unchanged lists)
    igniteui-docs.db                # SQLite DB with FTS4 (built by build-db.ts)
    validation_report_<platform>.json  # Validation results (per platform)
  docs/                             # Plans and documentation
  .gitattributes                    # Enforces LF line endings for docs_baseline/

Docs

File	Description
`docs/progress.md`	Implementation progress tracker
`docs/knowledgebase.md`	Cross-platform lessons learned (32 entries)
`docs/xplat-docs-architecture.md`	Cross-platform docs architecture (variable replacement, toc.json, apiMap)
`docs/react-pipeline.md`	React pipeline implementation plan
`docs/wc-pipeline-plan.md`	WebComponents pipeline implementation plan
`docs/blazor-pipeline-plan.md`	Blazor pipeline implementation plan
`docs/db.md`	SQLite + FTS4 database integration (implemented)
`docs/batch-compression.md`	OpenAI Batch API for compression — 50% cost reduction (implemented)
`docs/incremental-processing.md`	Incremental processing design — diff-based compression to skip unchanged docs (implemented)
`docs/impl_plan.md`	Code-view injection plan
`docs/toc_based_processing.md`	TOC-based file selection plan
`docs/prefix_fix.md`	Angular prefix fix plan

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

igniteui-doc-mcp

Setup

Building the Database

Building the API markdown

Building the MCP Server

Running the MCP Server

Configuring MCP Clients

Pipeline Overview

Run Full Pipeline

Run Individual Steps

Scripts Reference

export-angular-docs.ts

inject-angular-docs.ts

compress-angular-docs.ts / compress-react-docs.ts / compress-wc-docs.ts / compress-blazor-docs.ts

diff-docs.ts

update-baseline.ts

validate-docs.ts

build-db.ts

Cleanup Scripts

API Reference Documentation

Building API Docs

Rebuilding After Upstream Changes

Web Components First-Time Build

MCP Server

MCP Client Configuration

Testing with MCP Inspector

Tools

get_project_setup_guide

Directory Structure

Docs

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History

DEVELOPMENT.md

File metadata and controls

igniteui-doc-mcp

Setup

Building the Database

Building the API markdown

Building the MCP Server

Running the MCP Server

Configuring MCP Clients

Pipeline Overview

Run Full Pipeline

Run Individual Steps

Scripts Reference

export-angular-docs.ts

inject-angular-docs.ts

compress-angular-docs.ts / compress-react-docs.ts / compress-wc-docs.ts / compress-blazor-docs.ts

diff-docs.ts

update-baseline.ts

validate-docs.ts

build-db.ts

Cleanup Scripts

API Reference Documentation

Building API Docs

Rebuilding After Upstream Changes

Web Components First-Time Build

MCP Server

MCP Client Configuration

Testing with MCP Inspector

Tools

get_project_setup_guide

Directory Structure

Docs