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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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