impact-ui-mcp-server 1.0.0

package/DEPLOYMENT.md

@@ -0,0 +1,224 @@
+# Impact UI MCP Server - Deployment Guide
+
+This guide explains how to deploy and use the Impact UI MCP Server in other projects so teams can access Impact UI component documentation directly through their AI assistants.
+
+## Deployment Options
+
+### Option 1: NPM Package (Recommended for Teams)
+
+This is the recommended approach for teams that want to use the MCP server in their projects.
+
+#### Publishing the Package
+
+1. **From the Impact UI repository**, navigate to the mcp-server directory:
+   ```bash
+   cd mcp-server
+   ```
+
+2. **Publish to npm** (or your private npm registry):
+   ```bash
+   npm publish
+   ```
+   
+   For private registries:
+   ```bash
+   npm publish --registry=https://your-registry.com
+   ```
+
+#### Installing in Other Projects
+
+1. **Install the package** in your project:
+   ```bash
+   npm install @impact-analytics/impact-ui-mcp-server
+   ```
+
+2. **Configure Cursor IDE** to use the installed package:
+   
+   Open Cursor Settings (Cmd+Shift+P → "Preferences: Open User Settings (JSON)") and add:
+   
+   **If source files are included in the npm package (Option 1 - Recommended):**
+   ```json
+   {
+     "mcp.servers": {
+       "impact-ui": {
+         "command": "node",
+         "args": [
+           "./node_modules/@impact-analytics/impact-ui-mcp-server/src/index.js"
+         ],
+         "cwd": "${workspaceFolder}"
+       }
+     }
+   }
+   ```
+   **No environment variables needed!** The MCP server will auto-detect `impact-ui` from `node_modules`.
+   
+   **If you're using a cloned repository instead:**
+   ```json
+   {
+     "mcp.servers": {
+       "impact-ui": {
+         "command": "node",
+         "args": [
+           "./node_modules/@impact-analytics/impact-ui-mcp-server/src/index.js"
+         ],
+         "cwd": "${workspaceFolder}",
+         "env": {
+           "IMPACT_UI_PATH": "/absolute/path/to/impact-ui"
+         }
+       }
+     }
+   }
+   ```
+   **Note**: `IMPACT_UI_PATH` is the path to the **cloned git repository** (e.g., `/Users/team/projects/impact-ui`), NOT the npm package path.
+
+3. **Restart Cursor IDE**
+
+### Option 2: Direct Path Configuration
+
+If you don't want to use npm, you can point directly to the MCP server in the Impact UI repository.
+
+1. **In Cursor Settings**, add:
+   ```json
+   {
+     "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",
+         "env": {
+           "IMPACT_UI_PATH": "/absolute/path/to/impact-ui"
+         }
+       }
+     }
+   }
+   ```
+
+2. **Restart Cursor IDE**
+
+### Option 3: Environment Variable Configuration
+
+You can also set the path via environment variables:
+
+1. **Set environment variable** (in your shell profile or system settings):
+   ```bash
+   export IMPACT_UI_PATH=/absolute/path/to/impact-ui
+   # or
+   export IMPACT_UI_FRONTEND_PATH=/absolute/path/to/impact-ui/frontend
+   ```
+
+2. **Configure Cursor** (same as Option 1 or 2, but without the `env` section)
+
+## Configuration Options
+
+The MCP server supports the following environment variables:
+
+- **`IMPACT_UI_PATH`**: Path to the Impact UI repository root (e.g., `/path/to/impact-ui`)
+  - The server will automatically look for `frontend` directory inside this path
+  
+- **`IMPACT_UI_FRONTEND_PATH`**: Direct path to the frontend directory (e.g., `/path/to/impact-ui/frontend`)
+  - Use this if you want to point directly to the frontend folder
+
+## Verification
+
+After configuration, verify it's working:
+
+1. Open Cursor chat (Cmd+L or Ctrl+L)
+2. Look for the **Impact UI MCP server dropdown** - you should see all components listed
+3. Ask: "What components are available in Impact UI?"
+4. The MCP server should respond with component information
+
+## Troubleshooting
+
+### Server not starting
+
+- **Check Node.js version**: Requires Node.js 18+
+  ```bash
+  node --version
+  ```
+
+- **Verify the path**: Make sure `IMPACT_UI_PATH` points to the correct location
+  ```bash
+  ls $IMPACT_UI_PATH/frontend/src/stories
+  ```
+
+- **Check dependencies**: If using npm package, ensure it's installed
+  ```bash
+  npm list @impact-analytics/impact-ui-mcp-server
+  ```
+
+### Components not found
+
+- **Verify Storybook files exist**: The server looks for `*.stories.js` files in `frontend/src/stories`
+  ```bash
+  ls /path/to/impact-ui/frontend/src/stories/*.stories.js
+  ```
+
+- **Check file permissions**: Ensure the MCP server can read the files
+
+### Path issues
+
+- **Use absolute paths**: Always use absolute paths in configuration, not relative paths
+- **Check workspace folder**: In Cursor, `${workspaceFolder}` resolves to your current workspace
+
+## Multi-Project Setup
+
+If you work on multiple projects that use Impact UI:
+
+1. **Set a global environment variable** pointing to Impact UI:
+   ```bash
+   # In ~/.zshrc or ~/.bashrc
+   export IMPACT_UI_PATH=/path/to/impact-ui
+   ```
+
+2. **Use the same configuration** in all projects:
+   ```json
+   {
+     "mcp.servers": {
+       "impact-ui": {
+         "command": "node",
+         "args": [
+           "./node_modules/@impact-analytics/impact-ui-mcp-server/src/index.js"
+         ],
+         "cwd": "${workspaceFolder}"
+       }
+     }
+   }
+   ```
+
+   The server will automatically use the `IMPACT_UI_PATH` environment variable.
+
+## CI/CD Integration
+
+For automated testing or CI/CD pipelines, you can set the environment variable:
+
+```yaml
+# Example GitHub Actions
+env:
+  IMPACT_UI_PATH: ${{ secrets.IMPACT_UI_PATH }}
+```
+
+## Security Considerations
+
+- **Private npm registry**: If Impact UI is private, publish to a private npm registry
+- **Path access**: Ensure the MCP server only has read access to the Impact UI repository
+- **Network isolation**: The MCP server runs locally and doesn't require network access
+
+## Updating the MCP Server
+
+When the Impact UI library is updated:
+
+1. **Update the npm package** (if using Option 1):
+   ```bash
+   npm update @impact-analytics/impact-ui-mcp-server
+   ```
+
+2. **Restart Cursor IDE** to load the updated server
+
+## Support
+
+For issues or questions:
+- Check the main [README.md](./README.md) for usage examples
+- Review [QUICKSTART.md](./QUICKSTART.md) for setup instructions
+- Contact the Impact UI team

package/QUICKSTART.md

@@ -0,0 +1,119 @@
+# Quick Start Guide
+
+## Installation
+
+1. **Install dependencies:**
+   ```bash
+   cd mcp-server
+   npm install
+   ```
+   
+   Or use the setup script:
+   ```bash
+   ./setup.sh
+   ```
+
+## Configuration for Cursor IDE
+
+### Quick Setup (Recommended)
+
+1. **Generate the configuration automatically:**
+   ```bash
+   cd mcp-server
+   npm run generate-config
+   ```
+   
+   This will output the exact JSON you need to add to Cursor!
+
+2. **Open Cursor Settings:**
+   - Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux)
+   - Type "Preferences: Open User Settings (JSON)" and select it
+
+3. **Add the generated configuration** to your `settings.json` file
+   - Make sure to merge it with existing settings (add a comma if needed)
+
+4. **Restart Cursor IDE**
+
+5. **Verify it's working:**
+   - Open Cursor chat (Cmd+L or Ctrl+L)
+   - **Look for the Impact UI MCP server dropdown** - you should see a list of all components!
+   - Select any component from the dropdown to view its details
+   - Or ask: "What components are available in Impact UI?"
+   - The MCP server should automatically respond with component information
+
+### Manual Setup
+
+If you prefer to configure manually:
+
+1. **Get the absolute path to your project:**
+   ```bash
+   cd mcp-server
+   pwd
+   ```
+
+2. **Open Cursor Settings** (Cmd+Shift+P → "Preferences: Open User Settings (JSON)")
+
+3. **Add this configuration:**
+   ```json
+   {
+     "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!
+
+4. **Restart Cursor IDE**
+
+## Testing
+
+Test the server manually:
+```bash
+npm start
+```
+
+The server should output: "Building component registry..." and then "Impact UI MCP Server running on stdio"
+
+## Usage Examples
+
+### Using Component Resources (Dropdown)
+
+1. **Select a Component**: When you open Cursor chat, you'll see a dropdown with all Impact UI components
+2. **Browse Components**: Select any component (e.g., "Button", "Modal", "Table")
+3. **Ask Questions**: After selecting a component, you can ask:
+   - "What props does this component accept?"
+   - "Show me a code example for this component"
+   - "What are the best practices for using this component?"
+
+### Using Tools Directly
+
+Once configured, you can ask questions like:
+
+- "What components are available in the Impact UI library?"
+- "Show me how to use the Button component"
+- "What props does the Modal component accept?"
+- "Generate a code example for Table with sorting"
+- "Find components related to forms"
+
+## Troubleshooting
+
+**Server won't start:**
+- Make sure you've run `npm install`
+- Check that the path to `frontend/src/stories` is correct
+- Verify Node.js version is 18+ (check with `node --version`)
+
+**Components not found:**
+- Ensure Storybook story files exist in `frontend/src/stories`
+- Check that story files follow naming: `ComponentName.stories.js`
+
+**Configuration issues:**
+- Use absolute paths (not relative) in the config file
+- Make sure the `cwd` points to the mcp-server directory
+- Restart Claude Desktop after changing config

package/QUICK_SETUP.md

@@ -0,0 +1,95 @@
+# Quick Setup Guide for Teams
+
+This is a quick reference for teams who want to use the Impact UI MCP Server in their projects.
+
+## Option 1: Automated Setup (Easiest)
+
+1. **In your project directory**, run:
+   ```bash
+   npm install @impact-analytics/impact-ui-mcp-server
+   ```
+
+2. **Run the setup script**:
+   ```bash
+   npx @impact-analytics/impact-ui-mcp-server/setup-for-teams.sh
+   ```
+   
+   Or download and run:
+   ```bash
+   curl -o setup-for-teams.sh https://raw.githubusercontent.com/your-repo/impact-ui/main/mcp-server/setup-for-teams.sh
+   chmod +x setup-for-teams.sh
+   ./setup-for-teams.sh
+   ```
+
+3. **Copy the generated configuration** to Cursor settings
+4. **Restart Cursor IDE**
+
+## Option 2: Manual Setup
+
+### Step 1: Install the Package
+
+```bash
+npm install @impact-analytics/impact-ui-mcp-server
+```
+
+### Step 2: Configure Cursor
+
+1. Open Cursor Settings: `Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"
+2. Add this configuration:
+
+**If source files are included in the npm package (Option 1 - Recommended):**
+```json
+{
+  "mcp.servers": {
+    "impact-ui": {
+      "command": "node",
+      "args": [
+        "./node_modules/@impact-analytics/impact-ui-mcp-server/src/index.js"
+      ],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+**That's it!** No environment variables needed. The MCP server auto-detects from `node_modules`.
+
+**If using a cloned repository instead:**
+```json
+{
+  "mcp.servers": {
+    "impact-ui": {
+      "command": "node",
+      "args": [
+        "./node_modules/@impact-analytics/impact-ui-mcp-server/src/index.js"
+      ],
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "IMPACT_UI_PATH": "/path/to/impact-ui"
+      }
+    }
+  }
+}
+```
+**Note**: `IMPACT_UI_PATH` is the path to the **cloned git repository**, not the npm package.
+
+3. **Restart Cursor IDE**
+
+### Step 4: Verify
+
+1. Open Cursor chat (`Cmd+L`)
+2. Look for the **Impact UI** dropdown in the MCP server selector
+3. Ask: "What components are available in Impact UI?"
+
+## Troubleshooting
+
+**Server not starting?**
+- Check Node.js version: `node --version` (needs 18+)
+- Verify Impact UI path exists: `ls /path/to/impact-ui/frontend`
+
+**Components not found?**
+- Make sure the Impact UI repository has Storybook files
+- Check that `IMPACT_UI_PATH` points to the correct location
+
+**Need help?**
+- See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed instructions
+- Check [README.md](./README.md) for usage examples

package/README.md

@@ -0,0 +1,259 @@
+# 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](./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:
+```bash
+cd mcp-server
+```
+
+2. Install dependencies:
+```bash
+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:
+   ```json
+   {
+     "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:
+   ```bash
+   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`
+
+```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:
+```bash
+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
+
+```bash
+npm run dev
+```
+
+This will watch for file changes and restart the server.
+
+### Testing
+
+You can test the server manually by running:
+
+```bash
+npm start
+```
+
+Then send JSON-RPC requests via stdin. For example:
+```json
+{"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