@tpitre/story-ui 4.2.0 → 4.4.0

package/README.md

@@ -10,7 +10,7 @@ Story UI revolutionizes component documentation by automatically generating Stor
 ## Why Story UI?
 
 - **Framework Agnostic**: Works with React, Vue, Angular, Svelte, and Web Components
-- **Multi-Provider AI**: Choose between Claude (Anthropic), GPT-5 (OpenAI), or Gemini (Google)
+- **Multi-Provider AI**: Choose between Claude, OpenAI, or Google Gemini - always using the latest models
 - **Design System Aware**: Learns your component library and generates appropriate code
 - **Production Ready**: Deploy as a standalone web app with full MCP integration
 - **Zero Lock-in**: Use any component library - Mantine, Vuetify, Angular Material, Shoelace, or your own
@@ -47,6 +47,12 @@ Story UI will guide you through:
 - **TypeScript Support**: Full type-aware story generation
 - **Vision Support**: Attach screenshots for visual component requests
 
+### Story Management
+- **Edit Existing Stories**: Modify any generated story through conversation
+- **Delete Stories**: Remove stories directly from the Story UI panel
+- **Orphan Detection**: Find and clean up stories without associated chat history
+- **Full MCP Integration**: Manage stories via Claude Desktop or any MCP-compatible client
+
 ### Multi-Framework Support
 
 | Framework | Design Systems | Status |
@@ -54,16 +60,16 @@ Story UI will guide you through:
 | React | Mantine, Chakra UI, Material UI, Custom | Fully Supported |
 | Vue | Vuetify, Custom | Fully Supported |
 | Angular | Angular Material, Custom | Fully Supported |
-| Svelte | Skeleton UI, Custom | Fully Supported |
+| Svelte | Flowbite-Svelte, Custom | Fully Supported |
 | Web Components | Shoelace, Custom | Fully Supported |
 
 ### Multi-Provider LLM Support
 
 | Provider | Models | Best For |
 |----------|--------|----------|
-| **Claude** (Anthropic) | Opus 4.5, Sonnet 4.5, Haiku 4.5 | Complex reasoning, code quality |
-| **GPT** (OpenAI) | GPT-5.1, GPT-5.1 Thinking, GPT-4o, GPT-4o Mini | Versatility, speed |
-| **Gemini** (Google) | Gemini 3 Pro, Gemini 2.0 Flash, Gemini 1.5 Pro | Fast generation, cost efficiency |
+| **Claude** (Anthropic) | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 | Complex reasoning, code quality |
+| **GPT** (OpenAI) | gpt-5.2, gpt-5.1, gpt-4o, gpt-4o-mini | Versatility, latest capabilities |
+| **Gemini** (Google) | gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash | Fast generation, cost efficiency |
 
 ### Production Deployment
 - **Railway**: Node.js backend with file-based story persistence
@@ -115,7 +121,7 @@ The interactive installer will ask:
    ```
    ? Which AI provider do you prefer?
      > Claude (Anthropic) - Recommended
-       OpenAI (GPT-5)
+       OpenAI
        Google Gemini
 
    ? Enter your API key:
@@ -256,11 +262,18 @@ The easiest way to connect is via Claude Desktop's built-in connector UI:
 2. Go to **Settings** → **Connectors**
 3. Click **"Add custom connector"**
 4. Enter:
-   - **Name**: `Story UI` (or any name you prefer)
-   - **URL**: `https://story-ui-demo.up.railway.app/mcp-remote/mcp` (production)
+   - **Name**: `Story UI React` (or any descriptive name)
+   - **URL**: Your deployed Railway URL + `/mcp-remote/mcp`
+     - Example: `https://your-app-name.up.railway.app/mcp-remote/mcp`
 5. Click **Add**
 6. **Restart Claude Desktop**
 
+> **Note**: The URL will be your own Railway deployment URL. See [Production Deployment](#production-deployment) to set up your instance.
+
+**Multiple Projects**: If you have multiple Storybook projects, add a separate connector for each:
+- `Story UI React` → `https://my-react-app.up.railway.app/mcp-remote/mcp`
+- `Story UI Vue` → `https://my-vue-app.up.railway.app/mcp-remote/mcp`
+
 Once connected, you'll have access to all Story UI tools directly in your Claude conversations:
 - `generate-story` - Generate Storybook stories from natural language
 - `list-components` - Discover available components
@@ -274,38 +287,52 @@ Once connected, you'll have access to all Story UI tools directly in your Claude
 Connect via Claude Code's built-in MCP support:
 
 ```bash
-# Add remote HTTP MCP server (production)
-claude mcp add --transport http story-ui https://story-ui-demo.up.railway.app/mcp-remote/mcp
+# Add your production Railway deployment
+claude mcp add --transport http story-ui-react https://your-react-app.up.railway.app/mcp-remote/mcp
 
-# Or for local development
-claude mcp add --transport http story-ui-local http://localhost:4005/mcp-remote/mcp
+# Add another project (if needed)
+claude mcp add --transport http story-ui-vue https://your-vue-app.up.railway.app/mcp-remote/mcp
+
+# For local development (default port is 4001)
+claude mcp add --transport http story-ui-local http://localhost:4001/mcp-remote/mcp
 ```
 
 ### Manual Configuration (Advanced)
 
-For advanced users who prefer manual configuration, add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+For running multiple local Story UI instances with different ports, configure your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
-    "story-ui": {
+    "story-ui-react": {
+      "command": "npx",
+      "args": ["@tpitre/story-ui", "start", "--port", "4001"]
+    },
+    "story-ui-vue": {
+      "command": "npx",
+      "args": ["@tpitre/story-ui", "start", "--port", "4002"]
+    },
+    "story-ui-angular": {
       "command": "npx",
-      "args": ["@tpitre/story-ui", "mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "your-api-key"
-      }
+      "args": ["@tpitre/story-ui", "start", "--port", "4003"]
     }
   }
 }
 ```
 
+> **Note**: When using Claude Desktop, API keys are managed through your Anthropic account - no need to configure them in the MCP server.
+
 ### Starting the Local MCP Server
 
 ```bash
+# Start with default port (4001)
 npx story-ui start
+
+# Or specify a custom port
+npx story-ui start --port 4002
 ```
 
-This starts the Story UI HTTP server with MCP endpoint at `http://localhost:4005/mcp-remote/mcp`.
+This starts the Story UI HTTP server with MCP endpoint at `http://localhost:<port>/mcp-remote/mcp`.
 
 ### Available MCP Commands
 
@@ -319,13 +346,13 @@ Once connected, you can use these commands in Claude Desktop:
 
 ## Production Deployment
 
-Story UI v3 can be deployed as a standalone web application accessible from anywhere.
+Story UI can be deployed as a standalone web application accessible from anywhere. We recommend Railway for its ease of use, but any Node.js hosting platform will work.
 
 ### Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                    Railway Deployment                        │
+│                    Your Deployment (e.g., Railway)           │
 │  ┌─────────────────────────────────────────────────────────┐│
 │  │              Express MCP Server (Node.js)                ││
 │  │  - Serves Storybook with Story UI addon                  ││
@@ -336,9 +363,9 @@ Story UI v3 can be deployed as a standalone web application accessible from anyw
 └──────────────────────────────────────────────────────────────┘
 ```
 
-### Deploy to Railway
+### Deploy to Railway (Recommended)
 
-Railway provides a straightforward deployment experience with file-based story persistence.
+Railway provides a straightforward deployment experience with automatic HTTPS and file-based story persistence.
 
 **Quick Start:**
 
@@ -347,23 +374,27 @@ Railway provides a straightforward deployment experience with file-based story p
 npm install -g @railway/cli
 railway login
 
-# Initialize and deploy
+# Initialize and deploy from your Storybook project
 railway init
 railway up
 ```
 
 **Environment Variables (set in Railway Dashboard):**
 - `ANTHROPIC_API_KEY` - Required for Claude models
-- `OPENAI_API_KEY` - Optional for OpenAI models
-- `GEMINI_API_KEY` - Optional for Gemini models
+- `OPENAI_API_KEY` - Optional, for OpenAI models
+- `GEMINI_API_KEY` - Optional, for Gemini models
+
+**After Deployment:**
 
-**Connect MCP Clients:**
+Your Railway app will have a URL like `https://your-app-name.up.railway.app`. Use this URL to connect MCP clients:
 
 ```bash
-# Add your Railway deployment as an MCP server
-claude mcp add --transport http story-ui https://your-app.up.railway.app/mcp-remote/mcp
+# In Claude Code
+claude mcp add --transport http story-ui https://your-app-name.up.railway.app/mcp-remote/mcp
 ```
 
+Or add it to Claude Desktop via **Settings** → **Connectors** → **Add custom connector**.
+
 See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions and troubleshooting.
 
 ---
@@ -417,17 +448,14 @@ For simpler setups, use `story-ui-considerations.md`:
 ## CLI Reference
 
 ```bash
-# Initialize Story UI
+# Initialize Story UI in your project
 npx story-ui init
 
-# Start the development server
+# Start the MCP server (default port: 4001)
 npx story-ui start
-npx story-ui start --port 4005
-
-# Deploy to production
-npx story-ui deploy
+npx story-ui start --port 4002  # Custom port
 
-# Run MCP server
+# Run MCP STDIO server (for Claude Desktop local integration)
 npx story-ui mcp
 ```
 
@@ -461,7 +489,7 @@ npx story-ui mcp
 
 ## Upgrading from v2
 
-Story UI v3 is backwards compatible with v2 configurations. However, to take advantage of new features:
+Story UI v4 is backwards compatible with previous configurations. However, to take advantage of new features:
 
 1. **Multi-Provider Support**: Add `llmProvider` to your config
 2. **Framework Detection**: Add `framework` to your config for non-React projects

package/dist/mcp-server/index.js

@@ -78,6 +78,176 @@ app.get('/mcp/frameworks/detect', detectCurrentFramework);
 app.get('/mcp/frameworks/:type', getFrameworkDetails);
 app.post('/mcp/frameworks/validate', validateStoryForFramework);
 app.post('/mcp/frameworks/post-process', postProcessStoryForFramework);
+// MCP story management routes - for Claude Desktop and other MCP clients
+// List all stories
+app.get('/mcp/stories', async (req, res) => {
+    try {
+        const storiesPath = config.generatedStoriesPath;
+        if (!fs.existsSync(storiesPath)) {
+            return res.json({ stories: [] });
+        }
+        const files = fs.readdirSync(storiesPath);
+        const stories = files
+            .filter(file => file.endsWith('.stories.tsx') || file.endsWith('.stories.ts') || file.endsWith('.stories.svelte'))
+            .map(file => {
+            const filePath = path.join(storiesPath, file);
+            const stats = fs.statSync(filePath);
+            const content = fs.readFileSync(filePath, 'utf-8');
+            // Extract title from story file
+            const titleMatch = content.match(/title:\s*['"]([^'"]+)['"]/);
+            let title = titleMatch ? titleMatch[1].replace('Generated/', '') : file.replace(/\.stories\.(tsx|ts|svelte)$/, '');
+            // Remove hash suffix from display title
+            title = title.replace(/\s*\([a-f0-9]{8}\)$/i, '');
+            return {
+                id: file.replace(/\.stories\.(tsx|ts|svelte)$/, ''),
+                storyId: file.replace(/\.stories\.(tsx|ts|svelte)$/, ''),
+                fileName: file,
+                title,
+                lastUpdated: stats.mtime.getTime(),
+                createdAt: stats.birthtime.getTime(),
+                content
+            };
+        })
+            .sort((a, b) => b.lastUpdated - a.lastUpdated);
+        return res.json({ stories });
+    }
+    catch (error) {
+        console.error('Error listing stories:', error);
+        return res.status(500).json({ error: 'Failed to list stories' });
+    }
+});
+// Get a specific story by ID
+app.get('/mcp/stories/:storyId', async (req, res) => {
+    try {
+        const { storyId } = req.params;
+        const storiesPath = config.generatedStoriesPath;
+        if (!fs.existsSync(storiesPath)) {
+            return res.status(404).json({ error: 'Stories directory not found' });
+        }
+        const files = fs.readdirSync(storiesPath);
+        // Extract hash from story ID if in legacy format (story-a1b2c3d4)
+        const hashMatch = storyId.match(/^story-([a-f0-9]{8})$/);
+        const hash = hashMatch ? hashMatch[1] : null;
+        // Find matching file
+        const matchingFile = files.find(file => {
+            // Match by hash suffix
+            if (hash && file.includes(`-${hash}.stories.`))
+                return true;
+            // Match by exact ID
+            if (file.startsWith(`${storyId}.stories.`))
+                return true;
+            // Match by fileName
+            if (file === storyId)
+                return true;
+            // Match by ID without extension
+            if (file.replace(/\.stories\.(tsx|ts|svelte)$/, '') === storyId)
+                return true;
+            return false;
+        });
+        if (!matchingFile) {
+            return res.status(404).json({ error: `Story with ID ${storyId} not found` });
+        }
+        const filePath = path.join(storiesPath, matchingFile);
+        const stats = fs.statSync(filePath);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Extract title from story file
+        const titleMatch = content.match(/title:\s*['"]([^'"]+)['"]/);
+        let title = titleMatch ? titleMatch[1].replace('Generated/', '') : matchingFile.replace(/\.stories\.(tsx|ts|svelte)$/, '');
+        title = title.replace(/\s*\([a-f0-9]{8}\)$/i, '');
+        return res.json({
+            id: matchingFile.replace(/\.stories\.(tsx|ts|svelte)$/, ''),
+            storyId: matchingFile.replace(/\.stories\.(tsx|ts|svelte)$/, ''),
+            fileName: matchingFile,
+            title,
+            lastUpdated: stats.mtime.getTime(),
+            createdAt: stats.birthtime.getTime(),
+            timestamp: stats.mtime.getTime(),
+            content,
+            story: content
+        });
+    }
+    catch (error) {
+        console.error('Error getting story:', error);
+        return res.status(500).json({ error: 'Failed to get story' });
+    }
+});
+// Get story content (raw code)
+app.get('/mcp/stories/:storyId/content', async (req, res) => {
+    try {
+        const { storyId } = req.params;
+        const storiesPath = config.generatedStoriesPath;
+        if (!fs.existsSync(storiesPath)) {
+            return res.status(404).send('Stories directory not found');
+        }
+        const files = fs.readdirSync(storiesPath);
+        // Extract hash from story ID if in legacy format
+        const hashMatch = storyId.match(/^story-([a-f0-9]{8})$/);
+        const hash = hashMatch ? hashMatch[1] : null;
+        // Find matching file
+        const matchingFile = files.find(file => {
+            if (hash && file.includes(`-${hash}.stories.`))
+                return true;
+            if (file.startsWith(`${storyId}.stories.`))
+                return true;
+            if (file === storyId)
+                return true;
+            if (file.replace(/\.stories\.(tsx|ts|svelte)$/, '') === storyId)
+                return true;
+            return false;
+        });
+        if (!matchingFile) {
+            return res.status(404).send(`Story with ID ${storyId} not found`);
+        }
+        const filePath = path.join(storiesPath, matchingFile);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        res.type('text/plain').send(content);
+    }
+    catch (error) {
+        console.error('Error getting story content:', error);
+        return res.status(500).send('Failed to get story content');
+    }
+});
+// Delete a story by ID
+app.delete('/mcp/stories/:storyId', async (req, res) => {
+    try {
+        const { storyId } = req.params;
+        const storiesPath = config.generatedStoriesPath;
+        if (!fs.existsSync(storiesPath)) {
+            return res.status(404).json({ error: 'Stories directory not found' });
+        }
+        const files = fs.readdirSync(storiesPath);
+        // Extract hash from story ID if in legacy format
+        const hashMatch = storyId.match(/^story-([a-f0-9]{8})$/);
+        const hash = hashMatch ? hashMatch[1] : null;
+        // Find matching file
+        const matchingFile = files.find(file => {
+            if (hash && file.includes(`-${hash}.stories.`))
+                return true;
+            if (file.startsWith(`${storyId}.stories.`))
+                return true;
+            if (file === storyId)
+                return true;
+            if (file.replace(/\.stories\.(tsx|ts|svelte)$/, '') === storyId)
+                return true;
+            return false;
+        });
+        if (!matchingFile) {
+            return res.status(404).json({ error: `Story with ID ${storyId} not found` });
+        }
+        const filePath = path.join(storiesPath, matchingFile);
+        fs.unlinkSync(filePath);
+        console.log(`🗑️ Deleted story via MCP endpoint: ${matchingFile}`);
+        return res.json({
+            success: true,
+            deleted: matchingFile,
+            message: `Story "${matchingFile}" has been deleted successfully.`
+        });
+    }
+    catch (error) {
+        console.error('Error deleting story:', error);
+        return res.status(500).json({ error: 'Failed to delete story' });
+    }
+});
 // File-based story routes - stories are generated as .stories.tsx files
 // Storybook discovers these automatically via its native file system watching
 // Proxy routes for frontend compatibility (maps /story-ui/ to /mcp/)

package/dist/mcp-server/mcp-stdio-server.js

@@ -27,7 +27,8 @@ dotenv.config({ path: path.resolve(process.cwd(), '.env') });
 process.env.STORY_UI_MCP_MODE = 'true';
 // Get HTTP server port from environment variables (check multiple possible names)
 const HTTP_PORT = process.env.VITE_STORY_UI_PORT || process.env.STORY_UI_HTTP_PORT || process.env.PORT || '4001';
-const HTTP_BASE_URL = `http://localhost:${HTTP_PORT}`;
+// Allow configurable base URL for Railway/cloud deployments, fallback to localhost for local dev
+const HTTP_BASE_URL = process.env.STORY_UI_HTTP_BASE_URL || `http://localhost:${HTTP_PORT}`;
 // Initialize configuration
 const config = loadUserConfig();
 // Create MCP server instance
@@ -181,8 +182,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     throw new Error(`Failed to generate story: ${error}`);
                 }
                 const result = await response.json();
-                // Debug log to see what we're getting
-                console.error('Story generation result:', JSON.stringify(result, null, 2));
                 return {
                     content: [{
                             type: "text",
@@ -509,8 +508,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         throw new Error(`Failed to update story: ${error}`);
                     }
                     const result = await response.json();
-                    // Debug log to see what we're getting
-                    console.error('Story update result:', JSON.stringify(result, null, 2));
                     return {
                         content: [{
                                 type: "text",

package/dist/story-generator/framework-adapters/index.js

@@ -150,7 +150,7 @@ class AdapterRegistry {
         return {
             systemPrompt: adapter.generateSystemPrompt(config, options),
             componentReference: adapter.generateComponentReference(components, config),
-            layoutInstructions: '', // TODO: Implement layout instructions
+            layoutInstructions: '',
             examples: adapter.generateExamples(config),
             sampleStory: adapter.generateSampleStory(config, components),
             framework: this.detectedFramework || {

package/dist/templates/StoryUI/StoryUIPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StoryUIPanel.d.ts","sourceRoot":"","sources":["../../../templates/StoryUI/StoryUIPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,oBAAoB,CAAC;AAwwB5B,UAAU,iBAAiB;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,iBAAS,YAAY,CAAC,EAAE,OAAO,EAAE,EAAE,iBAAiB,2CAwnCnD;AAED,eAAe,YAAY,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"StoryUIPanel.d.ts","sourceRoot":"","sources":["../../../templates/StoryUI/StoryUIPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,oBAAoB,CAAC;AAwwB5B,UAAU,iBAAiB;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,iBAAS,YAAY,CAAC,EAAE,OAAO,EAAE,EAAE,iBAAiB,2CA0sCnD;AAED,eAAe,YAAY,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/templates/StoryUI/StoryUIPanel.js

@@ -452,12 +452,79 @@ function StoryUIPanel({ mcpPort }) {
     const fileInputRef = useRef(null);
     const abortControllerRef = useRef(null);
     const hasShownRefreshHint = useRef(false);
+    // Track stories for MCP external generation detection
+    // Used to detect when stories are created via MCP remote (Claude Desktop)
+    // and trigger automatic refresh since MCP has no browser context
+    const panelGeneratedStoryIds = useRef(new Set());
+    const knownStoryIds = useRef(new Set());
+    const isPollingInitialized = useRef(false);
     // Set port override if provided
     useEffect(() => {
         if (mcpPort && typeof window !== 'undefined') {
             window.STORY_UI_MCP_PORT = String(mcpPort);
         }
     }, [mcpPort]);
+    // Poll for MCP-generated stories (stories created externally via Claude Desktop/Code)
+    // This solves the Vite HMR issue where stories generated via MCP remote don't trigger
+    // a browser refresh because MCP has no browser context to call window.location.reload()
+    useEffect(() => {
+        const POLL_INTERVAL_MS = 5000; // Check every 5 seconds
+        const pollForExternalStories = async () => {
+            try {
+                const baseUrl = getApiBaseUrl();
+                const response = await fetch(`${baseUrl}/story-ui/stories`);
+                if (!response.ok)
+                    return;
+                const data = await response.json();
+                const currentStoryIds = new Set(data.stories?.map((s) => s.id) || []);
+                // On first poll, just record what's already there
+                if (!isPollingInitialized.current) {
+                    knownStoryIds.current = currentStoryIds;
+                    isPollingInitialized.current = true;
+                    console.log('[Story UI] MCP story polling initialized with', currentStoryIds.size, 'stories');
+                    return;
+                }
+                // Check for new stories not created by this panel session
+                for (const storyId of currentStoryIds) {
+                    if (!knownStoryIds.current.has(storyId) && !panelGeneratedStoryIds.current.has(storyId)) {
+                        // New story detected that wasn't created by this panel - must be from MCP remote
+                        console.log('[Story UI] Detected externally generated story:', storyId);
+                        console.log('[Story UI] Triggering refresh to register new story in Vite import map...');
+                        // Update known stories before refresh
+                        knownStoryIds.current = currentStoryIds;
+                        // Trigger refresh with a short delay
+                        setTimeout(() => {
+                            try {
+                                if (window.top && window.top !== window) {
+                                    window.top.location.reload();
+                                }
+                                else if (window.parent && window.parent !== window) {
+                                    window.parent.location.reload();
+                                }
+                                else {
+                                    window.location.reload();
+                                }
+                            }
+                            catch (error) {
+                                console.warn('[Story UI] Could not auto-refresh for MCP-generated story');
+                            }
+                        }, 1000);
+                        return; // Only trigger one refresh
+                    }
+                }
+                // Update known stories
+                knownStoryIds.current = currentStoryIds;
+            }
+            catch (error) {
+                // Silently ignore polling errors - server may be unavailable temporarily
+            }
+        };
+        // Start polling
+        const intervalId = setInterval(pollForExternalStories, POLL_INTERVAL_MS);
+        // Initial poll
+        pollForExternalStories();
+        return () => clearInterval(intervalId);
+    }, []);
     // Detect Storybook theme
     useEffect(() => {
         const detectTheme = () => {
@@ -863,6 +930,13 @@ function StoryUIPanel({ mcpPort }) {
             title: completion.title,
             action: completion.summary?.action,
         });
+        // Track this story as panel-generated to prevent false MCP detection
+        // The story ID is the fileName without .stories.tsx extension
+        if (completion.success && completion.fileName) {
+            const storyId = completion.fileName.replace('.stories.tsx', '');
+            panelGeneratedStoryIds.current.add(storyId);
+            console.log('[Story UI] Tracking panel-generated story:', storyId);
+        }
         const isUpdate = completion.summary.action === 'updated';
         const responseMessage = buildConversationalResponse(completion, isUpdate);
         const aiMsg = { role: 'ai', content: responseMessage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpitre/story-ui",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "AI-powered Storybook story generator with dynamic component discovery",
   "type": "module",
   "main": "dist/index.js",

package/templates/StoryUI/StoryUIPanel.tsx

@@ -800,6 +800,13 @@ function StoryUIPanel({ mcpPort }: StoryUIPanelProps) {
   const abortControllerRef = useRef<AbortController | null>(null);
   const hasShownRefreshHint = useRef(false);
 
+  // Track stories for MCP external generation detection
+  // Used to detect when stories are created via MCP remote (Claude Desktop)
+  // and trigger automatic refresh since MCP has no browser context
+  const panelGeneratedStoryIds = useRef<Set<string>>(new Set());
+  const knownStoryIds = useRef<Set<string>>(new Set());
+  const isPollingInitialized = useRef(false);
+
   // Set port override if provided
   useEffect(() => {
     if (mcpPort && typeof window !== 'undefined') {
@@ -807,6 +814,73 @@ function StoryUIPanel({ mcpPort }: StoryUIPanelProps) {
     }
   }, [mcpPort]);
 
+  // Poll for MCP-generated stories (stories created externally via Claude Desktop/Code)
+  // This solves the Vite HMR issue where stories generated via MCP remote don't trigger
+  // a browser refresh because MCP has no browser context to call window.location.reload()
+  useEffect(() => {
+    const POLL_INTERVAL_MS = 5000; // Check every 5 seconds
+
+    const pollForExternalStories = async () => {
+      try {
+        const baseUrl = getApiBaseUrl();
+        const response = await fetch(`${baseUrl}/story-ui/stories`);
+        if (!response.ok) return;
+
+        const data = await response.json();
+        const currentStoryIds = new Set<string>(data.stories?.map((s: { id: string }) => s.id) || []);
+
+        // On first poll, just record what's already there
+        if (!isPollingInitialized.current) {
+          knownStoryIds.current = currentStoryIds;
+          isPollingInitialized.current = true;
+          console.log('[Story UI] MCP story polling initialized with', currentStoryIds.size, 'stories');
+          return;
+        }
+
+        // Check for new stories not created by this panel session
+        for (const storyId of currentStoryIds) {
+          if (!knownStoryIds.current.has(storyId) && !panelGeneratedStoryIds.current.has(storyId)) {
+            // New story detected that wasn't created by this panel - must be from MCP remote
+            console.log('[Story UI] Detected externally generated story:', storyId);
+            console.log('[Story UI] Triggering refresh to register new story in Vite import map...');
+
+            // Update known stories before refresh
+            knownStoryIds.current = currentStoryIds;
+
+            // Trigger refresh with a short delay
+            setTimeout(() => {
+              try {
+                if (window.top && window.top !== window) {
+                  window.top.location.reload();
+                } else if (window.parent && window.parent !== window) {
+                  window.parent.location.reload();
+                } else {
+                  window.location.reload();
+                }
+              } catch (error) {
+                console.warn('[Story UI] Could not auto-refresh for MCP-generated story');
+              }
+            }, 1000);
+            return; // Only trigger one refresh
+          }
+        }
+
+        // Update known stories
+        knownStoryIds.current = currentStoryIds;
+      } catch (error) {
+        // Silently ignore polling errors - server may be unavailable temporarily
+      }
+    };
+
+    // Start polling
+    const intervalId = setInterval(pollForExternalStories, POLL_INTERVAL_MS);
+
+    // Initial poll
+    pollForExternalStories();
+
+    return () => clearInterval(intervalId);
+  }, []);
+
   // Detect Storybook theme
   useEffect(() => {
     const detectTheme = () => {
@@ -1219,6 +1293,14 @@ function StoryUIPanel({ mcpPort }: StoryUIPanelProps) {
       action: completion.summary?.action,
     });
 
+    // Track this story as panel-generated to prevent false MCP detection
+    // The story ID is the fileName without .stories.tsx extension
+    if (completion.success && completion.fileName) {
+      const storyId = completion.fileName.replace('.stories.tsx', '');
+      panelGeneratedStoryIds.current.add(storyId);
+      console.log('[Story UI] Tracking panel-generated story:', storyId);
+    }
+
     const isUpdate = completion.summary.action === 'updated';
     const responseMessage = buildConversationalResponse(completion, isUpdate);
     const aiMsg: Message = { role: 'ai', content: responseMessage };