fix(mcp): publish API reference docs and load latest version

[dkalinovInfra]

Description

Fixes two bugs preventing API reference data from working in the published @igniteui/mcp-server package, plus the CI changes needed to build those docs at release time.

Bug 1 — files field shipped the wrong glob. The files array in packages/igniteui-mcp/igniteui-doc-mcp/package.json referenced docs/<framework>/api/... with .md/.json extensions, but the actual on-disk layout is docs/<framework>-api/<pkg>/<ver>/llms-full.txt. The published tarball contained zero API entries, so get_api_reference / search_api returned "API reference not available" for every platform. Updated files to match the real paths and added the missing docs/blazor-api/ entry.

Bug 2 — ApiDocLoader version collision. Entries were keyed ${platform}:${componentName} and readdirSync lex-ordering meant older versions (9.0.x) silently overwrote newer ones (21.0.x) for any package with multiple version subdirs. IgxGridComponent was returning the v9 entry, missing fields added later (e.g. groupingDone). Fix has two parts:

• Build-time filter: scripts/export-{angular,react,wc,blazor}-api.ts now copy only the highest-ranked version per package and delete any older versions from the on-disk output directory. The published tarball shrinks accordingly (Angular drops 9.0.x ~193 KB + 15.1.x ~500 KB).
• Runtime defence-in-depth: ApiDocLoader.parseLlmsFullTxt picks the latest version when iterating, so older snapshots leaking onto disk locally cannot mask newer data.
• Both sides share a new src/lib/version-picker.ts so they agree on what "latest" means. Ranking: literal latest > parsable <major>.<minor|x>.<patch|x> (numeric descending, x outranks any concrete number) > lex fallback.

CI changes (.github/workflows/npm-publish.yml).

• Bumped actions/checkout and actions/setup-node to @v4.
• Added a Build MCP API docs step that runs build:docs:all so the tarball contains fresh llms-full.txt files at publish time.
• Configured a git global URL-rewrite using secrets.CLASSIC_PAT_GITHUB so the inline git submodule update --init blazor/api-docs can authenticate to the private IgniteUI/api-docs submodule.
• Added scripts/patch-api-docs-overrides.ts that pins @astrojs/sitemap@^3.7.2 and zod@^4.3.6 in the submodule's package.json before its npm install — works around an upstream Astro z.function(...).optional is not a function runtime error.

Related Issue

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring / code cleanup
• Build / CI configuration change

Affected Packages

• igniteui-cli (packages/cli)
• @igniteui/cli-core (packages/core)
• @igniteui/angular-templates (packages/igx-templates)
• @igniteui/angular-schematics (packages/ng-schematics)
• @igniteui/mcp-server (packages/igniteui-mcp)

Checklist

• I have tested my changes locally (npm run test)
• I have built the project successfully (npm run build)
• I have run the linter (npm run lint)
• I have added/updated tests as needed
• My changes do not introduce new warnings or errors

Additional Context

• New test files: src/__tests__/lib/version-picker.test.ts (12 cases — semver ordering, latest precedence, x in minor and patch slots, empty-input throw, input-not-mutated) and a regression test in src/__tests__/lib/api-doc-loader.test.ts for the multi-version scenario.
• Verification: npm pack --dry-run in packages/igniteui-mcp/igniteui-doc-mcp/ now lists docs/*-api/**/llms-full.txt entries (was zero before the files fix).
• A CLASSIC_PAT_GITHUB repo secret with repo scope on the IgniteUI org is required for the workflow to clone the private IgniteUI/api-docs submodule. Token expiration will cause future releases to fail until rotated — long term, consider migrating to a GitHub App so this isn't a recurring concern.

[coveralls]

coverage: 87.455%. remained the same — dkalinov/api-ref-docs-github-build into master

[Copilot]

Pull request overview

This PR fixes API reference availability for the published @igniteui/mcp-server package by ensuring the generated llms-full.txt API snapshots are packaged correctly and that the runtime loader consistently prefers the newest version when multiple version directories exist. It also updates CI to build these API docs during release publishing.

Changes:

• Added shared version ranking/picking logic and updated ApiDocLoader to load only the latest version per package.
• Updated API-doc export scripts to emit only the latest version per package and introduced a patch step to pin overrides in the api-docs submodule before installing/building.
• Updated release workflow to build MCP API docs at publish time and improved checkout/setup actions.

Reviewed changes

Copilot reviewed 18 out of 30 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/igniteui-mcp/igniteui-doc-mcp/src/lib/version-picker.ts	Introduces shared version directory comparison and “latest” selection logic.
packages/igniteui-mcp/igniteui-doc-mcp/src/lib/api-doc-loader.ts	Loads only the latest version per package to prevent older snapshots overwriting newer data.
packages/igniteui-mcp/igniteui-doc-mcp/src/tests/lib/version-picker.test.ts	Adds tests for version ranking and latest selection behavior.
packages/igniteui-mcp/igniteui-doc-mcp/src/tests/lib/api-doc-loader.test.ts	Adds regression coverage for multi-version package directories.
packages/igniteui-mcp/igniteui-doc-mcp/scripts/patch-api-docs-overrides.ts	Patches api-docs submodule package.json overrides to work around upstream dependency breakage.
packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-angular-api.ts	Exports only the latest Angular API snapshot per package.
packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-react-api.ts	Exports only the latest React API snapshot per package.
packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-wc-api.ts	Exports only the latest Web Components API snapshot per package.
packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-blazor-api.ts	Exports only the latest Blazor API snapshot per package.
packages/igniteui-mcp/igniteui-doc-mcp/package.json	Ensures API snapshot files are published and wires doc-build + patching into build:docs:all.
packages/igniteui-mcp/.gitignore	Ignores generated API snapshot directories under igniteui-doc-mcp/docs/*-api.
.github/workflows/npm-publish.yml	Builds MCP API docs during releases; updates actions; configures auth for private submodules.
packages/igniteui-mcp/igniteui-doc-mcp/docs/webcomponents-api/igniteui-grid-lite/latest/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/webcomponents-api/igniteui-dockmanager/latest/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/react-api/igniteui-react-dockmanager/19.5.1/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/blazor-api/IgniteUI.Blazor.GridLite/25.1.x/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/blazor-api/IgniteUI.Blazor.Documents.Core/25.1.x/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/angular-api/igniteui-angular-layouts/latest/llms-full.txt	Removes checked-in generated API snapshot (now built during release).
packages/igniteui-mcp/igniteui-doc-mcp/docs/angular-api/igniteui-angular-gauges/latest/llms-full.txt	Removes checked-in generated API snapshot (now built during release).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.