@splunk/splunk-ui-mcp 0.1.0 → 0.2.0

package/lib/utils/component-catalog.js

@@ -1,7 +1,11 @@
 import { readFileSync } from 'fs';
-import { join, dirname, resolve, relative, isAbsolute } from 'path';
-import { createRequire } from 'module';
+import { join, resolve, relative, isAbsolute } from 'path';
+import { filterByKeywords } from '@splunk/ui-utils/filter.js';
+import { resolvePackageAssetPath } from "./package-assets.js";
 let componentCache = null;
+let componentNameCache = null;
+let componentInfoByNormalizedNameCache = null;
+let componentSearchIndexCache = null;
 let docsLlmPath = null;
 /**
  * Override the docs-llm path (primarily for testing)
@@ -10,15 +14,31 @@ let docsLlmPath = null;
 export function setDocsLlmPath(path) {
     docsLlmPath = path;
     componentCache = null; // Clear cache when path changes
+    componentNameCache = null;
+    componentInfoByNormalizedNameCache = null;
+    componentSearchIndexCache = null;
 }
 /**
  * Sanitizes component names; Rejects names containing path separators or parent directory references
  */
 function sanitizeComponentName(name) {
-    if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    const sanitizedName = name.trim();
+    if (sanitizedName.includes('/') ||
+        sanitizedName.includes('\\') ||
+        sanitizedName.includes('..')) {
         throw new Error(`Invalid component name: "${name}".`);
     }
-    return name;
+    return sanitizedName;
+}
+/**
+ * Normalizes component names for case-insensitive and format-insensitive matching.
+ * Examples:
+ * - "Card Layout" -> "cardlayout"
+ * - "CardLayout" -> "cardlayout"
+ * - "card-layout" -> "cardlayout"
+ */
+export function normalizeComponentName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
 }
 /**
  * Resolves the path to the @splunk/react-ui/docs-llm directory
@@ -31,23 +51,8 @@ function resolveDocsLlmPath() {
     if (docsLlmPath) {
         return docsLlmPath;
     }
-    // Try resolving from the user's project first
-    try {
-        const require = createRequire(join(process.cwd(), 'package.json'));
-        const reactUiPackagePath = require.resolve('@splunk/react-ui/package.json');
-        const reactUiPath = dirname(reactUiPackagePath);
-        docsLlmPath = join(reactUiPath, 'docs-llm');
-        return docsLlmPath;
-    }
-    catch {
-        // Project doesn't have @splunk/react-ui installed, fall back to MCP's bundled version
-    }
-    // Fall back to MCP's bundled version (for standalone usage via setup tool)
     try {
-        const require = createRequire(import.meta.url);
-        const reactUiPackagePath = require.resolve('@splunk/react-ui/package.json');
-        const reactUiPath = dirname(reactUiPackagePath);
-        docsLlmPath = join(reactUiPath, 'docs-llm');
+        docsLlmPath = resolvePackageAssetPath('@splunk/react-ui', 'docs-llm');
         return docsLlmPath;
     }
     catch (error) {
@@ -93,24 +98,67 @@ function parseComponentCatalog() {
  * Returns the cached list of all components
  */
 export function getComponentList() {
-    if (!componentCache) {
-        componentCache = parseComponentCatalog();
-    }
+    componentCache ??= parseComponentCatalog();
     return componentCache;
 }
 /**
- * Checks if a component exists in the catalog
+ * Returns the cached list of component names
  */
-export function componentExists(componentName) {
-    const components = getComponentList();
-    return components.some((c) => c.name === componentName);
+export function getComponentNames() {
+    componentNameCache ??= getComponentList().map((component) => component.name);
+    return componentNameCache;
+}
+function getComponentInfoByNormalizedNameMap() {
+    componentInfoByNormalizedNameCache ??= new Map(getComponentList().map((component) => [normalizeComponentName(component.name), component]));
+    return componentInfoByNormalizedNameCache;
+}
+function getComponentSearchIndex() {
+    componentSearchIndexCache ??= getComponentList().map((component) => {
+        const nameSearchText = component.name;
+        const nameAndCategorySearchText = component.category
+            ? `${component.name} ${component.category}`
+            : component.name;
+        return {
+            component,
+            nameSearchText,
+            nameAndCategorySearchText,
+            normalizedNameSearchText: normalizeComponentName(nameSearchText),
+            normalizedNameAndCategorySearchText: normalizeComponentName(nameAndCategorySearchText),
+        };
+    });
+    return componentSearchIndexCache;
+}
+/**
+ * Finds components by keyword and normalized substring matching.
+ */
+export function searchComponents(query, { limit, includeCategory } = {}) {
+    const input = query.trim();
+    const normalizedInput = normalizeComponentName(input);
+    if (!normalizedInput) {
+        return [];
+    }
+    const searchIndex = getComponentSearchIndex();
+    const keywordMatches = filterByKeywords(searchIndex, input, (entry) => includeCategory ? entry.nameAndCategorySearchText : entry.nameSearchText).map((entry) => entry.component.name);
+    const normalizedMatches = searchIndex
+        .filter((entry) => (includeCategory
+        ? entry.normalizedNameAndCategorySearchText
+        : entry.normalizedNameSearchText).includes(normalizedInput))
+        .map((entry) => entry.component.name);
+    const uniqueMatches = [...new Set([...normalizedMatches, ...keywordMatches])];
+    if (limit && limit > 0) {
+        return uniqueMatches.slice(0, limit);
+    }
+    return uniqueMatches;
 }
 /**
  * Gets component info by name
  */
 export function getComponentInfo(componentName) {
-    const components = getComponentList();
-    return components.find((c) => c.name === componentName);
+    const normalizedInput = normalizeComponentName(componentName);
+    if (!normalizedInput) {
+        return undefined;
+    }
+    return getComponentInfoByNormalizedNameMap().get(normalizedInput);
 }
 /**
  * Reads the markdown documentation for a component

package/lib/utils/design-token-catalog.d.ts

@@ -0,0 +1,33 @@
+export type DesignTokenRecord = {
+    name: string;
+    description?: string;
+    type?: string;
+    deprecated?: boolean | string;
+    defaultValue: unknown;
+    overrideCount: number;
+    hasOverrides: boolean;
+    overridesByContext: Record<string, unknown>;
+};
+/**
+ * Override the tokens.json path (primarily for testing)
+ * @internal
+ */
+export declare function setTokensPath(path: string | null): void;
+/**
+ * Extracts the replacement token name from a deprecation message.
+ *
+ * Deprecation messages that include a replacement follow the format defined in
+ * `@splunk/themes` deprecated.ts: `Use \`replacementTokenName\``
+ * This format is also relied upon by `@splunk/eslint-plugin-splunk-ui` for auto-fixing.
+ */
+export declare function extractReplacementTokenName(deprecated: boolean | string | undefined): string | undefined;
+export declare function isDeprecatedToken(token: DesignTokenRecord): boolean;
+export declare function getDesignTokenList(): DesignTokenRecord[];
+export declare function getDesignTokenInfo(tokenName: string): DesignTokenRecord | undefined;
+/**
+ * Search for design tokens matching the given query.
+ *
+ * Never returns deprecated tokens — use `getDesignTokenInfo` for direct lookup by name
+ * if you need to retrieve a token regardless of its deprecation status.
+ */
+export declare function findDesignTokens(query: string): DesignTokenRecord[];

package/lib/utils/design-token-catalog.js

@@ -0,0 +1,158 @@
+import { readFileSync } from 'fs';
+import { addSearchData, search } from '@splunk/ui-utils/search.js';
+import { resolvePackageAssetPath } from "./package-assets.js";
+let designTokenCache = null;
+let tokenSearchIndex = null;
+let tokensPath = null;
+/**
+ * Override the tokens.json path (primarily for testing)
+ * @internal
+ */
+export function setTokensPath(path) {
+    tokensPath = path;
+    designTokenCache = null;
+    tokenSearchIndex = null;
+}
+function resolveTokensPath() {
+    if (tokensPath) {
+        return tokensPath;
+    }
+    try {
+        tokensPath = resolvePackageAssetPath('@splunk/themes', 'tokens.json');
+        return tokensPath;
+    }
+    catch (error) {
+        throw new Error('@splunk/themes tokens.json not found. ' +
+            'Either install it in your project (npm install @splunk/themes) ' +
+            'or ensure the MCP was installed with peer dependencies.\n' +
+            `Error: ${error.message}`);
+    }
+}
+const upsertTokenRecord = (tokenMap, tokenName, token, options = {}) => {
+    const existing = tokenMap.get(tokenName);
+    const next = existing ?? {
+        name: tokenName,
+        defaultValue: token.$value,
+        overrideCount: 0,
+        hasOverrides: false,
+        overridesByContext: {},
+    };
+    if (next.description == null && token.$description) {
+        next.description = token.$description;
+    }
+    if (next.type == null && token.$type) {
+        next.type = token.$type;
+    }
+    if (next.deprecated == null &&
+        token.$deprecated != null &&
+        (existing == null || options.allowDeprecatedOverride !== false)) {
+        next.deprecated = token.$deprecated;
+    }
+    // Use the first available value as default fallback if a base token isn't present.
+    if (next.defaultValue == null && token.$value != null) {
+        next.defaultValue = token.$value;
+    }
+    tokenMap.set(tokenName, next);
+    return next;
+};
+const getBaseSources = (resolverDoc) => {
+    const explicitBase = resolverDoc.sets?.base?.sources;
+    if (explicitBase) {
+        return explicitBase;
+    }
+    const firstSet = Object.values(resolverDoc.sets ?? {})[0];
+    return firstSet?.sources ?? [];
+};
+const parseDesignTokens = (resolverDoc) => {
+    const tokenMap = new Map();
+    getBaseSources(resolverDoc).forEach((tokenSource) => {
+        Object.entries(tokenSource).forEach(([tokenName, token]) => {
+            upsertTokenRecord(tokenMap, tokenName, token);
+        });
+    });
+    Object.values(resolverDoc.modifiers ?? {}).forEach((modifier) => {
+        Object.entries(modifier.contexts ?? {}).forEach(([contextName, tokenSources]) => {
+            tokenSources.forEach((tokenSource) => {
+                Object.entries(tokenSource).forEach(([tokenName, token]) => {
+                    const record = upsertTokenRecord(tokenMap, tokenName, token, {
+                        allowDeprecatedOverride: false,
+                    });
+                    if (!(contextName in record.overridesByContext)) {
+                        record.overridesByContext[contextName] = token.$value;
+                        record.overrideCount += 1;
+                        record.hasOverrides = true;
+                    }
+                });
+            });
+        });
+    });
+    return Array.from(tokenMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+};
+const buildSearchIndex = (tokens) => addSearchData(tokens.map((token) => ({
+    name: token.name,
+    description: token.description,
+    keywords: [token.type, token.deprecated != null ? 'deprecated' : '', 'design token']
+        .filter(Boolean)
+        .join(' '),
+    token,
+})));
+const getCachedTokens = () => {
+    if (!designTokenCache) {
+        const resolvedTokensPath = resolveTokensPath();
+        const rawContent = readFileSync(resolvedTokensPath, 'utf-8');
+        let tokenSpec;
+        try {
+            tokenSpec = JSON.parse(rawContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse tokens.json at "${resolvedTokensPath}". ` +
+                `The file may be malformed or from an incompatible version of @splunk/themes.\n` +
+                `Error: ${error.message}`);
+        }
+        designTokenCache = parseDesignTokens(tokenSpec);
+        tokenSearchIndex = buildSearchIndex(designTokenCache);
+    }
+    return designTokenCache;
+};
+/**
+ * Extracts the replacement token name from a deprecation message.
+ *
+ * Deprecation messages that include a replacement follow the format defined in
+ * `@splunk/themes` deprecated.ts: `Use \`replacementTokenName\``
+ * This format is also relied upon by `@splunk/eslint-plugin-splunk-ui` for auto-fixing.
+ */
+export function extractReplacementTokenName(deprecated) {
+    if (typeof deprecated !== 'string') {
+        return undefined;
+    }
+    const match = deprecated.match(/^Use `([^`]+)`$/);
+    return match?.[1];
+}
+export function isDeprecatedToken(token) {
+    return (token.deprecated === true ||
+        (typeof token.deprecated === 'string' && token.deprecated.trim().length > 0));
+}
+export function getDesignTokenList() {
+    return getCachedTokens();
+}
+export function getDesignTokenInfo(tokenName) {
+    return getCachedTokens().find((token) => token.name === tokenName);
+}
+/**
+ * Search for design tokens matching the given query.
+ *
+ * Never returns deprecated tokens — use `getDesignTokenInfo` for direct lookup by name
+ * if you need to retrieve a token regardless of its deprecation status.
+ */
+export function findDesignTokens(query) {
+    const trimmed = query.trim();
+    if (!trimmed) {
+        return [];
+    }
+    const tokens = getCachedTokens();
+    if (!tokenSearchIndex) {
+        tokenSearchIndex = buildSearchIndex(tokens);
+    }
+    const results = search(trimmed, tokenSearchIndex);
+    return results.map((result) => result.token).filter((token) => !isDeprecatedToken(token));
+}

package/lib/utils/package-assets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolves an asset file from a package.
+ *
+ * Resolution order:
+ * 1. User's project node_modules
+ * 2. MCP's bundled dependencies
+ */
+export declare function resolvePackageAssetPath(packageName: string, assetPath: string): string;

package/lib/utils/package-assets.js

@@ -0,0 +1,35 @@
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+const resolverModes = ['project', 'bundled'];
+const getPackageRootFrom = (packageName, mode) => {
+    const require = mode === 'project'
+        ? createRequire(join(process.cwd(), 'package.json'))
+        : createRequire(import.meta.url);
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    return dirname(packageJsonPath);
+};
+/**
+ * Resolves an asset file from a package.
+ *
+ * Resolution order:
+ * 1. User's project node_modules
+ * 2. MCP's bundled dependencies
+ */
+export function resolvePackageAssetPath(packageName, assetPath) {
+    const errors = [];
+    let packageRoot = null;
+    resolverModes.find((mode) => {
+        try {
+            packageRoot = getPackageRootFrom(packageName, mode);
+            return true;
+        }
+        catch (error) {
+            errors.push(`${mode}: ${error.message}`);
+            return false;
+        }
+    });
+    if (packageRoot) {
+        return join(packageRoot, assetPath);
+    }
+    throw new Error(`Failed to resolve "${assetPath}" from ${packageName}. Tried project and bundled package resolution.\n${errors.join('\n')}`);
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@splunk/splunk-ui-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Model Context Protocol server for the Splunk UI Design System",
   "license": "Apache-2.0",
   "author": "Splunk Inc.",
   "scripts": {
     "prebuild": "node scripts/generate-versions.js",
-    "build": "tsc",
+    "build": "yarn types:build && tsc -p tsconfig.json",
     "docs": "NODE_ENV=production webpack --config docs.gen.webpack.config.cjs",
     "docs:publish": "eval $(splunk-docs-package docs) && artifact-ci publish generic $DOCS_GEN_OUTPUT_NAME $DOCS_GEN_REMOTE_PATH",
     "docs:publish:external": "eval $(splunk-docs-package docs-external --suffix=public) && artifact-ci publish generic $DOCS_GEN_OUTPUT_NAME $DOCS_GEN_REMOTE_PATH",
@@ -14,7 +14,8 @@
     "lint": "eslint src --ext \".ts,.tsx,.js,.jsx\"",
     "lint:ci": "yarn run lint -- -f junit -o test-reports/lint-results.xml",
     "start": "tsc --watch",
-    "test": "vitest run"
+    "test": "vitest run",
+    "types:build": "tsc -p tsconfig.check.json"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -23,21 +24,24 @@
     "splunk-ui-mcp": "lib/index.js"
   },
   "files": [
-    "lib"
+    "lib",
+    "!lib/**/tests/**"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.5",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@splunk/ui-utils": "^1.12.0",
-    "zod": "^3.0.0"
+    "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@splunk/react-icons": "^5.8.0",
-    "@splunk/react-ui": "^5.8.0"
+    "@splunk/react-icons": "^5.9.0",
+    "@splunk/react-ui": "^5.9.0",
+    "@splunk/themes": "^1.6.0"
   },
   "devDependencies": {
     "@splunk/eslint-config": "^5.0.0",
-    "@splunk/react-icons": "^5.8.0",
-    "@splunk/react-ui": "^5.8.0",
+    "@splunk/react-icons": "^5.9.0",
+    "@splunk/react-ui": "^5.9.0",
+    "@splunk/themes": "^1.6.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^8.29.1",
     "@typescript-eslint/parser": "^8.29.1",

package/lib/resources/tests/components.unit.d.ts

@@ -1 +0,0 @@
-export {};

package/lib/resources/tests/components.unit.js

@@ -1,133 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-const MOCK_COMPONENT_LIST = [
-    {
-        name: 'Button',
-        filename: 'Button.md',
-        category: 'Base',
-    },
-    {
-        name: 'Card Layout',
-        filename: 'Card Layout.md',
-        category: 'Base',
-    },
-    {
-        name: 'Text',
-        filename: 'Text.md',
-        category: 'Data Entry',
-    },
-];
-const MOCK_BUTTON_DOCS = `# Button
-
-## Overview
-
-A button component for triggering actions.
-
-## Examples
-
-\`\`\`typescript
-import Button from '@splunk/react-ui/Button';
-\`\`\`
-`;
-// Mock the component catalog module
-vi.mock('../../utils/component-catalog.ts', () => ({
-    getComponentList: vi.fn(() => MOCK_COMPONENT_LIST),
-    getComponentInfo: vi.fn((name) => MOCK_COMPONENT_LIST.find((c) => c.name === name)),
-    getComponentDocs: vi.fn((name) => {
-        if (name === 'Button') {
-            return MOCK_BUTTON_DOCS;
-        }
-        throw new Error(`Component "${name}" not found in catalog`);
-    }),
-}));
-describe('createComponentResourceUri', () => {
-    it('builds an encoded MCP URI for the provided component name', async () => {
-        const { createComponentResourceUri, COMPONENT_RESOURCE_URI_BASE } = await import("../components.js");
-        expect(createComponentResourceUri('Button')).toBe(`${COMPONENT_RESOURCE_URI_BASE}/Button`);
-        expect(createComponentResourceUri('Card Layout')).toBe(`${COMPONENT_RESOURCE_URI_BASE}/Card%20Layout`);
-    });
-});
-describe('component resources', () => {
-    beforeEach(() => {
-        vi.resetModules();
-    });
-    describe('createComponentResourceLink', () => {
-        it('includes catalog metadata when the component exists', async () => {
-            const { createComponentResourceLink, createComponentResourceUri } = await import("../components.js");
-            const link = createComponentResourceLink('Button');
-            expect(link).toMatchObject({
-                type: 'resource_link',
-                name: 'Button',
-                title: 'Button',
-                uri: createComponentResourceUri('Button'),
-                description: 'Base component',
-                mimeType: 'text/markdown',
-            });
-        });
-        it('creates a resource link even if the component is unknown', async () => {
-            const { createComponentResourceLink, createComponentResourceUri } = await import("../components.js");
-            const link = createComponentResourceLink('Unknown');
-            expect(link).toMatchObject({
-                type: 'resource_link',
-                name: 'Unknown',
-                title: 'Unknown',
-                uri: createComponentResourceUri('Unknown'),
-                mimeType: 'text/markdown',
-            });
-        });
-    });
-    describe('component resource handler', () => {
-        it('reads component documentation by name', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const url = new URL('mcp://splunk-ui/components/Button');
-            const result = componentResource.handler(url, {
-                componentName: 'Button',
-            });
-            expect(result.contents).toHaveLength(1);
-            expect(result.contents[0]).toMatchObject({
-                mimeType: 'text/markdown',
-                text: MOCK_BUTTON_DOCS,
-            });
-        });
-        it('extracts component name from URL path if param is missing', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const url = new URL('mcp://splunk-ui/components/Button');
-            const result = componentResource.handler(url, {});
-            expect(result.contents).toHaveLength(1);
-            expect(result.contents[0]).toMatchObject({
-                mimeType: 'text/markdown',
-                text: MOCK_BUTTON_DOCS,
-            });
-        });
-        it('throws error when component name is missing', async () => {
-            const componentResource = (await import("../components.js")).default;
-            // URL with no component in path
-            const url = new URL('mcp://splunk-ui/components');
-            expect(() => componentResource.handler(url, {})).toThrow('Component name missing in resource request');
-        });
-        it('throws error for unknown component', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const url = new URL('mcp://splunk-ui/components/Unknown');
-            expect(() => componentResource.handler(url, { componentName: 'Unknown' })).toThrow('Unknown component "Unknown"');
-        });
-    });
-    describe('component resource template', () => {
-        it('autocompletes component names', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const complete = componentResource.template.completeCallback?.('componentName');
-            const completions = (await complete?.('b')) ?? [];
-            expect(completions).toEqual(['Button']);
-        });
-        it('autocompletes with partial matches', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const complete = componentResource.template.completeCallback?.('componentName');
-            const completions = (await complete?.('card')) ?? [];
-            expect(completions).toContain('Card Layout');
-        });
-        it('returns empty array when no matches found for autocomplete', async () => {
-            const componentResource = (await import("../components.js")).default;
-            const complete = componentResource.template.completeCallback?.('componentName');
-            const completions = (await complete?.('xyz')) ?? [];
-            expect(completions).toEqual([]);
-        });
-    });
-});

package/lib/resources/tests/icons.unit.d.ts

@@ -1 +0,0 @@
-export {};