@iress-oss/ids-mcp-server 6.0.0-alpha.3 → 6.0.0-alpha.30

package/README.md

@@ -1,15 +1,17 @@
 # IDS Component Library MCP Server
 
+> **⚠️ DEPRECATED** — This package is deprecated. AI context is now provided via static `.ai/` folders and `.agents/skills/` files in the repository. These deliver the same information without runtime dependencies, Playwright, or Storybook. See `packages/components/.ai/`, `packages/tokens/.ai/`, and `.agents/skills/` for the replacement.
+
 A Model Context Protocol (MCP) server specifically designed for the **Iress Design System (IDS)** component library. This server provides AI assistants and MCP clients with contextual information about IDS components, design tokens, usage patterns, and implementation details to help engineers build consistent user interfaces.
 
 ## Features
 
-- **Component Discovery**: Find IDS components by name or functionality
+- **Component Discovery**: Find IDS components and patterns by name or functionality
 - **Props & API Reference**: Get detailed component prop information and usage examples
 - **Usage Examples**: Real-world React code examples and implementation patterns
 - **Design Tokens**: Access to IDS design tokens (colors, spacing, typography)
 - **Smart Search**: Search across all IDS documentation with context-aware results
-- **Categorized Resources**: Organized by Components, Foundations, and Resources
+- **Categorized Resources**: Organized by Components, Patterns, Foundations, and Resources
 - **Engineer-Focused**: Tools designed specifically for UI development workflows
 
 ## Installation
@@ -54,18 +56,187 @@ For other MCP clients or manual configuration, use this server configuration:
 
 ## Available Tools
 
-1. **find_component**: Find IDS components by name or functionality - perfect for component discovery
+### Component Discovery & Implementation
+
+1. **find_component**: Find IDS components and patterns by name or functionality - supports both components and patterns (e.g., IressForm, IressButton)
 2. **get_component_props**: Get detailed prop information and API reference for specific components
 3. **get_usage_examples**: Get real-world React code examples and implementation patterns
-4. **search_ids_docs**: Search across all IDS documentation with context-aware results
-5. **list_components**: List all available components organized by category
-6. **get_design_tokens**: Access IDS design tokens (colors, spacing, typography, etc.)
+4. **get_iress_component_info**: Get comprehensive information about Iress components mentioned by their full name (e.g., IressButton, IressInput)
+5. **analyze_component_mentions**: Analyze text to find all Iress component mentions and provide information about each one
+
+### Design Tokens & Styling
+
+6. **get_design_tokens**: Access IDS design tokens (colors, spacing, typography, etc.) with token definitions and values
+7. **get_design_tokens_usage**: Get token usage examples, best practices, and anti-patterns with ✅ DO / ❌ DON'T examples
+   - Shows when to use tokens vs hardcoded values
+   - Demonstrates proper styling prop usage
+   - Includes accessibility guidelines for colors
+   - Covers spacing scale and directional props
+   - Explains IressText vs textStyle prop for typography
+8. **get_styling_props_reference**: Get comprehensive reference for IDS styling props including spacing, colors, typography, visual effects, and sizing
+   - Shows available props by category (spacing, colors, typography, visual, sizing, utility)
+   - Includes usage examples and token values
+   - Explains when to use style props vs iressCss() vs CSS-in-JS
+   - Provides component-specific styling guidance
+
+### Documentation & Guidelines
+
+9. **search_ids_docs**: Search across all IDS documentation with context-aware results
+10. **list_components**: List all available components organized by category
+11. **get_design_guidelines**: Get IDS design guidelines covering core principles, visual standards, and accessibility requirements
+
+## Design Token Usage Quick Start
+
+The IDS MCP Server provides comprehensive guidance on using design tokens correctly:
+
+### Using `get_design_tokens_usage`
+
+```typescript
+// Get color token usage examples
+get_design_tokens_usage({ category: 'colors' });
+// Returns: Semantic color tokens, ✅ DO/❌ DON'T examples, accessibility guidelines
+
+// Get spacing token usage examples
+get_design_tokens_usage({ category: 'spacing' });
+// Returns: Spacing scale (xs, sm, md, lg, xl), directional props, responsive patterns
+
+// Get typography usage examples
+get_design_tokens_usage({ category: 'typography' });
+// Returns: IressText component usage, textStyle prop examples
+
+// Get best practices and anti-patterns
+get_design_tokens_usage({ category: 'best-practices' });
+// Returns: When to use styling props vs iressCss() vs custom CSS, common mistakes
+
+// Get all usage guidance
+get_design_tokens_usage({ category: 'all' });
+// Returns: Complete guide with all categories
+```
+
+### Best Practices for AI Code Generation
+
+When generating code with the IDS component library:
+
+1. **Always use design tokens** instead of hardcoded values:
+   - ✅ `<IressPanel p="md" bg="colour.primary.fill">`
+   - ❌ `<IressPanel style={{ padding: '16px', backgroundColor: '#13213F' }}>`
+
+2. **Prefer styling props** over inline styles or custom CSS:
+   - ✅ `<IressPanel p="lg" color="colour.primary.text">`
+   - ❌ `<div className="custom-padding" style={{ color: '#000' }}>`
+
+3. **Use IressText** for text content (preferred over textStyle prop):
+   - ✅ `<IressText element="h1">Heading</IressText>`
+   - ❌ `<h1 style={{ fontSize: '24px' }}>Heading</h1>`
+
+4. **Pair bg and color props** for accessibility:
+   - ✅ `<IressPanel bg="colour.primary.fill" color="colour.primary.onFill">`
+   - ❌ `<IressPanel bg="colour.primary.fill">` (missing color)
+
+5. **For CSS-in-JS, use cssVars from @iress-oss/ids-tokens**:
+   - ✅ `background: ${cssVars.colour.primary.fill}; padding: ${cssVars.spacing[400]};`
+   - ❌ `background: '#13213F'; padding: '16px';`
+
+Use `get_design_tokens_usage` to see practical examples and anti-patterns for each category.
+
+## Styling Props Quick Start
+
+The IDS MCP Server provides comprehensive reference for using styling props across all components:
+
+### Using `get_styling_props_reference`
+
+```typescript
+// Get all styling props documentation
+get_styling_props_reference({ category: 'all' });
+// Returns: Complete reference + styling approach decision guide
+
+// Get spacing props (padding, margin, textAlign, stretch)
+get_styling_props_reference({ category: 'spacing' });
+// Returns: p, px, py, m, mx, my + token values
+
+// Get color props
+get_styling_props_reference({ category: 'colors' });
+// Returns: bg, color props with semantic color tokens
+
+// Get typography props
+get_styling_props_reference({ category: 'typography' });
+// Returns: textStyle prop usage
+
+// Get visual props (elevation, radius)
+get_styling_props_reference({ category: 'visual' });
+// Returns: layerStyle, borderRadius, focusable props
+
+// Get sizing props
+get_styling_props_reference({ category: 'sizing' });
+// Returns: width, maxWidth props
+
+// Get utility props (screen readers, scrollable, responsive)
+get_styling_props_reference({ category: 'utility' });
+// Returns: hideFrom, hideBelow, srOnly, scrollable, noGutter props
+
+// Get component-specific styling info
+get_styling_props_reference({ component: 'IressButton' });
+// Returns: Which styling props IressButton supports
+```
+
+### When to Use Different Styling Approaches
+
+The `get_styling_props_reference` tool includes comprehensive best practices from the IDS documentation (see the "Best Practices" section in the reference docs):
+
+1. **Style Props (Recommended)**: Use on IDS components for type-safe, theme-compatible inline styles
+   - `<IressButton p="md" bg="colour.primary.fill">`
+
+2. **iressCss() Function**: Use on non-IDS elements to apply styling props anywhere
+   - `<div className={iressCss({ p: 'xs', bg: 'neutral.alt' })}>`
+
+3. **IressStyled Component**: Use when you need styled wrapper without creating a component
+   - `<IressStyled p="md" bg="alt"><YourContent /></IressStyled>`
+
+4. **CSS-in-JS with cssVars**: Use with CSS-in-JS libraries (styled-components, emotion, etc.)
+   - `background: ${cssVars.colour.primary.fill};`
+
+5. **Custom CSS**: Use for complex styling, animations, pseudo-selectors
+   - When styling props aren't sufficient
+
+Use `get_styling_props_reference({ category: 'all' })` to see the complete reference including detailed best practices, decision guide with flowchart, common anti-patterns, and when to use each approach.
+
+### CSS-in-JS Usage
+
+When using CSS-in-JS libraries (styled-components, emotion, vanilla-extract, etc.), always use the `cssVars` object from `@iress-oss/ids-tokens`:
+
+```typescript
+import { cssVars } from '@iress-oss/ids-tokens';
+import styled from 'styled-components';
+
+// ✅ CORRECT - Using cssVars in CSS-in-JS
+const StyledComponent = styled.div`
+  padding: ${cssVars.spacing[400]}; /* md - 16px */
+  background-color: ${cssVars.colour.primary.fill};
+  color: ${cssVars.colour.primary.onFill};
+  font-family: ${cssVars.typography.fontFamily.body};
+`;
+
+// ❌ INCORRECT - Hardcoded values
+const BadComponent = styled.div`
+  padding: 16px;
+  background-color: #13213f;
+`;
+```
+
+**Available cssVars categories:**
+
+- `cssVars.colour.*` - All color tokens (primary, neutral, system)
+- `cssVars.spacing[*]` - Spacing scale (100, 200, 400, 600, 1200, etc.)
+- `cssVars.typography.*` - Font families, sizes, weights, line heights
+- `cssVars.radius[*]` - Border radius tokens
+- `cssVars.elevation.*` - Shadow and elevation tokens
 
 ## Available Resources
 
 All IDS component documentation files are exposed as categorized resources:
 
 - **Components**: Button, Input, Table, Modal, etc. (`components-*-docs.md`)
+- **Patterns**: Form, HookForm, etc. (`patterns-*-docs.md`)
 - **Foundations**: Colors, Typography, Spacing, etc. (`foundations-*-docs.md`)
 - **Resources**: Changelog, Guidelines, etc. (`resources-*-docs.md`)
 
@@ -81,6 +252,11 @@ The server works with the IDS component library documentation in the `generated/
 - `components-modal-docs.md` - IressModal component
 - `components-*-recipes-docs.md` - Usage patterns and recipes
 
+**Patterns** (Composite patterns and workflows):
+
+- `patterns-form-docs.md` - IressForm pattern
+- `patterns-hookform-docs.md` - IressHookForm pattern
+
 **Foundations** (Guidelines and tokens):
 
 - `foundations-colours-docs.md` - Color palette and usage

package/dist/componentHandlers.js

@@ -3,7 +3,7 @@
  */
 import { z } from 'zod';
 import * as path from 'path';
-import { getMarkdownFiles, mapIressComponentToFile, extractIressComponents, readFileContent, } from './utils.js';
+import { getMarkdownFiles, mapIressComponentToFile, extractIressComponents, readFileContent, parseMultiComponentQuery, } from './utils.js';
 import { DOCS_DIR } from './config.js';
 function checkIressComponentMatch(query) {
     if (query.startsWith('Iress')) {
@@ -44,6 +44,10 @@ function calculateRelevanceScore(file, content, query, lines) {
     // Lower relevance for content matches
     const contentMatches = content.toLowerCase().split(queryLower).length - 1;
     relevanceScore += contentMatches * 2;
+    // Boost pattern-based files as they're often searched for
+    if (file.startsWith('patterns-')) {
+        relevanceScore += 25;
+    }
     return relevanceScore;
 }
 function createSearchResult(file, relevanceScore, lines) {
@@ -60,12 +64,154 @@ function createSearchResult(file, relevanceScore, lines) {
         description: `${componentName}: ${description}`,
     };
 }
+/**
+ * Categorize file as component, pattern, or foundation
+ */
+function categorizeFile(filename) {
+    // New naming convention with namespace prefix
+    if (filename.startsWith('components_patterns-'))
+        return 'pattern';
+    if (filename.startsWith('components_foundations-'))
+        return 'foundation';
+    if (filename.startsWith('components_components-'))
+        return 'component';
+    // Legacy naming convention (without namespace prefix)
+    if (filename.startsWith('patterns-'))
+        return 'pattern';
+    if (filename.startsWith('foundations-'))
+        return 'foundation';
+    return 'component';
+}
+/**
+ * Extract description from documentation content
+ */
+function extractDescription(lines) {
+    // Look for first paragraph after title
+    const descriptionStart = lines.findIndex((line) => (line.startsWith('##') && !line.startsWith('###')) ||
+        (line.trim().length > 50 && !line.startsWith('#')));
+    if (descriptionStart === -1)
+        return '';
+    return lines[descriptionStart]
+        .replace(/^#+\s*/, '')
+        .trim()
+        .slice(0, 200);
+}
+/**
+ * Format individual component summary
+ */
+function formatComponentSummary(result) {
+    const typeEmoji = {
+        component: '🧩',
+        pattern: '📐',
+        foundation: '🏗️',
+    };
+    const emoji = result.type ? typeEmoji[result.type] : '📦';
+    const typeLabel = result.type
+        ? result.type.charAt(0).toUpperCase() + result.type.slice(1)
+        : 'Unknown';
+    let output = `${emoji} **${result.component}**\n`;
+    output += `Type: ${typeLabel}\n`;
+    if (result.file) {
+        output += `File: ${result.file}\n`;
+    }
+    output += `\n${result.description}\n`;
+    if (result.content) {
+        const contentPreview = result.content.slice(0, 500);
+        output += `\n\`\`\`\n${contentPreview}${result.content.length > 500 ? '...' : ''}\n\`\`\`\n`;
+    }
+    return output;
+}
+/**
+ * Format search results for multiple components
+ */
+function formatMultiComponentResults(results) {
+    const foundResults = results.filter((r) => r.found);
+    const notFoundResults = results.filter((r) => !r.found);
+    let output = '';
+    // Header summary
+    if (foundResults.length > 0) {
+        output += `Found ${foundResults.length} component${foundResults.length !== 1 ? 's' : ''}:\n\n`;
+    }
+    // Found components
+    for (const result of foundResults) {
+        output += formatComponentSummary(result);
+        output += '\n---\n\n';
+    }
+    // Not found components
+    if (notFoundResults.length > 0) {
+        output += `\n❌ Not found (${notFoundResults.length}):\n`;
+        for (const result of notFoundResults) {
+            output += `- ${result.component}\n`;
+        }
+    }
+    return output.trim();
+}
+/**
+ * Search for multiple components and return combined results
+ */
+function handleMultiComponentSearch(componentNames, category) {
+    const results = [];
+    for (const componentName of componentNames) {
+        // Map component to documentation file
+        const file = mapIressComponentToFile(componentName);
+        if (file) {
+            // Read and extract content
+            const filePath = path.join(DOCS_DIR, file);
+            const content = readFileContent(filePath);
+            const lines = content.split('\n');
+            // Extract metadata
+            const description = extractDescription(lines);
+            const type = categorizeFile(file);
+            // Apply category filter if provided
+            // Note: category uses plural form ('components'), type uses singular ('component')
+            const categoryMatchesType = (category === 'components' && type === 'component') ||
+                (category === 'foundations' && type === 'foundation') ||
+                (category === 'resources' && type === 'pattern'); // Patterns aren't in resources typically
+            if (category && !categoryMatchesType) {
+                // Skip components that don't match the category filter
+                continue;
+            }
+            results.push({
+                component: componentName,
+                found: true,
+                file,
+                type,
+                description,
+                content: content.slice(0, 1000), // First 1000 chars
+            });
+        }
+        else {
+            // Only add not-found components if no category filter, or always add them
+            results.push({
+                component: componentName,
+                found: false,
+                file: null,
+                type: null,
+                description: 'Component not found in documentation',
+            });
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: formatMultiComponentResults(results),
+            },
+        ],
+    };
+}
 export function handleFindComponent(args) {
     const schema = z.object({
         query: z.string(),
         category: z.enum(['components', 'foundations', 'resources']).optional(),
     });
     const { query, category } = schema.parse(args);
+    // ENHANCEMENT: Detect multiple components
+    const componentNames = parseMultiComponentQuery(query);
+    if (componentNames.length > 1) {
+        // Multi-component search
+        return handleMultiComponentSearch(componentNames, category);
+    }
     // Check if query is an Iress component name
     const iressMatch = checkIressComponentMatch(query);
     if (iressMatch) {
@@ -179,11 +325,25 @@ export function handleGetComponentProps(args) {
         const filePath = path.join(DOCS_DIR, componentFile);
         const content = readFileContent(filePath);
         const propSections = extractPropSections(content);
+        // Most IDS components support styling props - add helpful token usage guidance
+        // We include the hint for all components since even components without full styling props
+        // often accept margin/padding props, and the guidance is beneficial for AI code generation
+        const tokenUsageHint = '\n\n---\n\n**💡 Token Usage Tip**\n\n' +
+            'Most IDS components support styling props that accept design tokens. ' +
+            'Always prefer tokens over hardcoded values for consistency and theming support.\n\n' +
+            '**Common styling props:**\n' +
+            '- Spacing: `p="md"`, `m="lg"`, `px="sm"`, `py="xl"`\n' +
+            '- Colors: `bg="colour.primary.fill"`, `color="colour.primary.text"`\n' +
+            '- Typography: `textStyle="typography.heading.4"`\n' +
+            '- Layout: `maxWidth`, `width`, `textAlign`\n\n' +
+            '✅ **DO**: Use design tokens for consistency and theming\n' +
+            '❌ **DON\'T**: Use `style={{ padding: "16px" }}` or hardcoded colors\n\n' +
+            '*Use `get_design_tokens_usage` tool for complete token usage guidelines and best practices.*';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `**${component} Component Props & API**\n\n${formatPropsResponse(propSections, content, componentFile)}`,
+                    text: `**${component} Component Props & API**\n\n${formatPropsResponse(propSections, content, componentFile)}${tokenUsageHint}`,
                 },
             ],
         };