@iress-oss/ids-mcp-server 0.0.1-dev.0

package/dist/toolHandler.test.js

@@ -0,0 +1,369 @@
+/**
+ * Tests for toolHandler.ts
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleToolCall } from './toolHandler.js';
+import { handleFindComponent, handleGetComponentProps, handleListComponents, } from './componentHandlers.js';
+import { handleGetUsageExamples, handleSearchIdsDocs, handleGetDesignTokens, handleGetDesignGuidelines, } from './searchHandlers.js';
+import { handleGetIressComponentInfo, handleAnalyzeComponentMentions, } from './iressHandlers.js';
+// Mock all handler modules
+vi.mock('./componentHandlers.js', () => ({
+    handleFindComponent: vi.fn(),
+    handleGetComponentProps: vi.fn(),
+    handleListComponents: vi.fn(),
+}));
+vi.mock('./searchHandlers.js', () => ({
+    handleGetUsageExamples: vi.fn(),
+    handleSearchIdsDocs: vi.fn(),
+    handleGetDesignTokens: vi.fn(),
+    handleGetDesignGuidelines: vi.fn(),
+}));
+vi.mock('./iressHandlers.js', () => ({
+    handleGetIressComponentInfo: vi.fn(),
+    handleAnalyzeComponentMentions: vi.fn(),
+}));
+// Type the mocked functions
+const mockedHandleFindComponent = vi.mocked(handleFindComponent);
+const mockedHandleGetComponentProps = vi.mocked(handleGetComponentProps);
+const mockedHandleListComponents = vi.mocked(handleListComponents);
+const mockedHandleGetUsageExamples = vi.mocked(handleGetUsageExamples);
+const mockedHandleSearchIdsDocs = vi.mocked(handleSearchIdsDocs);
+const mockedHandleGetDesignTokens = vi.mocked(handleGetDesignTokens);
+const mockedHandleGetDesignGuidelines = vi.mocked(handleGetDesignGuidelines);
+const mockedHandleGetIressComponentInfo = vi.mocked(handleGetIressComponentInfo);
+const mockedHandleAnalyzeComponentMentions = vi.mocked(handleAnalyzeComponentMentions);
+describe('handleToolCall', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('component handlers', () => {
+        it('should handle find_component tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Component found' }],
+            };
+            mockedHandleFindComponent.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'find_component',
+                    arguments: { query: 'Button' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleFindComponent).toHaveBeenCalledWith({
+                query: 'Button',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle get_component_props tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Component props listed' }],
+            };
+            mockedHandleGetComponentProps.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'get_component_props',
+                    arguments: { component: 'Button' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleGetComponentProps).toHaveBeenCalledWith({
+                component: 'Button',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle list_components tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Components listed' }],
+            };
+            mockedHandleListComponents.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'list_components',
+                    arguments: { category: 'forms' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleListComponents).toHaveBeenCalledWith({
+                category: 'forms',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+    });
+    describe('search handlers', () => {
+        it('should handle get_usage_examples tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Usage examples found' }],
+            };
+            mockedHandleGetUsageExamples.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'get_usage_examples',
+                    arguments: { component: 'Button', pattern: 'primary' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleGetUsageExamples).toHaveBeenCalledWith({
+                component: 'Button',
+                pattern: 'primary',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle search_ids_docs tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Documentation searched' }],
+            };
+            mockedHandleSearchIdsDocs.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'search_ids_docs',
+                    arguments: { query: 'accessibility' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleSearchIdsDocs).toHaveBeenCalledWith({
+                query: 'accessibility',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle get_design_tokens tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Design tokens found' }],
+            };
+            mockedHandleGetDesignTokens.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'get_design_tokens',
+                    arguments: { category: 'colors' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleGetDesignTokens).toHaveBeenCalledWith({
+                category: 'colors',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle get_design_guidelines tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Design guidelines found' }],
+            };
+            mockedHandleGetDesignGuidelines.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'get_design_guidelines',
+                    arguments: { topic: 'spacing' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleGetDesignGuidelines).toHaveBeenCalledWith({
+                topic: 'spacing',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+    });
+    describe('iress handlers', () => {
+        it('should handle get_iress_component_info tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Iress component info' }],
+            };
+            mockedHandleGetIressComponentInfo.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'get_iress_component_info',
+                    arguments: {
+                        component_name: 'IressButton',
+                        include_examples: true,
+                        include_props: false,
+                    },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleGetIressComponentInfo).toHaveBeenCalledWith({
+                component_name: 'IressButton',
+                include_examples: true,
+                include_props: false,
+            });
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle analyze_component_mentions tool call', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Component mentions analyzed' }],
+            };
+            mockedHandleAnalyzeComponentMentions.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'analyze_component_mentions',
+                    arguments: { content: 'This uses IressButton component' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleAnalyzeComponentMentions).toHaveBeenCalledWith({
+                content: 'This uses IressButton component',
+            });
+            expect(result).toEqual(mockResponse);
+        });
+    });
+    describe('edge cases', () => {
+        it('should handle tool call without arguments', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Components listed' }],
+            };
+            mockedHandleListComponents.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'list_components',
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleListComponents).toHaveBeenCalledWith({});
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle tool call with null arguments', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Component found' }],
+            };
+            mockedHandleFindComponent.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'find_component',
+                    arguments: null,
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleFindComponent).toHaveBeenCalledWith(null);
+            expect(result).toEqual(mockResponse);
+        });
+        it('should handle tool call with undefined arguments', () => {
+            const mockResponse = {
+                content: [{ type: 'text', text: 'Component found' }],
+            };
+            mockedHandleFindComponent.mockReturnValue(mockResponse);
+            const request = {
+                params: {
+                    name: 'find_component',
+                    arguments: undefined,
+                },
+            };
+            const result = handleToolCall(request);
+            expect(mockedHandleFindComponent).toHaveBeenCalledWith({});
+            expect(result).toEqual(mockResponse);
+        });
+    });
+    describe('error handling', () => {
+        it('should throw error for unknown tool name', () => {
+            const request = {
+                params: {
+                    name: 'unknown_tool',
+                    arguments: { query: 'test' },
+                },
+            };
+            expect(() => handleToolCall(request)).toThrow('Unknown tool: unknown_tool');
+        });
+        it('should handle empty tool name', () => {
+            const request = {
+                params: {
+                    name: '',
+                    arguments: { query: 'test' },
+                },
+            };
+            expect(() => handleToolCall(request)).toThrow('Unknown tool: ');
+        });
+        it('should propagate errors from handler functions', () => {
+            const mockError = new Error('Handler error');
+            mockedHandleFindComponent.mockImplementation(() => {
+                throw mockError;
+            });
+            const request = {
+                params: {
+                    name: 'find_component',
+                    arguments: { query: 'Button' },
+                },
+            };
+            expect(() => handleToolCall(request)).toThrow('Handler error');
+        });
+    });
+    describe('type checking', () => {
+        it('should pass correct argument types to handlers', () => {
+            const complexArgs = {
+                component: 'Button',
+                options: {
+                    includeExamples: true,
+                    includeProps: false,
+                },
+                filters: ['primary', 'secondary'],
+                metadata: {
+                    timestamp: Date.now(),
+                    version: '1.0.0',
+                },
+            };
+            mockedHandleGetComponentProps.mockReturnValue({
+                content: [{ type: 'text', text: 'Success' }],
+            });
+            const request = {
+                params: {
+                    name: 'get_component_props',
+                    arguments: complexArgs,
+                },
+            };
+            handleToolCall(request);
+            expect(mockedHandleGetComponentProps).toHaveBeenCalledWith(complexArgs);
+        });
+        it('should handle boolean and number arguments', () => {
+            const booleanArgs = {
+                include_examples: true,
+                include_props: false,
+                max_results: 10,
+                threshold: 0.5,
+            };
+            mockedHandleGetIressComponentInfo.mockReturnValue({
+                content: [{ type: 'text', text: 'Success' }],
+            });
+            const request = {
+                params: {
+                    name: 'get_iress_component_info',
+                    arguments: booleanArgs,
+                },
+            };
+            handleToolCall(request);
+            expect(mockedHandleGetIressComponentInfo).toHaveBeenCalledWith(booleanArgs);
+        });
+    });
+    describe('all supported tools', () => {
+        const supportedTools = [
+            'find_component',
+            'get_component_props',
+            'get_usage_examples',
+            'search_ids_docs',
+            'list_components',
+            'get_design_tokens',
+            'get_iress_component_info',
+            'analyze_component_mentions',
+            'get_design_guidelines',
+        ];
+        it.each(supportedTools)('should handle %s tool', (toolName) => {
+            // Mock all handlers to return a standard response
+            const mockResponse = {
+                content: [{ type: 'text', text: `${toolName} executed` }],
+            };
+            const handlerMocks = [
+                mockedHandleFindComponent,
+                mockedHandleGetComponentProps,
+                mockedHandleListComponents,
+                mockedHandleGetUsageExamples,
+                mockedHandleSearchIdsDocs,
+                mockedHandleGetDesignTokens,
+                mockedHandleGetDesignGuidelines,
+                mockedHandleGetIressComponentInfo,
+                mockedHandleAnalyzeComponentMentions,
+            ];
+            handlerMocks.forEach((mock) => mock.mockReturnValue(mockResponse));
+            const request = {
+                params: {
+                    name: toolName,
+                    arguments: { test: 'value' },
+                },
+            };
+            const result = handleToolCall(request);
+            expect(result).toEqual(mockResponse);
+        });
+    });
+});

package/dist/tools.js

@@ -0,0 +1,165 @@
+/**
+ * Tool definitions for the IDS MCP Server
+ */
+export const toolDefinitions = [
+    {
+        name: 'find_component',
+        description: 'Find IDS components by name or functionality. Perfect for discovering which component to use for specific UI needs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: "Component name (e.g., 'button', 'input') or functionality (e.g., 'form submission', 'navigation')",
+                },
+                category: {
+                    type: 'string',
+                    description: 'Optional: filter by category (components, foundations, resources)',
+                    enum: ['components', 'foundations', 'resources'],
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_component_props',
+        description: 'Get detailed prop information and usage examples for IDS components. Essential for implementing components correctly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: "Component name (e.g., 'button', 'input', 'table')",
+                },
+            },
+            required: ['component'],
+        },
+    },
+    {
+        name: 'get_usage_examples',
+        description: 'Get code examples and implementation patterns for IDS components. Shows real-world usage in React applications.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: 'Component name to get examples for',
+                },
+                pattern: {
+                    type: 'string',
+                    description: "Optional: specific usage pattern (e.g., 'form', 'modal', 'table')",
+                },
+            },
+            required: ['component'],
+        },
+    },
+    {
+        name: 'search_ids_docs',
+        description: 'Search across all IDS documentation for specific terms, patterns, or implementation details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search term (component names, props, CSS classes, implementation patterns)',
+                },
+                case_sensitive: {
+                    type: 'boolean',
+                    description: 'Whether to perform case-sensitive search',
+                    default: false,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'list_components',
+        description: 'List all available IDS components, organized by category. Great for component discovery.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Filter by category: components, foundations, or resources',
+                    enum: ['components', 'foundations', 'resources', 'all'],
+                    default: 'all',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_design_tokens',
+        description: 'Get information about IDS design tokens (colors, spacing, typography) for consistent UI implementation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    description: 'Type of design token to search for',
+                    enum: ['colors', 'spacing', 'typography', 'breakpoints', 'all'],
+                    default: 'all',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_iress_component_info',
+        description: 'Get comprehensive information about Iress components mentioned by their full name (e.g., IressButton, IressInput, IressTable). Perfect for when components are mentioned with the Iress prefix.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component_name: {
+                    type: 'string',
+                    description: "Full Iress component name (e.g., 'IressButton', 'IressInput', 'IressTable')",
+                },
+                include_examples: {
+                    type: 'boolean',
+                    description: 'Whether to include usage examples in the response',
+                    default: true,
+                },
+                include_props: {
+                    type: 'boolean',
+                    description: 'Whether to include prop information in the response',
+                    default: true,
+                },
+            },
+            required: ['component_name'],
+        },
+    },
+    {
+        name: 'analyze_component_mentions',
+        description: 'Analyze text to find all Iress component mentions (e.g., IressButton, IressInput) and provide information about each one.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: {
+                    type: 'string',
+                    description: 'Text content to analyze for Iress component mentions',
+                },
+                detailed: {
+                    type: 'boolean',
+                    description: 'Whether to provide detailed information for each component found',
+                    default: false,
+                },
+            },
+            required: ['text'],
+        },
+    },
+    {
+        name: 'get_design_guidelines',
+        description: 'Get IDS design guidelines covering core principles, visual standards, accessibility requirements, and best practices for consistent design implementation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                section: {
+                    type: 'string',
+                    description: "Optional: specific guideline section (e.g., 'principles', 'typography', 'accessibility', 'layout', 'colors')",
+                },
+                query: {
+                    type: 'string',
+                    description: 'Optional: search for specific guidelines or best practices',
+                },
+            },
+        },
+    },
+];

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the IDS MCP Server
+ */
+export {};

package/dist/utils.js

@@ -0,0 +1,59 @@
+/**
+ * Utility functions for file operations and component mapping
+ */
+import * as fs from 'fs';
+import { DOCS_DIR } from './config.js';
+/**
+ * Utility function to get all markdown files in the docs directory
+ */
+export function getMarkdownFiles() {
+    try {
+        if (!fs.existsSync(DOCS_DIR)) {
+            return [];
+        }
+        const files = fs.readdirSync(DOCS_DIR, { recursive: true });
+        return files
+            .filter((file) => typeof file === 'string' && file.endsWith('.md'))
+            .map((file) => file);
+    }
+    catch (error) {
+        console.error('Error reading docs directory:', error);
+        return [];
+    }
+}
+/**
+ * Map Iress component names (e.g., IressButton) to their documentation files
+ */
+export function mapIressComponentToFile(componentName) {
+    // Remove 'Iress' prefix and convert to lowercase
+    const baseComponentName = componentName.replace(/^Iress/, '').toLowerCase();
+    const markdownFiles = getMarkdownFiles();
+    // Try to find exact match first
+    let matchingFile = markdownFiles.find((file) => file === `components-${baseComponentName}-docs.md`);
+    // If no exact match, try partial matching
+    matchingFile ??= markdownFiles.find((file) => file.startsWith(`components-${baseComponentName}`) &&
+        file.endsWith('-docs.md'));
+    // If still no match, try fuzzy matching
+    matchingFile ??= markdownFiles.find((file) => file.includes(baseComponentName) && file.startsWith('components-'));
+    return matchingFile ?? null;
+}
+/**
+ * Extract Iress component names from text (e.g., IressButton, IressInput)
+ */
+export function extractIressComponents(text) {
+    const iressComponentRegex = /Iress[A-Z][a-zA-Z]*/g;
+    const matches = text.match(iressComponentRegex) ?? [];
+    return [...new Set(matches)]; // Remove duplicates
+}
+/**
+ * Read file content safely
+ */
+export function readFileContent(filePath) {
+    return fs.readFileSync(filePath, 'utf-8');
+}
+/**
+ * Check if file exists
+ */
+export function fileExists(filePath) {
+    return fs.existsSync(filePath);
+}