@splunk/splunk-ui-mcp 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ A Model Context Protocol (MCP) server that gives AI assistants Splunk UI Design
 
 - Node.js 22 or newer
 - An MCP-compatible client (VS Code, Cursor, Windsurf, Claude Desktop, Goose, etc.)
-- Access to @splunk/react-ui and @splunk/react-icons (used for component docs and icon metadata)
+- Access to @splunk/react-ui, @splunk/react-icons, and @splunk/themes
 
 ## Install and configure
 
@@ -35,8 +35,9 @@ If you need the underlying tool or resource names (for debugging or client integ
 
 ### Tools
 
-- `get_component_docs`: Retrieve full docs for a `@splunk/react-ui` component.
-- `find_icons`: Search `@splunk/react-icons` and return a recommended icon plus alternatives.
+- `find_component`: Find `@splunk/react-ui` components by exact name or fuzzy query; returns full docs for exact matches and suggestions otherwise.
+- `find_icon`: Search `@splunk/react-icons` and return a recommended icon plus alternatives.
+- `find_design_token`: Search `@splunk/themes` design tokens and return recommended matches.
 - `list_splunk_ui_requirements`: Return version requirements and peer dependencies.
 
 ### Resources
@@ -52,3 +53,9 @@ mcp://splunk-ui/components/{componentName}
 ```
 mcp://splunk-ui/icons/{iconName}
 ```
+
+**Design tokens**
+
+```
+mcp://splunk-ui/design-tokens/{tokenName}
+```

package/lib/constants/versions.js

@@ -2,11 +2,11 @@
 // This file contains version information that gets injected at build time
 // DO NOT EDIT MANUALLY - this file is auto-generated during build
 const VERSIONS = {
-    "@splunk/react-ui": "5.8.0",
+    "@splunk/react-ui": "5.9.0",
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0",
     "styled-components": "^5.3.10",
-    "@splunk/themes": "1.5.0",
-    "@splunk/react-icons": "5.8.0"
+    "@splunk/themes": "1.6.0",
+    "@splunk/react-icons": "5.9.0"
 };
 export default VERSIONS;

package/lib/index.js

@@ -2,10 +2,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import requirements from "./tools/requirements.js";
-import findIcons from "./tools/find_icons.js";
-import getComponentDocs from "./tools/get_component_docs.js";
+import findIcon from "./tools/find_icon.js";
+import findComponent from "./tools/find_component.js";
+import findDesignToken from "./tools/find_design_token.js";
 import iconResource from "./resources/icons.js";
 import componentResource from "./resources/components.js";
+import designTokenResource from "./resources/design-tokens.js";
 // prettier-ignore
 import packageJson from '../package.json' with { type: 'json' };
 // Create an MCP server
@@ -19,11 +21,11 @@ const server = new McpServer({
     },
 });
 // Register all tools
-const tools = [requirements, findIcons, getComponentDocs];
+const tools = [requirements, findIcon, findComponent, findDesignToken];
 tools.forEach((tool) => {
     server.registerTool(tool.name, tool.config, tool.handler);
 });
-const resources = [iconResource, componentResource];
+const resources = [iconResource, componentResource, designTokenResource];
 resources.forEach((resource) => {
     server.registerResource(resource.name, resource.template, resource.config, resource.handler);
 });

package/lib/resources/components.js

@@ -1,8 +1,8 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { filterByKeywords } from '@splunk/ui-utils/filter.js';
-import { getComponentList, getComponentDocs, getComponentInfo, } from "../utils/component-catalog.js";
+import { getComponentList, getComponentNames, getComponentDocs, getComponentInfo, searchComponents, } from "../utils/component-catalog.js";
 export const COMPONENT_RESOURCE_NAME = 'splunk-ui-components';
 export const COMPONENT_RESOURCE_URI_BASE = 'mcp://splunk-ui/components';
+const CATEGORY_SEARCH_MIN_QUERY_LENGTH = 3;
 /**
  * Creates an MCP resource URI for a component
  */
@@ -76,12 +76,13 @@ const componentResourceTemplate = new ResourceTemplate(`${COMPONENT_RESOURCE_URI
     complete: {
         componentName: async (value) => {
             const input = value?.toString() ?? '';
+            const componentNames = getComponentNames();
+            const includeCategory = input.trim().length >= CATEGORY_SEARCH_MIN_QUERY_LENGTH;
             // Return all component names if no input is provided
             if (!input) {
-                return getComponentList().map((component) => component.name);
+                return componentNames;
             }
-            const componentNames = getComponentList().map((component) => component.name);
-            return filterByKeywords(componentNames, input);
+            return searchComponents(input, { includeCategory });
         },
     },
 });
@@ -101,7 +102,12 @@ const componentResource = {
         // Prefer the componentName param, but fall back to extracting from the path.
         let componentName;
         if (typeof componentNameParam === 'string' && componentNameParam.length > 0) {
-            componentName = componentNameParam;
+            try {
+                componentName = decodeURIComponent(componentNameParam);
+            }
+            catch {
+                throw new Error(`Invalid component name in resource params: ${componentNameParam}`);
+            }
         }
         else {
             // Extract from path, but exclude 'components' itself

package/lib/resources/design-tokens.d.ts

@@ -0,0 +1,17 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ResourceLink, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const DESIGN_TOKEN_RESOURCE_NAME = "splunk-ui-design-tokens";
+export declare const DESIGN_TOKEN_RESOURCE_URI_BASE = "mcp://splunk-ui/design-tokens";
+export declare const createDesignTokenResourceUri: (tokenName: string) => string;
+export declare const createDesignTokenResourceLink: (tokenName: string) => ResourceLink;
+declare const designTokenResource: {
+    name: string;
+    template: ResourceTemplate;
+    config: {
+        title: string;
+        description: string;
+        mimeType: string;
+    };
+    handler: (uri: URL, params: Record<string, unknown>) => ReadResourceResult;
+};
+export default designTokenResource;

package/lib/resources/design-tokens.js

@@ -0,0 +1,113 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { filterByKeywords, stringToKeywords } from '@splunk/ui-utils/filter.js';
+import { extractReplacementTokenName, getDesignTokenInfo, getDesignTokenList, } from "../utils/design-token-catalog.js";
+export const DESIGN_TOKEN_RESOURCE_NAME = 'splunk-ui-design-tokens';
+export const DESIGN_TOKEN_RESOURCE_URI_BASE = 'mcp://splunk-ui/design-tokens';
+export const createDesignTokenResourceUri = (tokenName) => `${DESIGN_TOKEN_RESOURCE_URI_BASE}/${encodeURIComponent(tokenName)}`;
+const createDesignTokenResourceMetadata = (tokenName) => {
+    return {
+        name: tokenName,
+        title: tokenName,
+        uri: createDesignTokenResourceUri(tokenName),
+        description: getDesignTokenInfo(tokenName)?.description,
+        mimeType: 'application/json',
+    };
+};
+export const createDesignTokenResourceLink = (tokenName) => ({
+    type: 'resource_link',
+    ...createDesignTokenResourceMetadata(tokenName),
+});
+const createDesignTokenResourcePayload = (token) => {
+    const replacementToken = extractReplacementTokenName(token.deprecated);
+    return {
+        name: token.name,
+        description: token.description,
+        type: token.type,
+        deprecated: token.deprecated,
+        usage: `variables.${token.name}`,
+        replacementToken,
+        replacementUsage: replacementToken ? `variables.${replacementToken}` : undefined,
+    };
+};
+const createListResult = () => ({
+    resources: getDesignTokenList().map((token) => ({
+        name: token.name,
+        title: token.name,
+        uri: createDesignTokenResourceUri(token.name),
+        description: token.description,
+        mimeType: 'application/json',
+    })),
+});
+const readDesignTokenResource = (tokenName) => {
+    const token = getDesignTokenInfo(tokenName);
+    if (!token) {
+        throw new Error(`Unknown design token "${tokenName}"`);
+    }
+    const resourcePayload = createDesignTokenResourcePayload(token);
+    return {
+        contents: [
+            {
+                uri: createDesignTokenResourceUri(token.name),
+                mimeType: 'application/json',
+                text: `${JSON.stringify(resourcePayload, null, 2)}\n`,
+            },
+        ],
+    };
+};
+const designTokenResourceTemplate = new ResourceTemplate(`${DESIGN_TOKEN_RESOURCE_URI_BASE}/{tokenName}`, {
+    list: async () => createListResult(),
+    complete: {
+        tokenName: async (value) => {
+            const input = value?.toString() ?? '';
+            const tokenNames = getDesignTokenList().map((token) => token.name);
+            if (!input) {
+                return tokenNames.slice(0, 50);
+            }
+            if (stringToKeywords(input).filter(Boolean).length === 0) {
+                return [];
+            }
+            return filterByKeywords(tokenNames, input).slice(0, 50);
+        },
+    },
+});
+const designTokenResource = {
+    name: DESIGN_TOKEN_RESOURCE_NAME,
+    template: designTokenResourceTemplate,
+    config: {
+        title: 'Splunk UI Design Tokens',
+        description: 'Metadata and usage guidance for design tokens from @splunk/themes.',
+        mimeType: 'application/json',
+    },
+    handler: (uri, params) => {
+        const { tokenName: tokenNameParam } = params;
+        let tokenName;
+        if (typeof tokenNameParam === 'string' && tokenNameParam.length > 0) {
+            try {
+                tokenName = decodeURIComponent(tokenNameParam);
+            }
+            catch {
+                throw new Error(`Invalid design token name in resource params: ${tokenNameParam}`);
+            }
+        }
+        else {
+            const pathParts = uri.pathname.split('/').filter(Boolean);
+            const encodedTokenName = pathParts[pathParts.length - 1];
+            if (encodedTokenName === 'design-tokens') {
+                tokenName = undefined;
+            }
+            else if (encodedTokenName) {
+                try {
+                    tokenName = decodeURIComponent(encodedTokenName);
+                }
+                catch {
+                    throw new Error(`Invalid design token name in resource path: ${encodedTokenName}`);
+                }
+            }
+        }
+        if (!tokenName) {
+            throw new Error(`Design token name missing in resource request: ${uri.toString()}`);
+        }
+        return readDesignTokenResource(tokenName);
+    },
+};
+export default designTokenResource;

package/lib/tools/find_component.d.ts

@@ -0,0 +1,19 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+export declare const findComponentHandler: ({ query }: {
+    query?: string;
+}) => CallToolResult;
+declare const findComponentTool: {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: {
+            query: z.ZodString;
+        };
+    };
+    handler: ({ query }: {
+        query?: string;
+    }) => CallToolResult;
+};
+export default findComponentTool;

package/lib/tools/find_component.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { createComponentResourceLink } from "../resources/components.js";
+import { getComponentDocs, getComponentInfo, getComponentNames, searchComponents, } from "../utils/component-catalog.js";
+const MAX_SUGGESTIONS = 5;
+const MAX_EXAMPLES = 10;
+const CATEGORY_SEARCH_MIN_QUERY_LENGTH = 3;
+const getSuggestedComponents = (trimmedQuery) => {
+    const includeCategory = trimmedQuery.length >= CATEGORY_SEARCH_MIN_QUERY_LENGTH;
+    return searchComponents(trimmedQuery, {
+        includeCategory,
+        limit: MAX_SUGGESTIONS,
+    });
+};
+export const findComponentHandler = ({ query }) => {
+    if (!query || query.trim().length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Component query is required. Provide a component name or keywords.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const normalizedQuery = query.trim();
+    const componentInfo = getComponentInfo(normalizedQuery);
+    if (componentInfo) {
+        try {
+            const docs = getComponentDocs(componentInfo.name);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: docs,
+                    },
+                    createComponentResourceLink(componentInfo.name),
+                ],
+                structuredContent: {
+                    query: normalizedQuery,
+                    resultType: 'exact',
+                    component: componentInfo.name,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve documentation for "${componentInfo.name}": ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    const suggestions = getSuggestedComponents(normalizedQuery);
+    const sampleNames = getComponentNames().slice(0, MAX_EXAMPLES).join(', ');
+    const hasSuggestions = suggestions.length > 0;
+    const suggestionText = hasSuggestions
+        ? `Top matches: ${suggestions.join(', ')}.\n\nUse one of the resource links below to open docs directly.`
+        : `No close matches found.\n\nAvailable components include: ${sampleNames}, and more.`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `No exact component match for "${normalizedQuery}".\n\n${suggestionText}`,
+            },
+            ...suggestions.map((name) => createComponentResourceLink(name)),
+        ],
+        structuredContent: {
+            query: normalizedQuery,
+            resultType: 'suggestions',
+            suggestions,
+        },
+    };
+};
+const findComponentTool = {
+    name: 'find_component',
+    config: {
+        title: 'Find Component Documentation',
+        description: 'Finds @splunk/react-ui components by exact name or fuzzy query. ' +
+            'Returns full docs for exact matches and ranked suggestions for discovery queries.',
+        inputSchema: {
+            query: z
+                .string()
+                .describe('Component name or keywords (e.g., "Button", "CardLayout", "table", "form rows").'),
+        },
+    },
+    handler: findComponentHandler,
+};
+export default findComponentTool;

package/lib/tools/find_design_token.d.ts

@@ -0,0 +1,16 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+declare const findDesignTokenTool: {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: {
+            query: z.ZodString;
+        };
+    };
+    handler: ({ query }: {
+        query?: string;
+    }) => CallToolResult;
+};
+export default findDesignTokenTool;

package/lib/tools/find_design_token.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import { createDesignTokenResourceLink, createDesignTokenResourceUri, } from "../resources/design-tokens.js";
+import { extractReplacementTokenName, findDesignTokens, getDesignTokenInfo, isDeprecatedToken, } from "../utils/design-token-catalog.js";
+const NO_RESULTS_RESULT = {
+    content: [
+        {
+            type: 'text',
+            text: 'No design tokens found. Try keywords like "text", "background", "border", ' +
+                '"spacing", or "shadow".',
+        },
+    ],
+};
+const getReplacementToken = (token) => {
+    if (!token || !isDeprecatedToken(token)) {
+        return undefined;
+    }
+    const replacementTokenName = extractReplacementTokenName(token.deprecated);
+    return replacementTokenName ? getDesignTokenInfo(replacementTokenName) : undefined;
+};
+const addUsageReference = (token) => ({
+    name: token.name,
+    description: token.description,
+    type: token.type,
+    deprecated: token.deprecated,
+    usage: `variables.${token.name}`,
+});
+const formatTokenDetails = (token, options = {}) => {
+    const lines = [];
+    if (token.description) {
+        lines.push(`- Description: ${token.description}`);
+    }
+    if (token.type) {
+        lines.push(`- Type: \`${token.type}\``);
+    }
+    lines.push(`- Usage: \`variables.${token.name}\``);
+    if (isDeprecatedToken(token)) {
+        lines.push(options.deprecatedAsBoolean
+            ? '- Deprecated: true'
+            : `- Deprecated: ${String(token.deprecated)}`);
+    }
+    const resourceLabel = options.resourceLabel ?? 'Resource';
+    lines.push(`- ${resourceLabel}: \`${createDesignTokenResourceUri(token.name)}\``);
+    return lines.join('\n');
+};
+const findDesignTokenHandler = ({ query }) => {
+    const normalizedQuery = query?.trim() ?? '';
+    if (normalizedQuery.length === 0) {
+        return NO_RESULTS_RESULT;
+    }
+    const exactMatch = getDesignTokenInfo(normalizedQuery);
+    const deprecatedExactMatch = exactMatch && isDeprecatedToken(exactMatch) ? exactMatch : undefined;
+    const exactReplacement = deprecatedExactMatch
+        ? getReplacementToken(deprecatedExactMatch)
+        : undefined;
+    const searchResults = exactMatch ? [] : findDesignTokens(normalizedQuery);
+    if (!exactMatch && searchResults.length === 0) {
+        return NO_RESULTS_RESULT;
+    }
+    let results = searchResults;
+    if (exactReplacement) {
+        results = [exactReplacement];
+    }
+    else if (exactMatch) {
+        results = [exactMatch];
+    }
+    const [recommended, ...others] = results;
+    const alternativeTokens = others.slice(0, 4);
+    const summarySections = [];
+    if (exactMatch && !deprecatedExactMatch) {
+        summarySections.push(`# \`${exactMatch.name}\``, formatTokenDetails(recommended, { resourceLabel: 'Resource link' }), 'Follow the resource links below for full token metadata.');
+    }
+    else if (deprecatedExactMatch && !exactReplacement) {
+        const deprecatedGuidance = typeof deprecatedExactMatch.deprecated === 'string'
+            ? `Query matched deprecated token \`${deprecatedExactMatch.name}\`. ${deprecatedExactMatch.deprecated}`
+            : `Query matched deprecated token \`${deprecatedExactMatch.name}\`. No replacement recommendation is available from token metadata.`;
+        summarySections.push(`# \`${deprecatedExactMatch.name}\``, deprecatedGuidance, formatTokenDetails(recommended, { deprecatedAsBoolean: true }), 'Follow the resource links below for full token metadata.');
+    }
+    else if (deprecatedExactMatch && exactReplacement) {
+        const deprecatedGuidance = typeof deprecatedExactMatch.deprecated === 'string'
+            ? `Query matched deprecated token \`${deprecatedExactMatch.name}\`. ${deprecatedExactMatch.deprecated}`
+            : `Query matched deprecated token \`${deprecatedExactMatch.name}\`.`;
+        summarySections.push(`# \`${deprecatedExactMatch.name}\``, deprecatedGuidance, '## Recommended Token', `Recommended to use \`${recommended.name}\` for "${normalizedQuery}"`, formatTokenDetails(recommended), 'Follow the resource links below for full token metadata.');
+    }
+    else {
+        summarySections.push(`# Design Tokens for "${normalizedQuery}"`, '## Recommended Token', `Recommended to use \`${recommended.name}\` for "${normalizedQuery}"`, formatTokenDetails(recommended), 'Follow the resource links below for full token metadata.');
+    }
+    if (alternativeTokens.length > 0) {
+        summarySections.push('## Alternative Tokens', alternativeTokens
+            .map((token) => `- \`${token.name}\`${token.description ? `: ${token.description}` : ''}`)
+            .join('\n'));
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: summarySections.join('\n\n'),
+            },
+            createDesignTokenResourceLink(recommended.name),
+            ...alternativeTokens.map((token) => createDesignTokenResourceLink(token.name)),
+        ],
+        structuredContent: {
+            recommended: addUsageReference(getDesignTokenInfo(recommended.name) ?? recommended),
+            alternatives: alternativeTokens
+                .map((token) => getDesignTokenInfo(token.name) ?? token)
+                .filter((token) => !isDeprecatedToken(token))
+                .map((token) => addUsageReference(token)),
+        },
+    };
+};
+const findDesignTokenTool = {
+    name: 'find_design_token',
+    config: {
+        title: 'Find Design Tokens',
+        description: 'Search for a Splunk UI design token from @splunk/themes. ' +
+            'In Splunk UI projects, all styling must use styled-components and design tokens for CSS properties as much as possible — ' +
+            'never hardcode hex values, rgb(), or CSS custom properties like var(--something). ' +
+            'Call this tool whenever you need a color, spacing, typography, shadow, or z-index value.',
+        inputSchema: {
+            query: z
+                .string()
+                .describe('What you are trying to style, e.g. "button background", "paragraph text color", "input border", "modal background", "spacing between elements", "focus shadow".'),
+        },
+    },
+    handler: findDesignTokenHandler,
+};
+export default findDesignTokenTool;

package/lib/tools/{find_icons.d.ts → find_icon.d.ts}

@@ -1,6 +1,6 @@
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-declare const findIconsTool: {
+declare const findIconTool: {
     name: string;
     config: {
         title: string;
@@ -13,4 +13,4 @@ declare const findIconsTool: {
         query?: string;
     }) => CallToolResult;
 };
-export default findIconsTool;
+export default findIconTool;

package/lib/tools/{find_icons.js → find_icon.js}

@@ -30,7 +30,7 @@ const formatIconDetails = (details) => {
     lines.push(details.usageExample);
     return lines.join('\n');
 };
-const findIconsHandler = ({ query }) => {
+const findIconHandler = ({ query }) => {
     if (!query || query.trim().length === 0) {
         return NO_RESULTS_RESULT;
     }
@@ -86,8 +86,8 @@ const findIconsHandler = ({ query }) => {
         structuredContent,
     };
 };
-const findIconsTool = {
-    name: 'find_icons',
+const findIconTool = {
+    name: 'find_icon',
     config: {
         title: 'Find Icons',
         description: 'Search @splunk/react-icons for the best match and a few alternatives based on your keyword.',
@@ -97,6 +97,6 @@ const findIconsTool = {
                 .describe('The search query for the icon, e.g., "search", "notification", "user".'),
         },
     },
-    handler: findIconsHandler,
+    handler: findIconHandler,
 };
-export default findIconsTool;
+export default findIconTool;

package/lib/utils/component-catalog.d.ts

@@ -8,14 +8,30 @@ export type ComponentInfo = {
  * @internal
  */
 export declare function setDocsLlmPath(path: string | null): void;
+/**
+ * Normalizes component names for case-insensitive and format-insensitive matching.
+ * Examples:
+ * - "Card Layout" -> "cardlayout"
+ * - "CardLayout" -> "cardlayout"
+ * - "card-layout" -> "cardlayout"
+ */
+export declare function normalizeComponentName(name: string): string;
 /**
  * Returns the cached list of all components
  */
 export declare function getComponentList(): ComponentInfo[];
 /**
- * Checks if a component exists in the catalog
+ * Returns the cached list of component names
+ */
+export declare function getComponentNames(): string[];
+type SearchComponentsOptions = {
+    includeCategory?: boolean;
+    limit?: number;
+};
+/**
+ * Finds components by keyword and normalized substring matching.
  */
-export declare function componentExists(componentName: string): boolean;
+export declare function searchComponents(query: string, { limit, includeCategory }?: SearchComponentsOptions): string[];
 /**
  * Gets component info by name
  */
@@ -24,3 +40,4 @@ export declare function getComponentInfo(componentName: string): ComponentInfo |
  * Reads the markdown documentation for a component
  */
 export declare function getComponentDocs(componentName: string): string;
+export {};