Impact UI MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Impact UI component library documentation, props, and code examples. This allows team members to query the UI library through natural language prompts without switching to Storybook or documentation.

🚀 Quick Start for Teams

Want to use this in your project? See DEPLOYMENT.md for complete setup instructions.

Quick setup:

1. Install: npm install @impact-analytics/impact-ui-mcp-server
2. Run setup script: npx @impact-analytics/impact-ui-mcp-server/setup-for-teams.sh
3. Add the generated config to Cursor settings
4. Restart Cursor IDE

Features

• 📋 Component Resources: Browse all components in a dropdown when selecting the MCP server
• 🔍 Component Discovery: List all available components or search by name/description
• 📖 Component Documentation: Get detailed information about any component including props, types, defaults, and descriptions
• 💻 Code Generation: Generate ready-to-use code examples with proper imports and state management
• 🎯 Smart Search: Search components by name, description, or prop names
• 📚 Usage Tips: Get best practices and usage patterns for components

Installation

1. Navigate to the mcp-server directory:

cd mcp-server

2. Install dependencies:

npm install

Configuration

For Cursor IDE ⭐ (Recommended)

Cursor IDE supports MCP servers through its settings. Here's how to configure it:

1. Open Cursor Settings:

   • Press Cmd+, (macOS) or Ctrl+, (Windows/Linux)
   • Or go to Cursor → Settings → Features → MCP

2. Add MCP Server Configuration:

   In your Cursor settings, add the following configuration. You can either:

   Option A: Via Settings UI

   • Navigate to Cursor → Settings → Features → MCP
   • Click "Add MCP Server"
   • Fill in:
     • Name: impact-ui
     • Command: node
     • Args: /absolute/path/to/impact-ui/mcp-server/src/index.js
     • Working Directory: /absolute/path/to/impact-ui/mcp-server

   Option B: Via settings.json

   Open your Cursor settings.json file:

   • Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
   • Type "Preferences: Open User Settings (JSON)"

   Add this configuration:

   {
     "mcp.servers": {
       "impact-ui": {
         "command": "node",
         "args": [
           "/absolute/path/to/impact-ui/mcp-server/src/index.js"
         ],
         "cwd": "/absolute/path/to/impact-ui/mcp-server"
       }
     }
   }

   Replace /absolute/path/to/impact-ui with your actual project path.

   To get your project path, run:

   cd /Users/narendrakumar/impact/impact-ui/mcp-server
   pwd

3. Restart Cursor IDE for the changes to take effect.

4. Verify it's working:

   • Open the Cursor chat (Cmd+L or Ctrl+L)
   • Try asking: "What components are available in the Impact UI library?"
   • The MCP server should automatically be used to answer your question

💡 Quick Tip: Run npm run generate-config in the mcp-server directory to automatically generate the correct configuration for your system!

For Claude Desktop

If you also use Claude Desktop, add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "impact-ui": {
      "command": "node",
      "args": [
        "/absolute/path/to/impact-ui/mcp-server/src/index.js"
      ],
      "cwd": "/absolute/path/to/impact-ui/mcp-server"
    }
  }
}

For Other MCP Clients

The server uses stdio transport, so it can be used with any MCP-compatible client. Configure your client to run:

node /path/to/mcp-server/src/index.js

Resources

When you select the Impact UI MCP server in Cursor, you'll see a dropdown list of all available components. You can:

1. Browse Components: Select any component from the dropdown to view its details
2. Ask Questions: After selecting a component, ask questions like:
   • "What props does this component accept?"
   • "Show me a code example"
   • "What are the best practices for using this component?"

Each component resource includes:

• Component name and category
• Full description
• All props with types, defaults, and descriptions
• Available Storybook examples
• File locations

Available Tools

1. get_component_info

Get detailed information about a specific component.

Example query: "What is the Button component and what props does it accept?"

2. list_components

List all available components, optionally filtered by category.

Example query: "List all components in the Patterns category"

3. get_component_props

Get all props for a component with types, defaults, and descriptions.

Example query: "What are all the props for the Modal component?"

4. generate_code_example

Generate a ready-to-use code example.

Example query: "Generate a code example for Modal with a title and primary button"

5. search_components

Search for components by name or description.

Example query: "Find components related to forms or inputs"

6. get_component_usage_tips

Get best practices and usage tips for a component.

Example query: "What are the best practices for using the Table component?"

Usage Examples

Once configured, you can ask questions like:

• "What components are available for building forms?"
• "Show me how to use the Button component with an icon"
• "What props does the Table component accept?"
• "Generate a code example for Modal with state management"
• "Find all components that have a 'size' prop"
• "What's the difference between Button variants?"

How It Works

1. Component Discovery: On startup, the server scans all Storybook story files (*.stories.js) in the frontend/src/stories directory.

2. Metadata Extraction: For each component, it extracts:

   • Component name and category (Components vs Patterns)
   • Description from Storybook
   • All props with types, defaults, descriptions, and options
   • Available story examples

3. Component File Parsing: It also attempts to find and parse the actual component source files to extract PropTypes and additional information.

4. Registry Building: All this information is stored in an in-memory registry for fast access.

5. Tool Handlers: When a tool is called, the server queries the registry and formats the response appropriately.

Development

Running in Development Mode

npm run dev

This will watch for file changes and restart the server.

Testing

You can test the server manually by running:

npm start

Then send JSON-RPC requests via stdin. For example:

{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

Project Structure

mcp-server/
├── src/
│   ├── index.js              # Main MCP server entry point
│   ├── tools/                # Tool implementations
│   │   ├── componentInfo.js
│   │   └── codeExample.js
│   ├── parsers/              # Parsers for extracting metadata
│   │   ├── storybookParser.js
│   │   └── componentParser.js
│   └── utils/                # Utility functions
│       └── fileReader.js
├── package.json
└── README.md

Troubleshooting

Server not starting

• Check that all dependencies are installed: npm install
• Verify the path to the frontend directory is correct
• Check that Storybook story files exist in frontend/src/stories

Components not found

• Ensure Storybook story files follow the naming convention: ComponentName.stories.js
• Check that the story files export a default object with title and component properties

Code examples not generating correctly

• Verify component names match exactly (case-sensitive)
• Check that props are valid for the component

License

MIT