@iress-oss/ids-mcp-server 0.0.1-dev.5 → 0.0.1-dev.7

package/dist/iressHandlers.js

@@ -0,0 +1,144 @@
+/**
+ * Tool handlers for Iress component-specific operations
+ */
+import { z } from 'zod';
+import * as path from 'path';
+import { mapIressComponentToFile, extractIressComponents, readFileContent, } from './utils.js';
+import { DOCS_DIR } from './config.js';
+export function handleGetIressComponentInfo(args) {
+    const schema = z.object({
+        component_name: z.string(),
+        include_examples: z.boolean().default(true),
+        include_props: z.boolean().default(true),
+    });
+    const { component_name, include_examples, include_props } = schema.parse(args);
+    // Find the corresponding documentation file
+    const componentFile = mapIressComponentToFile(component_name);
+    if (!componentFile) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Component "${component_name}" not found. Make sure you're using the correct Iress component name (e.g., IressButton, IressInput, IressTable).`,
+                },
+            ],
+        };
+    }
+    try {
+        const filePath = path.join(DOCS_DIR, componentFile);
+        const content = readFileContent(filePath);
+        let response = `**${component_name} Component Documentation**\n\n`;
+        // Extract overview/description
+        const lines = content.split('\n');
+        const overviewStart = lines.findIndex((line) => line.toLowerCase().includes('overview'));
+        if (overviewStart !== -1) {
+            const overviewEnd = lines.findIndex((line, index) => index > overviewStart && line.startsWith('#'));
+            const overviewLines = lines.slice(overviewStart, overviewEnd !== -1 ? overviewEnd : overviewStart + 10);
+            response += `${overviewLines.join('\n')}\n\n`;
+        }
+        // Include props if requested
+        if (include_props) {
+            const propSections = content.match(/(mode|prop|Properties|API)[\s\S]*?(?=\n##|\n\[#|$)/gi) ??
+                [];
+            if (propSections.length > 0) {
+                response += `**Props & API:**\n${propSections
+                    .slice(0, 3)
+                    .join('\n\n')}\n\n`;
+            }
+        }
+        // Include examples if requested
+        if (include_examples) {
+            const codeBlocks = content.match(/```[\s\S]*?```/g) ?? [];
+            const jsxBlocks = content.match(/<Iress[A-Z][^>]*>[\s\S]*?<\/Iress[A-Z][^>]*>/g) ?? [];
+            const examples = [...codeBlocks, ...jsxBlocks];
+            if (examples.length > 0) {
+                response += `**Usage Examples:**\n${examples
+                    .slice(0, 3)
+                    .join('\n\n')}\n\n`;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: response,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Failed to read component documentation: ${errorMessage}`);
+    }
+}
+function formatComponentDetails(componentName, componentFile) {
+    if (!componentFile) {
+        return `**${componentName}** ❌ Not found\n\n`;
+    }
+    try {
+        const filePath = path.join(DOCS_DIR, componentFile);
+        const content = readFileContent(filePath);
+        const lines = content.split('\n');
+        const description = lines
+            .slice(0, 20)
+            .find((line) => line.trim() &&
+            !line.startsWith('#') &&
+            !line.startsWith('<!--') &&
+            !line.includes('Overview') &&
+            line.length > 20)
+            ?.trim() ?? 'IDS component';
+        return `**${componentName}** ✅\n  - File: ${componentFile}\n  - Description: ${description}\n\n`;
+    }
+    catch {
+        return `**${componentName}** ❌\n  - Error reading documentation\n\n`;
+    }
+}
+function formatComponentSummary(componentName, componentFile) {
+    const status = componentFile ? '✅ Available' : '❌ Not found';
+    let result = `**${componentName}** ${status}\n`;
+    if (componentFile) {
+        result += `  - Documentation: ${componentFile}\n`;
+    }
+    return result + '\n';
+}
+export function handleAnalyzeComponentMentions(args) {
+    const schema = z.object({
+        text: z.string(),
+        detailed: z.boolean().default(false),
+    });
+    const { text, detailed } = schema.parse(args);
+    const componentMentions = extractIressComponents(text);
+    if (componentMentions.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: "No Iress component mentions found in the provided text. Components should be mentioned with the 'Iress' prefix (e.g., IressButton, IressInput).",
+                },
+            ],
+        };
+    }
+    let response = `**Found ${componentMentions.length} Iress component mention(s):**\n\n`;
+    for (const componentName of componentMentions) {
+        const componentFile = mapIressComponentToFile(componentName);
+        if (detailed && componentFile) {
+            response += formatComponentDetails(componentName, componentFile);
+        }
+        else {
+            response += formatComponentSummary(componentName, componentFile);
+        }
+    }
+    if (!detailed &&
+        componentMentions.some((name) => mapIressComponentToFile(name))) {
+        response +=
+            '\n*Use the `get_iress_component_info` tool with a specific component name for detailed information.*';
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: response,
+            },
+        ],
+    };
+}

package/dist/iressHandlers.test.js

@@ -0,0 +1,316 @@
+/**
+ * Tests for Iress component handlers
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { handleGetIressComponentInfo, handleAnalyzeComponentMentions, } from './iressHandlers.js';
+import * as utils from './utils.js';
+// Mock the utils module
+vi.mock('./utils.js', () => ({
+    mapIressComponentToFile: vi.fn(),
+    extractIressComponents: vi.fn(),
+    readFileContent: vi.fn(),
+}));
+// Mock the config module
+vi.mock('./config.js', () => ({
+    DOCS_DIR: '/mocked/docs/path',
+}));
+const mockUtils = vi.mocked(utils);
+describe('iressHandlers', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('handleGetIressComponentInfo', () => {
+        const mockComponentContent = `# IressButton Component
+
+## Overview
+The IressButton component is a versatile button component for the Iress Design System.
+
+## Props
+- \`variant\`: string - The button variant (primary, secondary, etc.)
+- \`size\`: string - The button size (small, medium, large)
+- \`disabled\`: boolean - Whether the button is disabled
+
+## Examples
+\`\`\`jsx
+<IressButton variant="primary" size="medium">
+  Click me
+</IressButton>
+\`\`\`
+
+## API Reference
+Additional API documentation here.
+`;
+        it('should return component information with examples and props by default', () => {
+            const args = {
+                component_name: 'IressButton',
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockComponentContent);
+            const result = handleGetIressComponentInfo(args);
+            expect(mockUtils.mapIressComponentToFile).toHaveBeenCalledWith('IressButton');
+            expect(mockUtils.readFileContent).toHaveBeenCalledWith('/mocked/docs/path/components-button-docs.md');
+            expect(result.content).toHaveLength(1);
+            expect(result.content[0].type).toBe('text');
+            expect(result.content[0].text).toContain('**IressButton Component Documentation**');
+            expect(result.content[0].text).toContain('The IressButton component is a versatile button component');
+            expect(result.content[0].text).toContain('**Props & API:**');
+            expect(result.content[0].text).toContain('**Usage Examples:**');
+            expect(result.content[0].text).toContain('<IressButton variant="primary"');
+        });
+        it('should include examples when include_examples is true', () => {
+            const args = {
+                component_name: 'IressButton',
+                include_examples: true,
+                include_props: false,
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockComponentContent);
+            const result = handleGetIressComponentInfo(args);
+            expect(result.content[0].text).toContain('**Usage Examples:**');
+            expect(result.content[0].text).not.toContain('**Props & API:**');
+        });
+        it('should include props when include_props is true', () => {
+            const args = {
+                component_name: 'IressButton',
+                include_examples: false,
+                include_props: true,
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockComponentContent);
+            const result = handleGetIressComponentInfo(args);
+            expect(result.content[0].text).toContain('**Props & API:**');
+            expect(result.content[0].text).not.toContain('**Usage Examples:**');
+        });
+        it('should exclude examples and props when both flags are false', () => {
+            const args = {
+                component_name: 'IressButton',
+                include_examples: false,
+                include_props: false,
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockComponentContent);
+            const result = handleGetIressComponentInfo(args);
+            expect(result.content[0].text).not.toContain('**Usage Examples:**');
+            expect(result.content[0].text).not.toContain('**Props & API:**');
+            expect(result.content[0].text).toContain('**IressButton Component Documentation**');
+        });
+        it('should return error message when component is not found', () => {
+            const args = {
+                component_name: 'IressNonExistent',
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue(null);
+            const result = handleGetIressComponentInfo(args);
+            expect(result.content).toHaveLength(1);
+            expect(result.content[0].type).toBe('text');
+            expect(result.content[0].text).toContain('Component "IressNonExistent" not found');
+            expect(result.content[0].text).toContain("Make sure you're using the correct Iress component name");
+        });
+        it('should throw error when file reading fails', () => {
+            const args = {
+                component_name: 'IressButton',
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockImplementation(() => {
+                throw new Error('File not accessible');
+            });
+            expect(() => handleGetIressComponentInfo(args)).toThrow('Failed to read component documentation: File not accessible');
+        });
+        it('should validate input parameters using zod schema', () => {
+            const invalidArgs = {
+                component_name: 123, // Should be string
+            };
+            expect(() => handleGetIressComponentInfo(invalidArgs)).toThrow();
+        });
+        it('should handle missing optional parameters with defaults', () => {
+            const args = {
+                component_name: 'IressButton',
+                // include_examples and include_props not provided, should default to true
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockComponentContent);
+            const result = handleGetIressComponentInfo(args);
+            expect(result.content[0].text).toContain('**Usage Examples:**');
+            expect(result.content[0].text).toContain('**Props & API:**');
+        });
+        it('should limit examples and prop sections to 3 items each', () => {
+            const contentWithMultipleExamples = `# IressButton
+
+## Overview
+Button component
+
+## Props
+First prop section
+## API
+Second API section
+## Properties
+Third properties section
+## Mode
+Fourth mode section
+
+\`\`\`jsx
+Example 1
+\`\`\`
+
+\`\`\`jsx
+Example 2
+\`\`\`
+
+\`\`\`jsx
+Example 3
+\`\`\`
+
+\`\`\`jsx
+Example 4
+\`\`\`
+
+<IressButton>Example 5</IressButton>
+`;
+            const args = {
+                component_name: 'IressButton',
+            };
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(contentWithMultipleExamples);
+            const result = handleGetIressComponentInfo(args);
+            // Should limit to 3 prop sections and 3 examples
+            const propMatches = result.content[0].text.match(/First prop section|Second API section|Third properties section|Fourth mode section/g);
+            const exampleMatches = result.content[0].text.match(/Example [1-5]/g);
+            expect(propMatches?.length).toBeLessThanOrEqual(3);
+            expect(exampleMatches?.length).toBeLessThanOrEqual(3);
+        });
+    });
+    describe('handleAnalyzeComponentMentions', () => {
+        it('should analyze text and find component mentions', () => {
+            const args = {
+                text: 'Use IressButton and IressInput components in your form.',
+                detailed: false,
+            };
+            mockUtils.extractIressComponents.mockReturnValue([
+                'IressButton',
+                'IressInput',
+            ]);
+            // Mock the function to return files for both calls
+            mockUtils.mapIressComponentToFile.mockImplementation((name) => {
+                if (name === 'IressButton')
+                    return 'components-button-docs.md';
+                if (name === 'IressInput')
+                    return 'components-input-docs.md';
+                return null;
+            });
+            const result = handleAnalyzeComponentMentions(args);
+            expect(mockUtils.extractIressComponents).toHaveBeenCalledWith('Use IressButton and IressInput components in your form.');
+            expect(result.content).toHaveLength(1);
+            expect(result.content[0].type).toBe('text');
+            expect(result.content[0].text).toContain('Found 2 Iress component mention(s)');
+            expect(result.content[0].text).toContain('**IressButton** ✅ Available');
+            expect(result.content[0].text).toContain('**IressInput** ✅ Available');
+            expect(result.content[0].text).toContain('*Use the `get_iress_component_info` tool with a specific component name for detailed information.*');
+        });
+        it('should provide detailed information when detailed flag is true', () => {
+            const args = {
+                text: 'Use IressButton component.',
+                detailed: true,
+            };
+            const mockFileContent = `# IressButton
+A great button component for interactive elements.
+## Props
+- variant: string
+`;
+            mockUtils.extractIressComponents.mockReturnValue(['IressButton']);
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockFileContent);
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).toContain('**IressButton** ✅');
+            expect(result.content[0].text).toContain('File: components-button-docs.md');
+            expect(result.content[0].text).toContain('Description: A great button component');
+        });
+        it('should handle components that are not found', () => {
+            const args = {
+                text: 'Use IressNonExistent component.',
+                detailed: false,
+            };
+            mockUtils.extractIressComponents.mockReturnValue(['IressNonExistent']);
+            mockUtils.mapIressComponentToFile.mockReturnValue(null);
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).toContain('**IressNonExistent** ❌ Not found');
+        });
+        it('should return appropriate message when no components are found', () => {
+            const args = {
+                text: 'This text has no component mentions.',
+                detailed: false,
+            };
+            mockUtils.extractIressComponents.mockReturnValue([]);
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).toContain('No Iress component mentions found');
+            expect(result.content[0].text).toContain("Components should be mentioned with the 'Iress' prefix");
+        });
+        it('should handle file reading errors in detailed mode gracefully', () => {
+            const args = {
+                text: 'Use IressButton component.',
+                detailed: true,
+            };
+            mockUtils.extractIressComponents.mockReturnValue(['IressButton']);
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockImplementation(() => {
+                throw new Error('File read error');
+            });
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).toContain('**IressButton** ❌');
+            expect(result.content[0].text).toContain('Error reading documentation');
+        });
+        it('should validate input parameters using zod schema', () => {
+            const invalidArgs = {
+                text: 123, // Should be string
+            };
+            expect(() => handleAnalyzeComponentMentions(invalidArgs)).toThrow();
+        });
+        it('should handle missing optional detailed parameter with default false', () => {
+            const args = {
+                text: 'Use IressButton component.',
+                // detailed not provided, should default to false
+            };
+            mockUtils.extractIressComponents.mockReturnValue(['IressButton']);
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            const result = handleAnalyzeComponentMentions(args);
+            // Should use summary format (not detailed)
+            expect(result.content[0].text).toContain('**IressButton** ✅ Available');
+            expect(result.content[0].text).not.toContain('Description:');
+        });
+        it('should not show detailed info prompt when detailed is true', () => {
+            const args = {
+                text: 'Use IressButton component.',
+                detailed: true,
+            };
+            const mockFileContent = 'Button documentation';
+            mockUtils.extractIressComponents.mockReturnValue(['IressButton']);
+            mockUtils.mapIressComponentToFile.mockReturnValue('components-button-docs.md');
+            mockUtils.readFileContent.mockReturnValue(mockFileContent);
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).not.toContain('*Use the `get_iress_component_info` tool with a specific component name for detailed information.*');
+        });
+        it('should handle mixed found and not found components', () => {
+            const args = {
+                text: 'Use IressButton and IressNonExistent components.',
+                detailed: false,
+            };
+            mockUtils.extractIressComponents.mockReturnValue([
+                'IressButton',
+                'IressNonExistent',
+            ]);
+            // Mock the function to return different results for each component
+            mockUtils.mapIressComponentToFile.mockImplementation((name) => {
+                if (name === 'IressButton')
+                    return 'components-button-docs.md';
+                if (name === 'IressNonExistent')
+                    return null;
+                return null;
+            });
+            const result = handleAnalyzeComponentMentions(args);
+            expect(result.content[0].text).toContain('**IressButton** ✅ Available');
+            expect(result.content[0].text).toContain('**IressNonExistent** ❌ Not found');
+            expect(result.content[0].text).toContain('*Use the `get_iress_component_info` tool with a specific component name for detailed information.*');
+        });
+    });
+});

package/dist/resourceHandlers.js

@@ -0,0 +1,67 @@
+/**
+ * Resource handlers for MCP server
+ */
+import * as path from 'path';
+import { getMarkdownFiles, readFileContent } from './utils.js';
+import { DOCS_DIR } from './config.js';
+export function handleListResources() {
+    const markdownFiles = getMarkdownFiles();
+    // Categorize resources for better organization
+    const categorizedResources = markdownFiles.map((file) => {
+        let category = 'Other';
+        let name = file;
+        if (file.startsWith('components-')) {
+            category = 'Components';
+            name = file.replace('components-', '').replace('-docs.md', '');
+        }
+        else if (file.startsWith('foundations-')) {
+            category = 'Foundations';
+            name = file.replace('foundations-', '').replace('-docs.md', '');
+        }
+        else if (file.startsWith('resources-')) {
+            category = 'Resources';
+            name = file.replace('resources-', '').replace('-docs.md', '');
+        }
+        else if (file.includes('introduction')) {
+            category = 'Getting Started';
+            name = 'Introduction';
+        }
+        return {
+            uri: `file://${path.join(DOCS_DIR, file)}`,
+            name: `${category}: ${name}`,
+            description: `IDS ${category.toLowerCase()} documentation for ${name}`,
+            mimeType: 'text/markdown',
+        };
+    });
+    return {
+        resources: categorizedResources,
+    };
+}
+export function handleReadResource(request) {
+    const url = new URL(request.params.uri);
+    if (url.protocol !== 'file:') {
+        throw new Error(`Unsupported protocol: ${url.protocol}`);
+    }
+    const filePath = url.pathname;
+    // Ensure the file is within our docs directory
+    const relativePath = path.relative(DOCS_DIR, filePath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error('Access denied: File is outside the docs directory');
+    }
+    try {
+        const content = readFileContent(filePath);
+        return {
+            contents: [
+                {
+                    uri: request.params.uri,
+                    mimeType: 'text/markdown',
+                    text: content,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Failed to read file: ${errorMessage}`);
+    }
+}