fix(mcp): publish API reference docs and load latest version by dkalinovInfra · Pull Request #1701 · IgniteUI/igniteui-cli

dkalinovInfra · 2026-05-20T15:46:46Z

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.

…docs

…erver, and templates

…se latest versions

…erver, templates, and schematics

…, templates, and schematics

coveralls · 2026-05-20T15:51:16Z

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.

damyanpetev · 2026-05-21T11:45:18Z

-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.CLASSIC_PAT_GITHUB }}


If you're adding a PAT token to this step as well, can we not just use submodules: true/recursive and have those clones correctly? I assume all of the submodules are needed at build time.

That'll also allow dropping or at least splitting the spread out submodule update calls from build scripts.

That PAT token was already added, so I've decided to reuse it. About other submodules, for now we don't use them during the build, so this will slow down the release workflow without any real need to have all of the submodules.

damyanpetev · 2026-05-21T12:56:26Z

+const PKG_PATH = join(ROOT, 'blazor', 'api-docs', 'package.json');
+
+const OVERRIDES = {
+  '@astrojs/sitemap': '^3.7.2',


Um any specific reason for the overrides? Kinda doesn't seem it should be needed, the submodules should be hitting stable refs, right?
Besides the fact this can affect the lock file, it will also go out of sync with the submodule repo - so fragile either way.

If there's an issue, is this something that should be addressed/fixed in the submodule repo itself?

PS: Really odd the api-docs for all is cloned under blazor 😄

I will probably deleted this script, as it may not be needed any more. Api repo was updated with same sitemap version as we need for the build (the issue was coming from zod versions sitemap needs v3 but we have dependency on v4 and this was breaking the build).

damyanpetev · 2026-05-21T12:59:31Z

And this one is a bit shaky too, though almost all of the scripts around collecting those API docs are prone to breakage if anything shifts slightly in the API docs build process.

Unless speed is critical here, as this is a requirement for the process, it should be possible to address this in the submodule repo again - either by producing artifacts that can be consumed by the MCP eventually, but even before that on the build commands level in api-docs we should really have a sub-set command to produce just the latest API Docs for a platform and even just the LLMs txt if possible and even preferably with parametrized path so this process can call something like:

npm run build:angular-latest-llm:en -- ../../docs/angular-api/llms-full.txt

and be pretty much done with the whole process.

dkalinovInfra added 9 commits May 20, 2026 13:55

Deleting generated documentation

e92b28a

chore: update GitHub Actions to use latest actions and build MCP API …

26b27e5

…docs

chore: update package versions to 15.2.2-alpha.0 for CLI, core, MCP s…

f6f369f

…erver, and templates

Adding global git user

96f6d94

chore: update build command to include API docs overrides

fa04097

feat: implement version picking logic and update API doc loaders to u…

1675673

…se latest versions

chore: update package versions to 15.2.2-alpha.1 for CLI, core, MCP s…

e9f0e27

…erver, templates, and schematics

Merge branch 'master' into dkalinov/api-ref-docs-github-build

605ce72

chore: downgrade package versions to 15.2.1 for CLI, core, MCP server…

5ab8223

…, templates, and schematics

dkalinovInfra requested review from Copilot, damyanpetev, kdinev and onlyexeption May 20, 2026 15:46

Copilot started reviewing on behalf of dkalinovInfra May 20, 2026 15:47 View session

Copilot AI reviewed May 20, 2026

View reviewed changes

kdinev approved these changes May 21, 2026

View reviewed changes

damyanpetev reviewed May 21, 2026

View reviewed changes

dkalinovInfra added the do-not-merge label May 21, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(mcp): publish API reference docs and load latest version#1701
dkalinovInfra wants to merge 9 commits into
masterfrom
dkalinov/api-ref-docs-github-build

dkalinovInfra commented May 20, 2026

Uh oh!

coveralls commented May 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

damyanpetev May 21, 2026

Uh oh!

dkalinovInfra May 21, 2026

Uh oh!

damyanpetev May 21, 2026

Uh oh!

damyanpetev May 21, 2026

Uh oh!

dkalinovInfra May 21, 2026

Uh oh!

damyanpetev May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

dkalinovInfra commented May 20, 2026

Description

Related Issue

Type of Change

Affected Packages

Checklist

Additional Context

Uh oh!

coveralls commented May 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

damyanpetev May 21, 2026

Choose a reason for hiding this comment

Uh oh!

dkalinovInfra May 21, 2026

Choose a reason for hiding this comment

Uh oh!

damyanpetev May 21, 2026

Choose a reason for hiding this comment

Uh oh!

damyanpetev May 21, 2026

Choose a reason for hiding this comment

Uh oh!

dkalinovInfra May 21, 2026

Choose a reason for hiding this comment

Uh oh!

damyanpetev May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants