@splunk/splunk-ui-mcp 0.1.0

package/lib/tools/tests/find_icons.unit.js

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const NO_RESULTS_TEXT = 'No icons found. Try different keywords like "search", "notification", "user", "chart", etc.';
+const ICON_CATALOG_FIXTURE = vi.hoisted(() => [
+    {
+        name: 'SearchIcon',
+        key: './SearchIcon',
+        category: 'Interface',
+        description: 'Use for search interactions.',
+        keywords: 'search, magnify, find',
+        variants: ['default', 'filled'],
+    },
+    {
+        name: 'AlertIcon',
+        key: './AlertIcon',
+        description: 'Communicates alert or warning states.',
+        keywords: 'alert, warning',
+    },
+    {
+        name: 'UserIcon',
+        key: './UserIcon',
+        keywords: 'profile, account',
+    },
+    { name: 'PrimaryIcon', key: './PrimaryIcon' },
+    { name: 'AltOne', key: './AltOne' },
+    { name: 'AltTwo', key: './AltTwo' },
+    { name: 'AltThree', key: './AltThree' },
+    { name: 'AltFour', key: './AltFour' },
+    { name: 'AltFive', key: './AltFive' },
+    { name: 'SoloIcon', key: './SoloIcon' },
+]);
+const INDEXED_DATA = { indexed: true };
+const addSearchDataMock = vi.fn();
+const searchMock = vi.fn();
+vi.mock('@splunk/react-icons/icon-catalog.json', () => ({
+    default: ICON_CATALOG_FIXTURE,
+}));
+vi.mock('@splunk/ui-utils/search', () => ({
+    addSearchData: addSearchDataMock,
+    search: searchMock,
+}));
+describe('find_icons tool', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        addSearchDataMock.mockReset();
+        searchMock.mockReset();
+        searchMock.mockReturnValue([]);
+        addSearchDataMock.mockReturnValue(INDEXED_DATA);
+    });
+    it('exposes metadata and prepares search index', async () => {
+        const { default: tool } = await import("../find_icons.js");
+        expect(tool.name).toBe('find_icons');
+        expect('config' in tool).toBe(true);
+        expect(tool.config?.title).toBeDefined();
+        expect(tool.config?.description).toBeDefined();
+        expect(tool.config.inputSchema?.query).toBeDefined();
+    });
+    it('prepares search index', async () => {
+        addSearchDataMock.mockReturnValue({
+            mock: true,
+        });
+        await import("../find_icons.js");
+        expect(addSearchDataMock).toHaveBeenCalledWith(ICON_CATALOG_FIXTURE);
+        expect(addSearchDataMock).toHaveReturnedWith({ mock: true });
+    });
+    describe('handler', () => {
+        it('returns guidance when query is empty', async () => {
+            const { default: tool } = await import("../find_icons.js");
+            const result = tool.handler({ query: '' });
+            expect(searchMock).not.toHaveBeenCalled();
+            expect(result.content[0]?.type).toBe('text');
+            expect(result.content[0]?.text).toBe(NO_RESULTS_TEXT);
+        });
+        it('returns guidance when no icons match search', async () => {
+            const { default: tool } = await import("../find_icons.js");
+            const result = tool.handler({ query: 'alert' });
+            expect(searchMock).toHaveBeenCalledWith('alert', INDEXED_DATA);
+            expect(result.content[0]?.text).toBe(NO_RESULTS_TEXT);
+        });
+        it('returns icon details and alternative resource links when matches are found', async () => {
+            searchMock.mockReturnValue([
+                {
+                    name: 'SearchIcon',
+                    description: 'Use for search interactions.',
+                    searchScore: { nameScore: 100, keywordsScore: 20, descriptionScore: 0 },
+                },
+                { name: 'AlertIcon', description: 'Communicates alert or warning states.' },
+                { name: 'UserIcon', keywords: 'profile, account' },
+            ]);
+            const { default: tool } = await import("../find_icons.js");
+            const result = tool.handler({ query: 'search' });
+            expect(searchMock).toHaveBeenCalledWith('search', INDEXED_DATA);
+            const [summary, ...rest] = result.content;
+            const resourceLinks = rest.filter((item) => item?.type === 'resource_link');
+            expect(summary).toMatchObject({ type: 'text' });
+            const summaryText = summary?.text ?? '';
+            expect(summaryText).toContain('# Icons for "search"');
+            expect(summaryText).toContain('## Recommended Icon');
+            expect(summaryText).toContain('Recommended to use <SearchIcon /> for "search"');
+            expect(summaryText).toContain('- Import: `@splunk/react-icons/SearchIcon`');
+            expect(summaryText).toContain('- Category: Interface');
+            expect(summaryText).toContain('- Keywords: search, magnify, find');
+            expect(summaryText).toContain('```tsx');
+            expect(summaryText).toContain('Follow the resource links below for full metadata and usage snippets.');
+            expect(summaryText).toContain('## Alternative Icons');
+            expect(summaryText).toContain('- AlertIcon');
+            expect(summaryText).toContain('- UserIcon');
+            expect(resourceLinks).toHaveLength(3);
+            expect(resourceLinks[0]).toMatchObject({
+                name: 'SearchIcon',
+                uri: 'mcp://splunk-ui/icons/SearchIcon',
+            });
+            expect(resourceLinks[1]).toMatchObject({
+                name: 'AlertIcon',
+                uri: 'mcp://splunk-ui/icons/AlertIcon',
+            });
+            expect(resourceLinks[2]).toMatchObject({
+                name: 'UserIcon',
+                uri: 'mcp://splunk-ui/icons/UserIcon',
+            });
+        });
+        it('limits alternative icons to four entries', async () => {
+            searchMock.mockReturnValue([
+                { name: 'PrimaryIcon' },
+                { name: 'AltOne' },
+                { name: 'AltTwo' },
+                { name: 'AltThree' },
+                { name: 'AltFour' },
+                { name: 'AltFive' },
+            ]);
+            const { default: tool } = await import("../find_icons.js");
+            const result = tool.handler({ query: 'primary' });
+            const summaryText = result.content[0]?.type === 'text' ? (result.content[0]?.text ?? '') : '';
+            expect(summaryText).toContain('- AltOne');
+            expect(summaryText).toContain('- AltTwo');
+            expect(summaryText).toContain('- AltThree');
+            expect(summaryText).toContain('- AltFour');
+            expect(summaryText).not.toContain('- AltFive');
+        });
+        it('omits alternative section when only one icon matches', async () => {
+            const { default: tool } = await import("../find_icons.js");
+            const { handler } = tool;
+            const args = { query: 'solo' };
+            searchMock.mockReturnValue([{ name: 'SoloIcon' }]);
+            const result = await handler(args);
+            const summaryText = result.content[0]?.type === 'text' ? (result.content[0]?.text ?? '') : '';
+            expect(summaryText).not.toContain('## Alternative Icons');
+        });
+    });
+});

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

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

package/lib/tools/tests/get_component_docs.unit.js

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi, beforeEach } 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';
+
+<Button label="Click me" />
+\`\`\`
+
+## API
+
+### Props
+
+- label: string
+- onClick: () => void
+`;
+// Mock the component catalog
+vi.mock('../../utils/component-catalog.ts', () => ({
+    getComponentList: vi.fn(() => MOCK_COMPONENT_LIST),
+    componentExists: vi.fn((name) => MOCK_COMPONENT_LIST.some((c) => c.name === name)),
+    getComponentDocs: vi.fn((name) => {
+        if (name === 'Button') {
+            return MOCK_BUTTON_DOCS;
+        }
+        throw new Error(`Component "${name}" not found in catalog`);
+    }),
+}));
+// Mock the components resource
+vi.mock('../../resources/components.ts', () => ({
+    createComponentResourceLink: vi.fn((name) => ({
+        type: 'resource_link',
+        uri: `mcp://splunk-ui/components/${encodeURIComponent(name)}`,
+        name,
+    })),
+}));
+describe('get_component_docs tool', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('returns documentation for an existing component', async () => {
+        const tool = (await import("../get_component_docs.js")).default;
+        const result = tool.handler({ componentName: 'Button' });
+        expect(result.content).toHaveLength(2);
+        expect(result.content[0]).toMatchObject({
+            type: 'text',
+            text: MOCK_BUTTON_DOCS,
+        });
+        expect(result.content[1]).toMatchObject({
+            type: 'resource_link',
+            name: 'Button',
+        });
+    });
+    it('returns error message for non-existent component', async () => {
+        const tool = (await import("../get_component_docs.js")).default;
+        const result = tool.handler({ componentName: 'NonExistent' });
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0]).toMatchObject({
+            type: 'text',
+        });
+        expect(result.content[0].text).toContain('Component "NonExistent" not found');
+        expect(result.content[0].text).toContain('Available components include');
+    });
+    it('handles empty component name', async () => {
+        const tool = (await import("../get_component_docs.js")).default;
+        const result = tool.handler({ componentName: '' });
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0]).toMatchObject({
+            type: 'text',
+        });
+        expect(result.content[0].text).toContain('Component name is required');
+    });
+    it('handles whitespace-only component name', async () => {
+        const tool = (await import("../get_component_docs.js")).default;
+        const result = tool.handler({ componentName: '   ' });
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0]).toMatchObject({
+            type: 'text',
+        });
+        expect(result.content[0].text).toContain('Component name is required');
+    });
+    it('handles errors when reading documentation', async () => {
+        const { getComponentDocs } = await import("../../utils/component-catalog.js");
+        // Mock an error for a specific component
+        getComponentDocs.mockImplementationOnce(() => {
+            throw new Error('File system error');
+        });
+        const tool = (await import("../get_component_docs.js")).default;
+        const result = tool.handler({ componentName: 'Button' });
+        expect(result.isError).toBe(true);
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0].text).toContain('Failed to retrieve documentation');
+        expect(result.content[0].text).toContain('File system error');
+    });
+    it('includes resource link in successful response', async () => {
+        const { createComponentResourceLink } = await import("../../resources/components.js");
+        const tool = (await import("../get_component_docs.js")).default;
+        tool.handler({ componentName: 'Button' });
+        expect(createComponentResourceLink).toHaveBeenCalledWith('Button');
+    });
+    it('works with components that have spaces in name', async () => {
+        const tool = (await import("../get_component_docs.js")).default;
+        // Card Layout exists in mock data
+        const result = tool.handler({ componentName: 'Card Layout' });
+        // Should try to get docs (will fail in mock, but proves it checked existence)
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Failed to retrieve documentation');
+    });
+});

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

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

package/lib/tools/tests/requirements.unit.js

@@ -0,0 +1,34 @@
+import { describe, expect, it, test } from 'vitest';
+import requirements from "../requirements.js";
+import VERSIONS from "../../constants/versions.js";
+describe('requirements tool', () => {
+    describe('configuration', () => {
+        it('should have correct tool name', () => {
+            expect(requirements.name).toBe('list_splunk_ui_requirements');
+        });
+        it('should have proper config structure', () => {
+            expect(requirements.config).toBeDefined();
+            expect(requirements.config.title).toBeDefined();
+            expect(requirements.config.description).toBeDefined();
+            expect(requirements.config.inputSchema).toEqual({});
+        });
+        it('should have a handler function', () => {
+            expect(typeof requirements.handler).toBe('function');
+        });
+    });
+    describe('handler', () => {
+        it('returns the correct JSON structure', () => {
+            const result = requirements.handler();
+            const text = result.content[0].text;
+            const parsed = JSON.parse(text);
+            expect(parsed).toBeDefined();
+            expect(typeof parsed).toBe('object');
+        });
+        test.each(Object.entries(VERSIONS))('should include %s and version in JSON response', (pkg, version) => {
+            const result = requirements.handler();
+            const text = result.content[0].text;
+            const parsed = JSON.parse(text);
+            expect(parsed[pkg]).toBe(version);
+        });
+    });
+});

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

@@ -0,0 +1,26 @@
+export type ComponentInfo = {
+    name: string;
+    filename: string;
+    category?: string;
+};
+/**
+ * Override the docs-llm path (primarily for testing)
+ * @internal
+ */
+export declare function setDocsLlmPath(path: string | null): void;
+/**
+ * Returns the cached list of all components
+ */
+export declare function getComponentList(): ComponentInfo[];
+/**
+ * Checks if a component exists in the catalog
+ */
+export declare function componentExists(componentName: string): boolean;
+/**
+ * Gets component info by name
+ */
+export declare function getComponentInfo(componentName: string): ComponentInfo | undefined;
+/**
+ * Reads the markdown documentation for a component
+ */
+export declare function getComponentDocs(componentName: string): string;

package/lib/utils/component-catalog.js

@@ -0,0 +1,148 @@
+import { readFileSync } from 'fs';
+import { join, dirname, resolve, relative, isAbsolute } from 'path';
+import { createRequire } from 'module';
+let componentCache = null;
+let docsLlmPath = null;
+/**
+ * Override the docs-llm path (primarily for testing)
+ * @internal
+ */
+export function setDocsLlmPath(path) {
+    docsLlmPath = path;
+    componentCache = null; // Clear cache when path changes
+}
+/**
+ * Sanitizes component names; Rejects names containing path separators or parent directory references
+ */
+function sanitizeComponentName(name) {
+    if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+        throw new Error(`Invalid component name: "${name}".`);
+    }
+    return name;
+}
+/**
+ * Resolves the path to the @splunk/react-ui/docs-llm directory
+ *
+ * Resolution order:
+ * 1. User's project node_modules (if @splunk/react-ui is installed locally)
+ * 2. MCP's bundled dependencies (fallback for standalone usage)
+ */
+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');
+        return docsLlmPath;
+    }
+    catch (error) {
+        throw new Error('@splunk/react-ui package not found. ' +
+            'Either install it in your project (npm install @splunk/react-ui) ' +
+            'or ensure the MCP was installed with peer dependencies.\n' +
+            `Error: ${error.message}`);
+    }
+}
+/**
+ * Parses the llms.txt file to extract component names and categories
+ */
+function parseComponentCatalog() {
+    const llmsTxtPath = join(resolveDocsLlmPath(), 'llms.txt');
+    try {
+        const content = readFileSync(llmsTxtPath, 'utf-8');
+        const components = [];
+        let currentCategory;
+        const lines = content.split('\n');
+        lines.forEach((line) => {
+            const categoryMatch = line.match(/^## (.+)$/);
+            if (categoryMatch) {
+                [, currentCategory] = categoryMatch;
+                return;
+            }
+            const componentMatch = line.match(/^- \*\*(.+?)\*\*$/);
+            if (componentMatch) {
+                const [, name] = componentMatch;
+                components.push({
+                    name,
+                    filename: `${name}.md`,
+                    category: currentCategory,
+                });
+            }
+        });
+        return components;
+    }
+    catch (parseError) {
+        throw new Error(`Failed to parse llms.txt: ${parseError.message}`);
+    }
+}
+/**
+ * Returns the cached list of all components
+ */
+export function getComponentList() {
+    if (!componentCache) {
+        componentCache = parseComponentCatalog();
+    }
+    return componentCache;
+}
+/**
+ * Checks if a component exists in the catalog
+ */
+export function componentExists(componentName) {
+    const components = getComponentList();
+    return components.some((c) => c.name === componentName);
+}
+/**
+ * Gets component info by name
+ */
+export function getComponentInfo(componentName) {
+    const components = getComponentList();
+    return components.find((c) => c.name === componentName);
+}
+/**
+ * Reads the markdown documentation for a component
+ */
+export function getComponentDocs(componentName) {
+    const sanitizedComponentName = sanitizeComponentName(componentName);
+    const componentInfo = getComponentInfo(sanitizedComponentName);
+    if (!componentInfo) {
+        throw new Error(`Component "${sanitizedComponentName}" not found in catalog`);
+    }
+    const docsLlmBase = resolveDocsLlmPath();
+    const docPath = join(docsLlmBase, componentInfo.filename);
+    // Verify the resolved path stays within docs-llm directory
+    const resolvedPath = resolve(docPath);
+    const resolvedBase = resolve(docsLlmBase);
+    // Use relative path check to prevent path traversal attacks
+    // This prevents bypasses via sibling directories that share a prefix
+    // (e.g., base=/path/docs-llm vs malicious=/path/docs-llm2/evil.md)
+    // If relativePath starts with '..', the target is outside the base directory
+    // If relativePath is absolute, resolve() returned a different root entirely
+    const relativePath = relative(resolvedBase, resolvedPath);
+    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        throw new Error(`Attempted to access path outside docs-llm directory.`);
+    }
+    try {
+        return readFileSync(docPath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read documentation for "${sanitizedComponentName}": ${error.message}`);
+    }
+}
+// TODO: Future enhancement - add section extraction helpers
+// These would parse markdown sections like "## Examples", "## API", etc.
+// Example:
+// export function getComponentSection(componentName: string, sectionName: string): string

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

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

package/lib/utils/tests/component-catalog.unit.js

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const MOCK_LLMS_TXT = `# React UI (@splunk/react-ui)
+
+A library of UI components, all independent of the Splunk Enterprise environment.
+
+## Base
+
+- **Anchor**
+- **Avatar**
+- **Button**
+- **Card Layout**
+
+## Content
+
+- **Heading**
+- **Paragraph**
+
+## Deprecated
+
+- **Accordion**
+`;
+const MOCK_BUTTON_DOCS = `# Button
+
+## Overview
+
+A button component for triggering actions.
+
+## Examples
+
+\`\`\`typescript
+import Button from '@splunk/react-ui/Button';
+\`\`\`
+`;
+// Mock file system operations
+vi.mock('fs', () => ({
+    readFileSync: vi.fn((path) => {
+        if (path.includes('llms.txt')) {
+            return MOCK_LLMS_TXT;
+        }
+        if (path.includes('Button.md')) {
+            return MOCK_BUTTON_DOCS;
+        }
+        throw new Error(`File not found: ${path}`);
+    }),
+}));
+describe('component-catalog', () => {
+    beforeEach(async () => {
+        vi.resetModules();
+        const { setDocsLlmPath } = await import("../component-catalog.js");
+        setDocsLlmPath('/mocked/docs-llm');
+    });
+    describe('getComponentList', () => {
+        it('parses components from llms.txt', async () => {
+            const { getComponentList } = await import("../component-catalog.js");
+            const components = getComponentList();
+            expect(components).toHaveLength(7);
+            expect(components[0]).toEqual({
+                name: 'Anchor',
+                filename: 'Anchor.md',
+                category: 'Base',
+            });
+            expect(components[2]).toEqual({
+                name: 'Button',
+                filename: 'Button.md',
+                category: 'Base',
+            });
+        });
+        it('preserves category information', async () => {
+            const { getComponentList } = await import("../component-catalog.js");
+            const components = getComponentList();
+            const heading = components.find((c) => c.name === 'Heading');
+            expect(heading?.category).toBe('Content');
+            const accordion = components.find((c) => c.name === 'Accordion');
+            expect(accordion?.category).toBe('Deprecated');
+        });
+        it('caches the result on subsequent calls', async () => {
+            // Need to clear mocks and reload in this test to accurately count calls
+            vi.clearAllMocks();
+            vi.resetModules();
+            const { readFileSync } = await import('fs');
+            const { setDocsLlmPath, getComponentList } = await import("../component-catalog.js");
+            setDocsLlmPath('/mocked/docs-llm');
+            getComponentList();
+            getComponentList();
+            getComponentList();
+            // Should only read the llms.txt file once (cached after first read)
+            const llmsTxtCalls = readFileSync.mock.calls.filter((call) => call[0].includes('llms.txt'));
+            expect(llmsTxtCalls).toHaveLength(1);
+        });
+    });
+    describe('componentExists', () => {
+        it('returns true for components in the catalog', async () => {
+            const { componentExists } = await import("../component-catalog.js");
+            expect(componentExists('Button')).toBe(true);
+            expect(componentExists('Heading')).toBe(true);
+        });
+        it('returns false for components not in the catalog', async () => {
+            const { componentExists } = await import("../component-catalog.js");
+            expect(componentExists('NonExistent')).toBe(false);
+            expect(componentExists('Unknown')).toBe(false);
+        });
+    });
+    describe('getComponentInfo', () => {
+        it('returns component info for existing components', async () => {
+            const { getComponentInfo } = await import("../component-catalog.js");
+            const buttonInfo = getComponentInfo('Button');
+            expect(buttonInfo).toEqual({
+                name: 'Button',
+                filename: 'Button.md',
+                category: 'Base',
+            });
+        });
+        it('returns undefined for non-existent components', async () => {
+            const { getComponentInfo } = await import("../component-catalog.js");
+            expect(getComponentInfo('NonExistent')).toBeUndefined();
+        });
+    });
+    describe('getComponentDocs', () => {
+        it('reads and returns markdown documentation', async () => {
+            const { getComponentDocs } = await import("../component-catalog.js");
+            const docs = getComponentDocs('Button');
+            expect(docs).toBe(MOCK_BUTTON_DOCS);
+        });
+        it('throws error for non-existent component', async () => {
+            const { getComponentDocs } = await import("../component-catalog.js");
+            expect(() => getComponentDocs('NonExistent')).toThrow('Component "NonExistent" not found in catalog');
+        });
+        it('rejects component names with path separators', async () => {
+            const { getComponentDocs } = await import("../component-catalog.js");
+            expect(() => getComponentDocs('some/path/Button')).toThrow(/Invalid component name/);
+            expect(() => getComponentDocs('some\\path\\Button')).toThrow(/Invalid component name/);
+        });
+        it('rejects component names with parent directory references', async () => {
+            const { getComponentDocs } = await import("../component-catalog.js");
+            expect(() => getComponentDocs('../../etc/passwd')).toThrow(/Invalid component name/);
+            expect(() => getComponentDocs('Button/../../../etc/passwd')).toThrow(/Invalid component name/);
+        });
+        it('rejects absolute paths', async () => {
+            const { getComponentDocs } = await import("../component-catalog.js");
+            expect(() => getComponentDocs('/etc/passwd')).toThrow(/Invalid component name/);
+            expect(() => getComponentDocs('C:\\Windows\\System32\\config\\sam')).toThrow(/Invalid component name/);
+        });
+    });
+});