@splunk/splunk-ui-mcp 0.1.0 → 0.2.0

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

@@ -1,161 +0,0 @@
-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/get_component_docs.d.ts

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

@@ -1,82 +0,0 @@
-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/tests/find_icons.unit.d.ts

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

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

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

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

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

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

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

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

@@ -1,34 +0,0 @@
-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/tests/component-catalog.unit.d.ts

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