impact-ui-mcp-server 1.0.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "impact-ui-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for Impact UI Library - Provides AI access to component documentation and code examples",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "impact-ui-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "DEPLOYMENT.md",
+    "QUICK_SETUP.md",
+    "QUICKSTART.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "generate-config": "node generate-cursor-config.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ui-library",
+    "component-documentation",
+    "impact-ui",
+    "cursor",
+    "claude"
+  ],
+  "author": "Impact Analytics",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/impact-analytics/impact-ui.git",
+    "directory": "mcp-server"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "glob": "^10.3.10",
+    "fs-extra": "^11.1.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,565 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { glob } from "glob";
+import { join } from "path";
+import { parseStorybookStory } from "./parsers/storybookParser.js";
+import { parseComponentFile } from "./parsers/componentParser.js";
+import { getProjectRoot } from "./utils/fileReader.js";
+import { getComponentInfo } from "./tools/componentInfo.js";
+import { generateCodeExample } from "./tools/codeExample.js";
+
+// Component registry - populated on startup
+let componentRegistry = {};
+
+/**
+ * Discover and parse all components from Storybook stories
+ */
+async function buildComponentRegistry() {
+  const projectRoot = getProjectRoot();
+  const storiesPath = join(projectRoot, "src/stories");
+  const componentsPath = join(projectRoot, "src/components");
+
+  console.error("Building component registry...");
+
+  // Find all story files
+  const storyFiles = await glob("*.stories.js", { cwd: storiesPath });
+  
+  for (const file of storyFiles) {
+    const storyFilePath = join(storiesPath, file);
+    const componentName = file.replace(".stories.js", "");
+    
+    // Parse storybook story
+    const storyMetadata = parseStorybookStory(storyFilePath, componentName);
+    
+    if (!storyMetadata) {
+      console.error(`Failed to parse story for ${componentName}`);
+      continue;
+    }
+
+    // Try to find component file
+    const componentFile = await findComponentFile(componentsPath, componentName);
+    let componentInfo = null;
+    
+    if (componentFile) {
+      componentInfo = parseComponentFile(componentFile, componentName);
+    }
+
+    // Merge story metadata with component info
+    componentRegistry[componentName] = {
+      ...storyMetadata,
+      componentFile: componentFile || null,
+      componentInfo: componentInfo,
+    };
+  }
+
+  console.error(`Loaded ${Object.keys(componentRegistry).length} components`);
+}
+
+/**
+ * Find component file in components directory
+ */
+async function findComponentFile(componentsPath, componentName) {
+  const { existsSync } = await import("fs");
+  const possiblePaths = [
+    join(componentsPath, componentName, "index.js"),
+    join(componentsPath, componentName, `${componentName}.js`),
+    join(componentsPath, componentName, `${componentName}.jsx`),
+    join(componentsPath, componentName, "index.jsx"),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      if (existsSync(path)) {
+        return path;
+      }
+    } catch {
+      // Continue searching
+    }
+  }
+
+  return null;
+}
+
+// Initialize MCP Server
+const server = new Server(
+  {
+    name: "impact-ui-mcp-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_component_info",
+        description: "Get detailed information about a specific UI component including props, description, usage examples, and file locations",
+        inputSchema: {
+          type: "object",
+          properties: {
+            componentName: {
+              type: "string",
+              description: "Name of the component (e.g., 'Button', 'Modal', 'Table'). Use list_components to see all available components.",
+            },
+          },
+          required: ["componentName"],
+        },
+      },
+      {
+        name: "list_components",
+        description: "List all available UI components in the library, optionally filtered by category",
+        inputSchema: {
+          type: "object",
+          properties: {
+            category: {
+              type: "string",
+              description: "Optional: Filter by category - 'Components' or 'Patterns'",
+              enum: ["Components", "Patterns"],
+            },
+          },
+        },
+      },
+      {
+        name: "get_component_props",
+        description: "Get all props for a component with their types, defaults, descriptions, and whether they're required",
+        inputSchema: {
+          type: "object",
+          properties: {
+            componentName: {
+              type: "string",
+              description: "Name of the component",
+            },
+          },
+          required: ["componentName"],
+        },
+      },
+      {
+        name: "generate_code_example",
+        description: "Generate a ready-to-use code example for a component with specified props. Automatically includes state management for components that need it (like Modal, Panel, etc.)",
+        inputSchema: {
+          type: "object",
+          properties: {
+            componentName: {
+              type: "string",
+              description: "Name of the component",
+            },
+            props: {
+              type: "object",
+              description: "Props to include in the example (optional). Key-value pairs where keys are prop names and values are prop values.",
+            },
+          },
+          required: ["componentName"],
+        },
+      },
+      {
+        name: "search_components",
+        description: "Search for components by name or description. Useful for finding components when you don't know the exact name.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Search query to match against component names or descriptions",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "get_component_usage_tips",
+        description: "Get best practices, usage tips, and common patterns for using a component",
+        inputSchema: {
+          type: "object",
+          properties: {
+            componentName: {
+              type: "string",
+              description: "Name of the component",
+            },
+          },
+          required: ["componentName"],
+        },
+      },
+    ],
+  };
+});
+
+// List available resources (components)
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const resources = Object.values(componentRegistry)
+    .sort((a, b) => {
+      // Sort by category first, then by name
+      if (a.category !== b.category) {
+        return a.category.localeCompare(b.category);
+      }
+      return a.name.localeCompare(b.name);
+    })
+    .map((component) => ({
+      uri: `impact-ui://component/${component.name}`,
+      name: component.name,
+      description: component.description || `Component: ${component.name}`,
+      mimeType: "application/json",
+    }));
+
+  return {
+    resources,
+  };
+});
+
+// Fetch a specific component resource
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  // Parse the URI: impact-ui://component/ComponentName
+  const match = uri.match(/^impact-ui:\/\/component\/(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid resource URI: ${uri}`);
+  }
+
+  const componentName = match[1];
+  const component = componentRegistry[componentName];
+
+  if (!component) {
+    throw new Error(`Component '${componentName}' not found`);
+  }
+
+  // Format component data as JSON
+  const componentData = {
+    name: component.name,
+    category: component.category,
+    description: component.description,
+    props: component.props,
+    examples: component.examples || [],
+    storyFile: component.storyFile,
+    componentFile: component.componentFile,
+  };
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(componentData, null, 2),
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "get_component_info": {
+        const result = getComponentInfo(componentRegistry, args.componentName);
+        
+        if (!result.found) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: result.message,
+              },
+            ],
+          };
+        }
+
+        // Format the response nicely
+        const component = result.component;
+        let response = `# ${component.name}\n\n`;
+        response += `**Category:** ${component.category}\n\n`;
+        response += `**Description:**\n${component.description}\n\n`;
+        
+        if (Object.keys(component.props).length > 0) {
+          response += `**Props:**\n`;
+          for (const [propName, propInfo] of Object.entries(component.props)) {
+            response += `- \`${propName}\` (${propInfo.type})`;
+            if (propInfo.defaultValue !== undefined) {
+              response += ` - Default: ${JSON.stringify(propInfo.defaultValue)}`;
+            }
+            if (propInfo.required) {
+              response += ` - **Required**`;
+            }
+            response += `\n  ${propInfo.description}\n`;
+          }
+        }
+
+        if (component.examples && component.examples.length > 0) {
+          response += `\n**Available Examples:** ${component.examples.join(", ")}\n`;
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      case "list_components": {
+        let components = Object.values(componentRegistry);
+        
+        if (args.category) {
+          components = components.filter((c) => c.category === args.category);
+        }
+
+        const componentNames = components.map((c) => c.name).sort();
+        
+        const categorized = {};
+        for (const comp of components) {
+          if (!categorized[comp.category]) {
+            categorized[comp.category] = [];
+          }
+          categorized[comp.category].push(comp.name);
+        }
+
+        let response = "## Available Components\n\n";
+        for (const [category, names] of Object.entries(categorized)) {
+          response += `### ${category}\n`;
+          response += names.sort().join(", ") + "\n\n";
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      case "get_component_props": {
+        const component = componentRegistry[args.componentName];
+        
+        if (!component) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Component '${args.componentName}' not found. Use list_components to see available components.`,
+              },
+            ],
+          };
+        }
+
+        if (Object.keys(component.props).length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Component '${args.componentName}' has no documented props.`,
+              },
+            ],
+          };
+        }
+
+        let response = `# ${args.componentName} Props\n\n`;
+        
+        for (const [propName, propInfo] of Object.entries(component.props)) {
+          response += `## ${propName}\n`;
+          response += `- **Type:** ${propInfo.type}\n`;
+          if (propInfo.defaultValue !== undefined) {
+            response += `- **Default:** ${JSON.stringify(propInfo.defaultValue)}\n`;
+          }
+          if (propInfo.required) {
+            response += `- **Required:** Yes\n`;
+          }
+          if (propInfo.options) {
+            response += `- **Options:** ${propInfo.options.join(", ")}\n`;
+          }
+          response += `- **Description:** ${propInfo.description}\n\n`;
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      case "generate_code_example": {
+        const result = generateCodeExample(
+          componentRegistry,
+          args.componentName,
+          args.props || {}
+        );
+
+        if (result.error) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: result.error,
+              },
+            ],
+          };
+        }
+
+        let response = `## Code Example for ${args.componentName}\n\n`;
+        response += "```jsx\n";
+        response += result.example;
+        response += "\n```\n";
+
+        if (result.basicExample) {
+          response += "\n## Basic Example (without state)\n\n";
+          response += "```jsx\n";
+          response += result.basicExample;
+          response += "\n```\n";
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      case "search_components": {
+        const query = args.query.toLowerCase();
+        const matches = Object.values(componentRegistry).filter(
+          (comp) =>
+            comp.name.toLowerCase().includes(query) ||
+            comp.description.toLowerCase().includes(query) ||
+            Object.keys(comp.props).some((prop) =>
+              prop.toLowerCase().includes(query)
+            )
+        );
+
+        if (matches.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No components found matching '${args.query}'`,
+              },
+            ],
+          };
+        }
+
+        let response = `## Search Results for "${args.query}"\n\n`;
+        for (const comp of matches) {
+          response += `### ${comp.name}\n`;
+          response += `${comp.description}\n`;
+          response += `**Category:** ${comp.category}\n\n`;
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      case "get_component_usage_tips": {
+        const component = componentRegistry[args.componentName];
+        
+        if (!component) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Component '${args.componentName}' not found.`,
+              },
+            ],
+          };
+        }
+
+        let response = `# Usage Tips for ${args.componentName}\n\n`;
+        response += `## Description\n${component.description}\n\n`;
+
+        // Extract tips from description
+        const tips = [];
+        if (component.description.includes("Note:")) {
+          const noteMatch = component.description.match(/Note:([^\n]+)/i);
+          if (noteMatch) {
+            tips.push(noteMatch[1].trim());
+          }
+        }
+
+        // Add prop-specific tips
+        response += `## Important Props\n\n`;
+        const importantProps = Object.entries(component.props)
+          .filter(([_, info]) => info.required || info.description.length > 50)
+          .slice(0, 5);
+
+        for (const [propName, propInfo] of importantProps) {
+          response += `- **${propName}**: ${propInfo.description}\n`;
+        }
+
+        if (component.examples && component.examples.length > 0) {
+          response += `\n## Available Examples\n`;
+          response += `Check Storybook for these examples: ${component.examples.join(", ")}\n`;
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: response,
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error.message}\n\nStack: ${error.stack}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  try {
+    await buildComponentRegistry();
+    
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    
+    console.error("Impact UI MCP Server running on stdio");
+  } catch (error) {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/parsers/componentParser.js

@@ -0,0 +1,68 @@
+import { readFile } from "../utils/fileReader.js";
+
+/**
+ * Parse component source file to extract PropTypes or additional info
+ */
+export function parseComponentFile(filePath, componentName) {
+  const content = readFile(filePath);
+  if (!content) {
+    return null;
+  }
+
+  const info = {
+    hasPropTypes: false,
+    propTypes: {},
+    imports: [],
+    exports: [],
+  };
+
+  // Extract PropTypes
+  const propTypesMatch = content.match(
+    /(?:\.propTypes\s*=|PropTypes\.shape\(|PropTypes\.exact\()\s*{([\s\S]*?)}/m
+  );
+  if (propTypesMatch) {
+    info.hasPropTypes = true;
+    info.propTypes = parsePropTypes(propTypesMatch[1]);
+  }
+
+  // Extract imports
+  const importMatches = content.matchAll(
+    /import\s+(?:{([^}]+)}|(\w+)|(\*\s+as\s+\w+))\s+from\s+["']([^"']+)["']/g
+  );
+  for (const match of importMatches) {
+    info.imports.push({
+      source: match[4],
+      named: match[1] || match[2] || match[3],
+    });
+  }
+
+  // Extract exports
+  const exportMatches = content.matchAll(
+    /export\s+(?:const|function|class)\s+(\w+)/g
+  );
+  for (const match of exportMatches) {
+    info.exports.push(match[1]);
+  }
+
+  return info;
+}
+
+/**
+ * Parse PropTypes definition
+ */
+function parsePropTypes(propTypesContent) {
+  const propTypes = {};
+  
+  // Match PropTypes definitions like: propName: PropTypes.string
+  const propRegex = /(\w+):\s*PropTypes\.(\w+)(?:\.isRequired)?/g;
+  let match;
+
+  while ((match = propRegex.exec(propTypesContent)) !== null) {
+    propTypes[match[1]] = {
+      type: match[2],
+      required: propTypesContent.includes(`${match[1]}: PropTypes.${match[2]}.isRequired`),
+    };
+  }
+
+  return propTypes;
+}