Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): the MCP route's keyword index takes any doc keyword, constructor and __proto__ included (#9526)

Christopher Chedeau45cc3fef0ad9
diff --git a/apps/docsite/src/__tests__/mcp-keyword-index.test.ts b/apps/docsite/src/__tests__/mcp-keyword-index.test.ts
new file mode 100644
index 0000000000..bdf48d715b
--- /dev/null
+++ b/apps/docsite/src/__tests__/mcp-keyword-index.test.ts
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file mcp-keyword-index.test.ts
+ * @input The MCP route's keyword index (app/mcp/keywordIndex.ts) and fixture
+ * docs whose keywords include names that a plain object inherits
+ * @output Checks that each keyword is its own entry and resolves to its
+ * component
+ * @position Docsite tests; run with `pnpm -F @astryxdesign/docsite test`
+ */
+
+import {describe, expect, it} from 'vitest';
+import {buildKeywordIndex, resolveKeywords} from '../app/mcp/keywordIndex';
+
+const docs = [
+ {name: 'Builder', keywords: ['constructor', 'factory']},
+ {name: 'Prototype', keywords: ['__proto__']},
+ {name: 'Printer', keywords: ['toString', 'factory']},
+];
+
+describe('MCP keyword index over keywords a plain object inherits', () => {
+ it('indexes each keyword as its own entry', () => {
+ const index = buildKeywordIndex(docs);
+ expect(index.get('constructor')).toEqual(['Builder']);
+ expect(index.get('__proto__')).toEqual(['Prototype']);
+ expect(index.get('tostring')).toEqual(['Printer']);
+ expect(index.get('factory')).toEqual(['Builder', 'Printer']);
+ expect(index.get('valueof')).toBeUndefined();
+ });
+
+ it('resolves a query that names one of them to its component', () => {
+ const index = buildKeywordIndex(docs);
+ expect(resolveKeywords(index, 'Constructor')).toEqual(['Builder']);
+ expect(resolveKeywords(index, '__proto__')).toEqual(['Prototype']);
+ expect(resolveKeywords(index, 'a factory')).toEqual(['Builder', 'Printer']);
+ expect(resolveKeywords(index, 'hasOwnProperty')).toEqual([]);
+ });
+});
diff --git a/apps/docsite/src/__tests__/mcp-server.test.ts b/apps/docsite/src/__tests__/mcp-server.test.ts
index ed54dab99e..640d342800 100644
--- a/apps/docsite/src/__tests__/mcp-server.test.ts
+++ b/apps/docsite/src/__tests__/mcp-server.test.ts
@@ -4,8 +4,8 @@
* @file MCP server tests.
*
* Validates the keyword-based search resolution and branding for the
- * MCP server route handler. Uses the same generated registries as the
- * actual server.
+ * MCP server route handler. Uses the same generated registries and keyword
+ * index as the actual server.
*
* Run: pnpm -F @astryxdesign/docsite test
*/
@@ -21,42 +21,18 @@ import {
} from '../../../../packages/cli/foundation/discovery/template-adapter.mjs';
import type {ComponentEntry} from '../generated/componentRegistry';
+import {buildKeywordIndex, resolveKeywords} from '../app/mcp/keywordIndex';
// ── Replicate MCP server logic for testing ─────────────────────────────
-// These mirror the runtime logic in apps/docsite/src/app/mcp/route.ts
-// without importing the Next.js route handler directly.
+// The keyword index and its resolution are the route's own (keywordIndex.ts).
+// The scoring below mirrors the runtime logic in
+// apps/docsite/src/app/mcp/route.ts without importing the Next.js route
+// handler directly.
const allComponents: ComponentEntry[] = Object.values(components).flat();
const visibleComponents = allComponents.filter(c => !c.hidden);
-function buildKeywordIndex(): Record<string, string[]> {
- const index: Record<string, string[]> = {};
- for (const comp of visibleComponents) {
- for (const kw of comp.keywords) {
- const lower = kw.toLowerCase();
- if (!index[lower]) {
- index[lower] = [];
- }
- if (!index[lower].includes(comp.name)) {
- index[lower].push(comp.name);
- }
- }
- }
- return index;
-}
-
-const keywordIndex = buildKeywordIndex();
-
-function resolveKeywords(query: string): string[] {
- const lower = query.toLowerCase();
- const resolved: string[] = [];
- for (const [keyword, componentNames] of Object.entries(keywordIndex)) {
- if (lower.includes(keyword) || keyword.includes(lower)) {
- resolved.push(...componentNames);
- }
- }
- return [...new Set(resolved)];
-}
+const keywordIndex = buildKeywordIndex(visibleComponents);
function score(text: string, query: string): number {
const lower = text.toLowerCase();
@@ -94,7 +70,7 @@ function score(text: string, query: string): number {
}
function simulateSearch(query: string, limit = 8) {
- const keywordMatches = resolveKeywords(query);
+ const keywordMatches = resolveKeywords(keywordIndex, query);
const scored: Array<{name: string; score: number; type: string}> = [];
for (const comp of visibleComponents) {
@@ -142,34 +118,33 @@ function simulateSearch(query: string, limit = 8) {
describe('MCP keyword index', () => {
it('builds a non-empty keyword index from component docs', () => {
- const keys = Object.keys(keywordIndex);
- expect(keys.length).toBeGreaterThan(50);
+ expect(keywordIndex.size).toBeGreaterThan(50);
});
it('Toast is indexed under "snackbar"', () => {
- expect(keywordIndex['snackbar']).toBeDefined();
- expect(keywordIndex['snackbar']).toContain('Toast');
+ expect(keywordIndex.get('snackbar')).toBeDefined();
+ expect(keywordIndex.get('snackbar')).toContain('Toast');
});
it('Selector is indexed under "dropdown"', () => {
- expect(keywordIndex['dropdown']).toBeDefined();
- expect(keywordIndex['dropdown']).toContain('Selector');
+ expect(keywordIndex.get('dropdown')).toBeDefined();
+ expect(keywordIndex.get('dropdown')).toContain('Selector');
});
it('Dialog is indexed under "modal"', () => {
- expect(keywordIndex['modal']).toBeDefined();
- expect(keywordIndex['modal']).toContain('Dialog');
+ expect(keywordIndex.get('modal')).toBeDefined();
+ expect(keywordIndex.get('modal')).toContain('Dialog');
});
it('no duplicate component names within a keyword entry', () => {
- for (const [, names] of Object.entries(keywordIndex)) {
+ for (const names of keywordIndex.values()) {
expect(new Set(names).size).toBe(names.length);
}
});
it('hidden components are excluded from the index', () => {
const hiddenNames = allComponents.filter(c => c.hidden).map(c => c.name);
- const indexedNames = new Set(Object.values(keywordIndex).flat());
+ const indexedNames = new Set([...keywordIndex.values()].flat());
for (const name of hiddenNames) {
expect(indexedNames.has(name)).toBe(false);
}
@@ -178,33 +153,33 @@ describe('MCP keyword index', () => {
describe('MCP keyword resolution', () => {
it('resolves "snackbar" to Toast', () => {
- const results = resolveKeywords('snackbar');
+ const results = resolveKeywords(keywordIndex, 'snackbar');
expect(results).toContain('Toast');
});
it('resolves "dropdown" to Selector', () => {
- const results = resolveKeywords('dropdown');
+ const results = resolveKeywords(keywordIndex, 'dropdown');
expect(results).toContain('Selector');
});
it('resolves "modal" to Dialog', () => {
- const results = resolveKeywords('modal');
+ const results = resolveKeywords(keywordIndex, 'modal');
expect(results).toContain('Dialog');
});
it('resolves multi-word queries by substring matching', () => {
- const results = resolveKeywords('toast notification');
+ const results = resolveKeywords(keywordIndex, 'toast notification');
expect(results).toContain('Toast');
});
it('returns empty for nonsense queries', () => {
- const results = resolveKeywords('xyzzy12345');
+ const results = resolveKeywords(keywordIndex, 'xyzzy12345');
expect(results).toEqual([]);
});
it('deduplicates results', () => {
// A query that matches multiple keywords for the same component
- const results = resolveKeywords('select dropdown');
+ const results = resolveKeywords(keywordIndex, 'select dropdown');
const selectorCount = results.filter(r => r === 'Selector').length;
expect(selectorCount).toBeLessThanOrEqual(1);
});
diff --git a/apps/docsite/src/app/mcp/keywordIndex.ts b/apps/docsite/src/app/mcp/keywordIndex.ts
new file mode 100644
index 0000000000..fe2d0d730e
--- /dev/null
+++ b/apps/docsite/src/app/mcp/keywordIndex.ts
@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file keywordIndex.ts
+ * @input Each visible component's name and its `.doc.mjs` keywords
+ * @output buildKeywordIndex (each lowercased keyword to the components that
+ * list it) and resolveKeywords (the components whose keywords a query names)
+ * @position The MCP route's keyword resolution; its tests import it too
+ *
+ * A doc keyword is any string. The index is a Map because a plain object
+ * reads a keyword such as `constructor` or `__proto__` as a property it
+ * inherits, and the route then fails as it loads.
+ */
+
+/** What the index reads from a component's doc. */
+export interface KeywordSource {
+ readonly name: string;
+ readonly keywords: ReadonlyArray<string>;
+}
+
+/** Each lowercased keyword, with the components that list it, in doc order. */
+export function buildKeywordIndex(
+ sources: ReadonlyArray<KeywordSource>,
+): ReadonlyMap<string, ReadonlyArray<string>> {
+ const index = new Map<string, string[]>();
+ for (const source of sources) {
+ for (const keyword of source.keywords) {
+ const lower = keyword.toLowerCase();
+ const names = index.get(lower);
+ if (names == null) {
+ index.set(lower, [source.name]);
+ } else if (!names.includes(source.name)) {
+ names.push(source.name);
+ }
+ }
+ }
+ return index;
+}
+
+/**
+ * The components with a keyword the query contains or that contains the
+ * query, each once.
+ */
+export function resolveKeywords(
+ index: ReadonlyMap<string, ReadonlyArray<string>>,
+ query: string,
+): string[] {
+ const lower = query.toLowerCase();
+ const resolved: string[] = [];
+ for (const [keyword, names] of index) {
+ if (lower.includes(keyword) || keyword.includes(lower)) {
+ resolved.push(...names);
+ }
+ }
+ return [...new Set(resolved)];
+}
diff --git a/apps/docsite/src/app/mcp/route.ts b/apps/docsite/src/app/mcp/route.ts
index 91c47b1c73..06e705d660 100644
--- a/apps/docsite/src/app/mcp/route.ts
+++ b/apps/docsite/src/app/mcp/route.ts
@@ -22,6 +22,7 @@ import {components} from '../../generated/componentRegistry';
import {docTopics} from '../../generated/docsRegistry';
import {blocks} from '../../generated/blockRegistry';
import {templates} from '../../generated/templateRegistry';
+import {buildKeywordIndex, resolveKeywords} from './keywordIndex';
import type {ComponentEntry} from '../../generated/componentRegistry';
import type {DocTopic} from '../../generated/docsRegistry';
@@ -46,18 +47,7 @@ function componentInstall(comp: ComponentEntry): string {
// Built from the `keywords` field on each component's .doc.mjs file.
// Inverts keyword[] → component name so natural language queries resolve
// to the right components without a hardcoded alias map.
-const keywordIndex: Record<string, string[]> = {};
-for (const comp of visibleComponents) {
- for (const kw of comp.keywords) {
- const lower = kw.toLowerCase();
- if (!keywordIndex[lower]) {
- keywordIndex[lower] = [];
- }
- if (!keywordIndex[lower].includes(comp.name)) {
- keywordIndex[lower].push(comp.name);
- }
- }
-}
+const keywordIndex = buildKeywordIndex(visibleComponents);
// ── Scoring ────────────────────────────────────────────────────────────
@@ -100,21 +90,6 @@ function score(text: string, query: string): number {
return 0;
}
-/** Resolve keywords from component docs to boost matching components */
-function resolveKeywords(query: string): string[] {
- const lower = query.toLowerCase();
- const resolved: string[] = [];
-
- // Check each keyword in the index
- for (const [keyword, componentNames] of Object.entries(keywordIndex)) {
- if (lower.includes(keyword) || keyword.includes(lower)) {
- resolved.push(...componentNames);
- }
- }
-
- return [...new Set(resolved)];
-}
-
// ── Context Budget ─────────────────────────────────────────────────────
const MAX_TOPIC_BRIEF_CHARS = 4000;
@@ -135,7 +110,7 @@ const handler = createMcpHandler(
limit: z.number().optional().describe('Max results (default 8).'),
},
async ({query, limit = 8}) => {
- const keywordMatches = resolveKeywords(query);
+ const keywordMatches = resolveKeywords(keywordIndex, query);
const scored: Array<{
item: ComponentEntry | DocTopic | TemplateEntry;
@@ -530,7 +505,7 @@ const handler = createMcpHandler(
}
// ── Fuzzy fallback with keyword awareness ──────────────────────
- const keywordResolved = resolveKeywords(name);
+ const keywordResolved = resolveKeywords(keywordIndex, name);
const keywordComponents =
keywordResolved.length > 0
? visibleComponents