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

package/dist/resourceHandlers.test.js

@@ -0,0 +1,352 @@
+/**
+ * Tests for resourceHandlers.ts
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as path from 'path';
+import { handleListResources, handleReadResource } from './resourceHandlers.js';
+import { getMarkdownFiles, readFileContent } from './utils.js';
+import { DOCS_DIR } from './config.js';
+const mockGetMarkdownFiles = vi.mocked(getMarkdownFiles);
+const mockReadFileContent = vi.mocked(readFileContent);
+// Mock dependencies
+vi.mock('./utils.js', () => ({
+    getMarkdownFiles: vi.fn(),
+    readFileContent: vi.fn(),
+}));
+vi.mock('./config.js', () => ({
+    DOCS_DIR: '/mock/docs/ids',
+}));
+describe('resourceHandlers', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('handleListResources', () => {
+        it('should return empty resources when no markdown files exist', () => {
+            mockGetMarkdownFiles.mockReturnValue([]);
+            const result = handleListResources();
+            expect(result).toEqual({
+                resources: [],
+            });
+            expect(mockGetMarkdownFiles).toHaveBeenCalledOnce();
+        });
+        it('should categorize component files correctly', () => {
+            const mockFiles = [
+                'components-button-docs.md',
+                'components-input-docs.md',
+                'components-modal-docs.md',
+            ];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(3);
+            expect(result.resources[0]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'components-button-docs.md')}`,
+                name: 'Components: button',
+                description: 'IDS components documentation for button',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[1]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'components-input-docs.md')}`,
+                name: 'Components: input',
+                description: 'IDS components documentation for input',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[2]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'components-modal-docs.md')}`,
+                name: 'Components: modal',
+                description: 'IDS components documentation for modal',
+                mimeType: 'text/markdown',
+            });
+        });
+        it('should categorize foundation files correctly', () => {
+            const mockFiles = [
+                'foundations-colors-docs.md',
+                'foundations-typography-docs.md',
+                'foundations-spacing-docs.md',
+            ];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(3);
+            expect(result.resources[0]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'foundations-colors-docs.md')}`,
+                name: 'Foundations: colors',
+                description: 'IDS foundations documentation for colors',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[1]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'foundations-typography-docs.md')}`,
+                name: 'Foundations: typography',
+                description: 'IDS foundations documentation for typography',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[2]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'foundations-spacing-docs.md')}`,
+                name: 'Foundations: spacing',
+                description: 'IDS foundations documentation for spacing',
+                mimeType: 'text/markdown',
+            });
+        });
+        it('should categorize resource files correctly', () => {
+            const mockFiles = [
+                'resources-guidelines-docs.md',
+                'resources-patterns-docs.md',
+            ];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(2);
+            expect(result.resources[0]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'resources-guidelines-docs.md')}`,
+                name: 'Resources: guidelines',
+                description: 'IDS resources documentation for guidelines',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[1]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'resources-patterns-docs.md')}`,
+                name: 'Resources: patterns',
+                description: 'IDS resources documentation for patterns',
+                mimeType: 'text/markdown',
+            });
+        });
+        it('should categorize introduction files correctly', () => {
+            const mockFiles = ['introduction.md', 'getting-started-introduction.md'];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(2);
+            expect(result.resources[0]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'introduction.md')}`,
+                name: 'Getting Started: Introduction',
+                description: 'IDS getting started documentation for Introduction',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[1]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'getting-started-introduction.md')}`,
+                name: 'Getting Started: Introduction',
+                description: 'IDS getting started documentation for Introduction',
+                mimeType: 'text/markdown',
+            });
+        });
+        it('should categorize uncategorized files as Other', () => {
+            const mockFiles = ['readme.md', 'changelog.md', 'random-file.md'];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(3);
+            expect(result.resources[0]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'readme.md')}`,
+                name: 'Other: readme.md',
+                description: 'IDS other documentation for readme.md',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[1]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'changelog.md')}`,
+                name: 'Other: changelog.md',
+                description: 'IDS other documentation for changelog.md',
+                mimeType: 'text/markdown',
+            });
+            expect(result.resources[2]).toEqual({
+                uri: `file://${path.join(DOCS_DIR, 'random-file.md')}`,
+                name: 'Other: random-file.md',
+                description: 'IDS other documentation for random-file.md',
+                mimeType: 'text/markdown',
+            });
+        });
+        it('should handle mixed file categories', () => {
+            const mockFiles = [
+                'components-button-docs.md',
+                'foundations-colors-docs.md',
+                'resources-guidelines-docs.md',
+                'introduction.md',
+                'readme.md',
+            ];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(5);
+            // Check that each category is represented
+            const categories = result.resources.map((resource) => resource.name.split(':')[0]);
+            expect(categories).toContain('Components');
+            expect(categories).toContain('Foundations');
+            expect(categories).toContain('Resources');
+            expect(categories).toContain('Getting Started');
+            expect(categories).toContain('Other');
+        });
+    });
+    describe('handleReadResource', () => {
+        const mockFileContent = '# Test Documentation\n\nThis is test content.';
+        beforeEach(() => {
+            mockReadFileContent.mockReturnValue(mockFileContent);
+        });
+        it('should successfully read a valid file', () => {
+            const testFilePath = path.join(DOCS_DIR, 'components-button-docs.md');
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            const result = handleReadResource(request);
+            expect(result).toEqual({
+                contents: [
+                    {
+                        uri: request.params.uri,
+                        mimeType: 'text/markdown',
+                        text: mockFileContent,
+                    },
+                ],
+            });
+            expect(mockReadFileContent).toHaveBeenCalledWith(testFilePath);
+        });
+        it('should throw error for unsupported protocol', () => {
+            const request = {
+                params: {
+                    uri: 'http://example.com/file.md',
+                },
+            };
+            expect(() => handleReadResource(request)).toThrow('Unsupported protocol: http:');
+        });
+        it('should throw error for files outside docs directory', () => {
+            const request = {
+                params: {
+                    uri: 'file:///etc/passwd',
+                },
+            };
+            expect(() => handleReadResource(request)).toThrow('Access denied: File is outside the docs directory');
+        });
+        it('should throw error for files using relative path traversal', () => {
+            const testFilePath = path.join(DOCS_DIR, '..', '..', 'secret.md');
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            expect(() => handleReadResource(request)).toThrow('Access denied: File is outside the docs directory');
+        });
+        it('should handle file read errors gracefully', () => {
+            const testFilePath = path.join(DOCS_DIR, 'nonexistent-file.md');
+            const readError = new Error('File not found');
+            mockReadFileContent.mockImplementation(() => {
+                throw readError;
+            });
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            expect(() => handleReadResource(request)).toThrow('Failed to read file: File not found');
+            expect(mockReadFileContent).toHaveBeenCalledWith(testFilePath);
+        });
+        it('should handle unknown errors gracefully', () => {
+            const testFilePath = path.join(DOCS_DIR, 'components-button-docs.md');
+            mockReadFileContent.mockImplementation(() => {
+                throw new Error('Unknown error string'); // Proper Error object
+            });
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            expect(() => handleReadResource(request)).toThrow('Failed to read file: Unknown error string');
+        });
+        it('should handle files in subdirectories within docs directory', () => {
+            const testFilePath = path.join(DOCS_DIR, 'subdirectory', 'components-nested-docs.md');
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            const result = handleReadResource(request);
+            expect(result).toEqual({
+                contents: [
+                    {
+                        uri: request.params.uri,
+                        mimeType: 'text/markdown',
+                        text: mockFileContent,
+                    },
+                ],
+            });
+            expect(mockReadFileContent).toHaveBeenCalledWith(testFilePath);
+        });
+        it('should handle Windows-style paths correctly', () => {
+            const normalizedPath = path.join(DOCS_DIR, 'components-button-docs.md');
+            const windowsStyleUri = `file://${normalizedPath.replace(/\\/g, '/')}`;
+            const request = {
+                params: {
+                    uri: windowsStyleUri,
+                },
+            };
+            const result = handleReadResource(request);
+            expect(result).toEqual({
+                contents: [
+                    {
+                        uri: request.params.uri,
+                        mimeType: 'text/markdown',
+                        text: mockFileContent,
+                    },
+                ],
+            });
+        });
+    });
+    // Add type-specific tests at the end
+    describe('Type compliance tests', () => {
+        it('should return resources with correct interface structure', () => {
+            const mockFiles = ['components-button-docs.md'];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            // Verify the returned structure matches expected interface
+            expect(result).toHaveProperty('resources');
+            expect(Array.isArray(result.resources)).toBe(true);
+            if (result.resources.length > 0) {
+                const resource = result.resources[0];
+                expect(resource).toHaveProperty('uri');
+                expect(resource).toHaveProperty('name');
+                expect(resource).toHaveProperty('description');
+                expect(resource).toHaveProperty('mimeType');
+                expect(typeof resource.uri).toBe('string');
+                expect(typeof resource.name).toBe('string');
+                expect(typeof resource.description).toBe('string');
+                expect(resource.mimeType).toBe('text/markdown');
+            }
+        });
+        it('should return read resource with correct content structure', () => {
+            const mockContent = '# Component Documentation\n\nDescription here.';
+            mockReadFileContent.mockReturnValue(mockContent);
+            const testFilePath = path.join(DOCS_DIR, 'components-button-docs.md');
+            const request = {
+                params: {
+                    uri: `file://${testFilePath}`,
+                },
+            };
+            const result = handleReadResource(request);
+            // Verify the returned structure matches expected interface
+            expect(result).toHaveProperty('contents');
+            expect(Array.isArray(result.contents)).toBe(true);
+            expect(result.contents).toHaveLength(1);
+            const content = result.contents[0];
+            expect(content).toHaveProperty('uri');
+            expect(content).toHaveProperty('mimeType');
+            expect(content).toHaveProperty('text');
+            expect(typeof content.uri).toBe('string');
+            expect(content.mimeType).toBe('text/markdown');
+            expect(typeof content.text).toBe('string');
+            expect(content.text).toBe(mockContent);
+        });
+        it('should handle empty file names correctly', () => {
+            const mockFiles = ['', '   ', '.md'];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(3);
+            // All should be categorized as "Other" since they don't match patterns
+            result.resources.forEach((resource) => {
+                expect(resource.name).toMatch(/^Other:/);
+            });
+        });
+        it('should preserve original filename in Other category', () => {
+            const originalFilename = 'some-random-documentation.md';
+            const mockFiles = [originalFilename];
+            mockGetMarkdownFiles.mockReturnValue(mockFiles);
+            const result = handleListResources();
+            expect(result.resources).toHaveLength(1);
+            expect(result.resources[0].name).toBe(`Other: ${originalFilename}`);
+            expect(result.resources[0].description).toBe(`IDS other documentation for ${originalFilename}`);
+        });
+    });
+});

package/dist/searchHandlers.js

@@ -0,0 +1,287 @@
+/**
+ * Tool handlers for search and documentation operations
+ */
+import { z } from 'zod';
+import * as path from 'path';
+import { getMarkdownFiles, readFileContent } from './utils.js';
+import { DOCS_DIR } from './config.js';
+export function handleGetUsageExamples(args) {
+    const schema = z.object({
+        component: z.string(),
+        pattern: z.string().optional(),
+    });
+    const { component, pattern } = schema.parse(args);
+    const markdownFiles = getMarkdownFiles();
+    // Find component files (main + recipes)
+    const componentFiles = markdownFiles.filter((file) => file.includes(`${component.toLowerCase()}`) ||
+        (file.includes('recipes') &&
+            file.toLowerCase().includes(component.toLowerCase())));
+    if (componentFiles.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No examples found for "${component}". Try: ${markdownFiles
+                        .filter((f) => f.startsWith('components-'))
+                        .slice(0, 5)
+                        .map((f) => f.replace('components-', '').replace('-docs.md', ''))
+                        .join(', ')}`,
+                },
+            ],
+        };
+    }
+    const examples = [];
+    for (const file of componentFiles) {
+        try {
+            const filePath = path.join(DOCS_DIR, file);
+            const content = readFileContent(filePath);
+            // Extract code examples
+            const codeBlocks = content.match(/```[\s\S]*?```/g) ?? [];
+            const jsxBlocks = content.match(/<[A-Z][^>]*>[\s\S]*?<\/[A-Z][^>]*>/g) ?? [];
+            if (pattern) {
+                // Filter examples by pattern
+                const patternMatches = [...codeBlocks, ...jsxBlocks].filter((block) => block.toLowerCase().includes(pattern.toLowerCase()));
+                examples.push(...patternMatches);
+            }
+            else {
+                examples.push(...codeBlocks, ...jsxBlocks);
+            }
+        }
+        catch (error) {
+            console.error(`Error reading file ${file}:`, error);
+        }
+    }
+    const patternSuffix = pattern ? ` (${pattern} pattern)` : '';
+    const patternNotFoundSuffix = pattern ? ` with pattern "${pattern}"` : '';
+    const examplesText = examples.length > 0
+        ? `**${component} Usage Examples**${patternSuffix}:\n\n${examples
+            .slice(0, 5)
+            .join('\n\n---\n\n')}`
+        : `No usage examples found for "${component}"${patternNotFoundSuffix}.`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: examplesText,
+            },
+        ],
+    };
+}
+export function handleSearchIdsDocs(args) {
+    const schema = z.object({
+        query: z.string(),
+        case_sensitive: z.boolean().default(false),
+    });
+    const { query, case_sensitive } = schema.parse(args);
+    const markdownFiles = getMarkdownFiles();
+    const results = [];
+    for (const file of markdownFiles) {
+        try {
+            const filePath = path.join(DOCS_DIR, file);
+            const content = readFileContent(filePath);
+            const lines = content.split('\n');
+            lines.forEach((line, index) => {
+                const searchLine = case_sensitive ? line : line.toLowerCase();
+                const searchQuery = case_sensitive ? query : query.toLowerCase();
+                if (searchLine.includes(searchQuery)) {
+                    // Get context (surrounding lines)
+                    const contextStart = Math.max(0, index - 1);
+                    const contextEnd = Math.min(lines.length - 1, index + 1);
+                    const context = lines.slice(contextStart, contextEnd + 1).join('\n');
+                    results.push({
+                        file: file.replace('-docs.md', '').replace(/^[a-z]+-/, ''),
+                        line: index + 1,
+                        content: line.trim(),
+                        context,
+                    });
+                }
+            });
+        }
+        catch (error) {
+            console.error(`Error reading file ${file}:`, error);
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: results.length > 0
+                    ? `Found ${results.length} matches in IDS documentation:\n\n${results
+                        .slice(0, 15) // Limit results
+                        .map((r) => `**${r.file}:${r.line}**\n\`\`\`\n${r.context}\n\`\`\``)
+                        .join('\n\n')}`
+                    : `No matches found for "${query}" in IDS documentation.`,
+            },
+        ],
+    };
+}
+export function handleGetDesignTokens(args) {
+    const schema = z.object({
+        type: z
+            .enum(['colors', 'spacing', 'typography', 'breakpoints', 'all'])
+            .default('all'),
+    });
+    const { type } = schema.parse(args);
+    const markdownFiles = getMarkdownFiles();
+    // Find foundation files related to design tokens
+    const foundationFiles = markdownFiles.filter((file) => file.startsWith('foundations-') &&
+        (type === 'all' || file.includes(type)));
+    const tokenInfo = [];
+    for (const file of foundationFiles) {
+        try {
+            const filePath = path.join(DOCS_DIR, file);
+            const content = readFileContent(filePath);
+            // Extract CSS custom properties and token information
+            const cssVariables = content.match(/--iress-[a-z-]+/g) ?? [];
+            const tokenSections = content.match(/#{2,3}\s+[^#\n]+/g) ?? [];
+            if (cssVariables.length > 0 || tokenSections.length > 0) {
+                let fileInfo = `**${file
+                    .replace('foundations-', '')
+                    .replace('-docs.md', '')}**\n`;
+                if (cssVariables.length > 0) {
+                    const uniqueVars = [...new Set(cssVariables)].slice(0, 10);
+                    fileInfo += `CSS Variables: ${uniqueVars.join(', ')}\n`;
+                }
+                if (tokenSections.length > 0) {
+                    fileInfo += `\n${tokenSections.slice(0, 3).join('\n\n')}`;
+                }
+                tokenInfo.push(fileInfo);
+            }
+        }
+        catch (error) {
+            console.error(`Error reading file ${file}:`, error);
+        }
+    }
+    const typeLabel = type !== 'all' ? ` (${type})` : '';
+    const typeNotFoundLabel = type !== 'all' ? ` for ${type}` : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: tokenInfo.length > 0
+                    ? `**IDS Design Tokens${typeLabel}**\n\n${tokenInfo.join('\n\n---\n\n')}`
+                    : `No design token information found${typeNotFoundLabel}. Available foundations: ${markdownFiles
+                        .filter((f) => f.startsWith('foundations-'))
+                        .map((f) => f.replace('foundations-', '').replace('-docs.md', ''))
+                        .join(', ')}`,
+            },
+        ],
+    };
+}
+function findSectionContent(content, section) {
+    const sectionRegex = new RegExp(`(#{1,3}\\s+.*${section}.*?(?=#{1,3}|$))`, 'gis');
+    const sectionMatch = sectionRegex.exec(content);
+    if (sectionMatch) {
+        return sectionMatch[0];
+    }
+    // Try to find sections that contain the search term
+    const sections = content.split(/(?=#{1,3}\s+)/);
+    const matchingSections = sections.filter((sectionContent) => sectionContent.toLowerCase().includes(section.toLowerCase()));
+    return matchingSections.length > 0 ? matchingSections.join('\n\n') : null;
+}
+function addContextLines(lines, startIndex, endIndex, contextLines) {
+    for (let j = startIndex; j < endIndex; j++) {
+        if (!contextLines.includes(lines[j])) {
+            contextLines.push(lines[j]);
+        }
+    }
+}
+function filterContentByQuery(content, query) {
+    const lines = content.split('\n');
+    const contextLines = [];
+    const queryLower = query.toLowerCase();
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.toLowerCase().includes(queryLower)) {
+            // Add context lines before
+            const startContext = Math.max(0, i - 3);
+            addContextLines(lines, startContext, i, contextLines);
+            // Add the matching line
+            if (!contextLines.includes(line)) {
+                contextLines.push(line);
+            }
+            // Add context lines after
+            const endContext = Math.min(lines.length, i + 4);
+            addContextLines(lines, i + 1, endContext, contextLines);
+        }
+    }
+    return contextLines.length > 0 ? contextLines.join('\n') : null;
+}
+export function handleGetDesignGuidelines(args) {
+    const schema = z.object({
+        section: z.string().optional(),
+        query: z.string().optional(),
+    });
+    const { section, query } = schema.parse(args);
+    try {
+        // Read the guidelines.md file from the docs directory
+        const guidelinesPath = path.join(DOCS_DIR, 'guidelines.md');
+        const content = readFileContent(guidelinesPath);
+        if (!content) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Design guidelines file not found. Please ensure guidelines.md exists in the docs directory.',
+                    },
+                ],
+            };
+        }
+        let filteredContent = content;
+        // Filter by section if specified
+        if (section) {
+            const sectionContent = findSectionContent(content, section);
+            if (sectionContent) {
+                filteredContent = sectionContent;
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Section "${section}" not found in design guidelines. Available sections include: Core Design Principles, Visual Design Standards, Component Guidelines, Accessibility, Layout Systems, and Best Practices.`,
+                        },
+                    ],
+                };
+            }
+        }
+        // Filter by query if specified
+        if (query) {
+            const queryContent = filterContentByQuery(filteredContent, query);
+            if (queryContent) {
+                filteredContent = queryContent;
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No guidelines found matching "${query}". Try searching for terms like: accessibility, typography, colors, spacing, components, principles, or usability.`,
+                        },
+                    ],
+                };
+            }
+        }
+        const sectionSuffix = section ? ` - ${section}` : '';
+        const querySuffix = query ? ` (filtered by: ${query})` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `**IDS Design Guidelines${sectionSuffix}${querySuffix}**\n\n${filteredContent}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        console.error('Error reading guidelines:', error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Error reading design guidelines. Please ensure the guidelines.md file exists and is accessible.',
+                },
+            ],
+        };
+    }
+}