@splunk/splunk-ui-mcp 0.1.0

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

@@ -0,0 +1,133 @@
+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

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

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

@@ -0,0 +1,161 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const ICON_CATALOG_FIXTURE = vi.hoisted(() => [
+    {
+        name: 'SearchIcon',
+        category: 'Interface',
+        description: 'Use for search interactions.',
+        keywords: 'search, magnify, find',
+        variants: ['default', 'filled'],
+    },
+    {
+        name: 'AlertIcon',
+        keywords: 'alert, warning',
+    },
+]);
+vi.mock('@splunk/react-icons/icon-catalog.json', () => ({
+    default: ICON_CATALOG_FIXTURE,
+}));
+describe('createIconResourceUri', () => {
+    it('builds an encoded MCP URI for the provided icon name', async () => {
+        const { createIconResourceUri, ICON_RESOURCE_URI_BASE } = await import("../icons.js");
+        expect(createIconResourceUri('SimpleIcon')).toBe(`${ICON_RESOURCE_URI_BASE}/SimpleIcon`);
+        expect(createIconResourceUri('Icon With Spaces')).toBe(`${ICON_RESOURCE_URI_BASE}/Icon%20With%20Spaces`);
+        expect(createIconResourceUri('Icon/Separators')).toBe(`${ICON_RESOURCE_URI_BASE}/Icon%2FSeparators`);
+    });
+});
+describe('icon resources', () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    describe('createIconResourceLink', () => {
+        it('includes catalog metadata when the icon exists', async () => {
+            const { createIconResourceLink, createIconResourceUri } = await import("../icons.js");
+            const link = createIconResourceLink('SearchIcon');
+            expect(link).toMatchObject({
+                type: 'resource_link',
+                name: 'SearchIcon',
+                title: 'SearchIcon',
+                uri: createIconResourceUri('SearchIcon'),
+                description: 'Use for search interactions.',
+                mimeType: 'application/json',
+            });
+        });
+        it('falls back to minimal metadata when the icon is unknown', async () => {
+            const { createIconResourceLink, createIconResourceUri } = await import("../icons.js");
+            const link = createIconResourceLink('MissingIcon');
+            expect(link).toMatchObject({
+                type: 'resource_link',
+                name: 'MissingIcon',
+                title: 'MissingIcon',
+                uri: createIconResourceUri('MissingIcon'),
+                description: undefined,
+                mimeType: 'application/json',
+            });
+        });
+    });
+    describe('getIconResourceDetails', () => {
+        it('returns structured details for known icons', async () => {
+            const { getIconResourceDetails } = await import("../icons.js");
+            const details = getIconResourceDetails('SearchIcon');
+            expect(details).toMatchObject({
+                name: 'SearchIcon',
+                importPath: '@splunk/react-icons/SearchIcon',
+                category: 'Interface',
+                description: 'Use for search interactions.',
+                keywords: 'search, magnify, find',
+                variants: ['default', 'filled'],
+            });
+            expect(details?.usageExample).toContain('SearchIcon');
+        });
+        it('returns undefined when the icon is missing', async () => {
+            const { getIconResourceDetails } = await import("../icons.js");
+            expect(getIconResourceDetails('MissingIcon')).toBeUndefined();
+        });
+        it('accepts catalog entries directly', async () => {
+            const { getIconResourceDetails } = await import("../icons.js");
+            const details = getIconResourceDetails({
+                name: 'AlertIcon',
+                key: './AlertIcon',
+                keywords: 'alert, warning',
+                variants: ['default'],
+                description: 'An alert icon.',
+                category: '',
+            });
+            expect(details).toMatchObject({
+                name: 'AlertIcon',
+                importPath: '@splunk/react-icons/AlertIcon',
+            });
+            expect(details.usageExample).toContain('AlertIcon');
+        });
+    });
+    describe('iconResource', () => {
+        const setup = async () => {
+            const { default: iconResource, createIconResourceUri } = await import("../icons.js");
+            return {
+                iconResource,
+                createIconResourceUri,
+            };
+        };
+        it('provides the expected metadata configuration', async () => {
+            const { iconResource } = await setup();
+            expect(iconResource.name).toBe('splunk-ui-icons');
+            expect(iconResource.config).toMatchObject({
+                title: expect.stringContaining('Icon Catalog'),
+                mimeType: 'application/json',
+            });
+        });
+        it('lists icons from the catalog', async () => {
+            const { iconResource } = await setup();
+            const { template } = iconResource;
+            const listResult = await template.listCallback?.();
+            expect(listResult).toMatchObject({
+                resources: expect.arrayContaining([
+                    expect.objectContaining({ name: 'SearchIcon' }),
+                    expect.objectContaining({ name: 'AlertIcon' }),
+                ]),
+            });
+        });
+        it('suggests icon names using the completion handler', async () => {
+            const { iconResource } = await setup();
+            const complete = iconResource.template.completeCallback?.('iconName');
+            const completions = (await complete?.('se')) ?? [];
+            expect(completions).toContain('SearchIcon');
+            expect(completions).not.toContain('AlertIcon');
+        });
+        it('reads icon details using request variables', async () => {
+            const { iconResource, createIconResourceUri } = await setup();
+            expect(typeof iconResource.handler).toBe('function');
+            const readResult = await iconResource.handler(new URL(createIconResourceUri('AlertIcon')), { iconName: 'AlertIcon' });
+            const [content] = readResult.contents;
+            expect(content).toMatchObject({
+                uri: createIconResourceUri('AlertIcon'),
+                mimeType: 'application/json',
+            });
+            const parsed = JSON.parse(String(content.text ?? '{}'));
+            expect(parsed).toMatchObject({
+                name: 'AlertIcon',
+                importPath: '@splunk/react-icons/AlertIcon',
+                keywords: 'alert, warning',
+            });
+            expect(parsed.usageExample).toContain('AlertIcon');
+            // Ensure the template reference is exercised for coverage.
+            expect(iconResource.template).toBeDefined();
+        });
+        it('derives the icon name from the URI when variables are absent', async () => {
+            const { iconResource, createIconResourceUri } = await setup();
+            const readWithoutVariable = (await iconResource.handler(new URL(createIconResourceUri('SearchIcon')), {}));
+            const [content] = readWithoutVariable.contents;
+            expect(JSON.parse(String(content.text))).toMatchObject({ name: 'SearchIcon' });
+        });
+        it('throws when the icon cannot be resolved from variables or the URI', async () => {
+            const { iconResource } = await setup();
+            expect(() => iconResource.handler(new URL('mcp://splunk-ui'), {})).toThrowError('Icon name missing in resource request: mcp://splunk-ui');
+        });
+        it('throws when the requested icon is not found in the catalog', async () => {
+            const { iconResource, createIconResourceUri } = await setup();
+            expect(() => iconResource.handler(new URL(createIconResourceUri('MissingIcon')), {
+                iconName: 'MissingIcon',
+            })).toThrowError('Unknown icon "MissingIcon"');
+        });
+    });
+});

package/lib/tools/find_icons.d.ts

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

package/lib/tools/find_icons.js

@@ -0,0 +1,102 @@
+import iconCatalog from '@splunk/react-icons/icon-catalog.json' with { type: 'json' };
+import { addSearchData, search } from '@splunk/ui-utils/search.js';
+import { z } from 'zod';
+import { createIconResourceLink, getIconResourceDetails } from "../resources/icons.js";
+const iconData = addSearchData(iconCatalog);
+const NO_RESULTS_RESULT = {
+    content: [
+        {
+            type: 'text',
+            text: 'No icons found. Try different keywords like "search", "notification", "user", "chart", etc.',
+        },
+    ],
+};
+const formatIconDetails = (details) => {
+    const lines = [];
+    if (details.description) {
+        lines.push(`- Description: ${details.description}`);
+    }
+    lines.push(`- Import: \`${details.importPath}\``);
+    if (details.category) {
+        lines.push(`- Category: ${details.category}`);
+    }
+    if (details.variants?.length) {
+        lines.push(`- Variants: ${details.variants.join(', ')}`);
+    }
+    if (details.keywords) {
+        lines.push(`- Keywords: ${details.keywords}`);
+    }
+    lines.push('');
+    lines.push(details.usageExample);
+    return lines.join('\n');
+};
+const findIconsHandler = ({ query }) => {
+    if (!query || query.trim().length === 0) {
+        return NO_RESULTS_RESULT;
+    }
+    const results = search(query, iconData);
+    if (results.length === 0) {
+        return NO_RESULTS_RESULT;
+    }
+    const [recommended, ...others] = results;
+    const recommendedIcon = recommended.name;
+    const alternativeIcons = others.slice(0, 4); // recommend up to 4 alternative icons
+    const recommendedDetails = getIconResourceDetails(recommendedIcon);
+    const alternativeSummaries = alternativeIcons.map((icon) => ({
+        name: icon.name,
+        details: getIconResourceDetails(icon.name),
+    }));
+    const sections = [
+        `# Icons for "${query}"`,
+        '## Recommended Icon',
+        `Recommended to use <${recommendedIcon} /> for "${query}"`,
+        recommendedDetails
+            ? formatIconDetails(recommendedDetails)
+            : `No catalog details found for ${recommendedIcon}.`,
+    ];
+    sections.push('Follow the resource links below for full metadata and usage snippets.');
+    if (alternativeSummaries.length > 0) {
+        sections.push('## Alternative Icons', alternativeSummaries
+            .map(({ name, details }) => {
+            const context = details?.description ?? details?.keywords ?? details?.category;
+            return context ? `- ${name}: ${context}` : `- ${name}`;
+        })
+            .join('\n'));
+    }
+    const summaryText = sections.join('\n\n');
+    const structuredContent = {
+        recommended: {
+            name: recommendedIcon,
+            details: recommendedDetails ?? null,
+        },
+        alternatives: alternativeSummaries.map(({ name, details }) => ({
+            name,
+            details: details ?? null,
+        })),
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: summaryText,
+            },
+            createIconResourceLink(recommendedIcon),
+            ...alternativeIcons.map((icon) => createIconResourceLink(icon.name)),
+        ],
+        structuredContent,
+    };
+};
+const findIconsTool = {
+    name: 'find_icons',
+    config: {
+        title: 'Find Icons',
+        description: 'Search @splunk/react-icons for the best match and a few alternatives based on your keyword.',
+        inputSchema: {
+            query: z
+                .string()
+                .describe('The search query for the icon, e.g., "search", "notification", "user".'),
+        },
+    },
+    handler: findIconsHandler,
+};
+export default findIconsTool;

package/lib/tools/get_component_docs.d.ts

@@ -0,0 +1,19 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/**
+ * Tool to get documentation for a specific React UI component
+ */
+declare const getComponentDocsTool: {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: {
+            componentName: z.ZodString;
+        };
+    };
+    handler: ({ componentName }: {
+        componentName?: string;
+    }) => CallToolResult;
+};
+export default getComponentDocsTool;

package/lib/tools/get_component_docs.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { createComponentResourceLink } from "../resources/components.js";
+import { componentExists, getComponentDocs, getComponentList } from "../utils/component-catalog.js";
+/**
+ * Tool to get documentation for a specific React UI component
+ */
+const getComponentDocsTool = {
+    name: 'get_component_docs',
+    config: {
+        title: 'Get Component Documentation',
+        description: 'Retrieves the full documentation for a specific @splunk/react-ui component. ' +
+            'Includes overview, usage guidelines, examples, API documentation, and accessibility information.',
+        inputSchema: {
+            componentName: z
+                .string()
+                .describe('The exact name of the component (e.g., "Button", "Card Layout", "Text"). ' +
+                'Case-sensitive. Use the component name as it appears in the catalog.'),
+        },
+    },
+    handler: ({ componentName }) => {
+        if (!componentName || componentName.trim().length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Component name is required. Please provide a component name.',
+                    },
+                ],
+            };
+        }
+        // Check if component exists
+        if (!componentExists(componentName)) {
+            const components = getComponentList();
+            const availableNames = components.map((c) => c.name).slice(0, 10);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Component "${componentName}" not found.\n\n` +
+                            `Available components include: ${availableNames.join(', ')}, and more.\n\n` +
+                            'Component names are case-sensitive. Please check the spelling and try again.',
+                    },
+                ],
+            };
+        }
+        // Get the documentation
+        try {
+            const docs = getComponentDocs(componentName);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: docs,
+                    },
+                    createComponentResourceLink(componentName),
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve documentation for "${componentName}": ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};
+export default getComponentDocsTool;
+// TODO: Future enhancement - add section extraction
+// Allow requesting specific sections of documentation:
+// - Overview
+// - Examples
+// - API/Props
+// - Accessibility
+// - Test Hooks
+//
+// Example:
+// export function getComponentSection(componentName: string, section: string): CallToolResult

package/lib/tools/requirements.d.ts

@@ -0,0 +1,15 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Tool to list design system version requirements (Splunk UI packages + peerDependencies)
+ * without requiring an existing project.
+ */
+declare const requirements: {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: {};
+    };
+    handler: () => CallToolResult;
+};
+export default requirements;

package/lib/tools/requirements.js

@@ -0,0 +1,25 @@
+import VERSIONS from "../constants/versions.js";
+/**
+ * Tool to list design system version requirements (Splunk UI packages + peerDependencies)
+ * without requiring an existing project.
+ */
+const requirements = {
+    name: 'list_splunk_ui_requirements',
+    config: {
+        title: 'List Splunk UI Design System Requirements',
+        description: '🔧 **For Agents:** ALWAYS call this tool first to fetch exact version constraints for Splunk UI packages and peer dependencies required by the Splunk UI Design System before scaffolding a new project; after use the check_setup tool to verify.\n\n' +
+            'Returns the Splunk UI design system requirements as JSON.',
+        inputSchema: {},
+    },
+    handler: () => {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(VERSIONS, null, 2),
+                },
+            ],
+        };
+    },
+};
+export default requirements;

package/lib/tools/tests/find_icons.unit.d.ts

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