@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/docs/MCP-SERVER.md

@@ -0,0 +1,307 @@
+The Crownpeak DQM React Component provides an MCP (Model Context Protocol) server for AI-powered documentation search. This enables AI assistants like Claude, GitHub Copilot, and Cline to search and understand the DQM documentation.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Benefits](#benefits)
+- [Installation](#installation)
+  - [Claude Desktop](#claude-desktop)
+  - [VS Code Copilot](#vs-code-copilot)
+  - [Cline](#cline)
+  - [OpenAI Codex CLI](#openai-codex-cli)
+- [Usage](#usage)
+  - [Example Queries](#example-queries)
+- [Dynamic Usage](#dynamic-usage)
+- [Documentation Coverage](#documentation-coverage)
+- [Troubleshooting](#troubleshooting)
+- [Related Links](#related-links)
+
+---
+
+## Overview
+
+| Feature | Description |
+|---------|-------------|
+| **Powered by** | [Probe](https://probeai.dev/) search engine |
+| **Configuration** | Zero setup - just `npx` |
+| **Tool Name** | `search_dqm_docs` |
+| **Package** | `@crownpeak/dqm-react-component-dev-mcp` |
+
+The MCP server indexes all DQM documentation and makes it searchable by AI assistants. When you ask a question about DQM, your AI assistant can automatically search the documentation to provide accurate, up-to-date answers.
+
+---
+
+## Benefits
+
+### For Developers Integrating DQM
+
+The MCP server is especially useful when you're **integrating the DQM component into your application**:
+
+- **Step-by-Step Guidance**: Ask your AI assistant "How do I add DQMSidebar to my React app?" and get accurate, contextual instructions
+- **Configuration Help**: Get instant answers about props, overlay detection, authentication modes
+- **Code Generation**: AI can generate correctly configured DQMSidebar code based on your specific requirements
+- **Troubleshooting**: When something doesn't work, the AI can search the documentation for solutions
+
+**Example workflow:**
+```
+You: "I want to add DQM to my Next.js app with backend authentication"
+AI: [searches docs] Here's how to set it up...
+     1. Install the package
+     2. Configure authBackendUrl
+     3. Set up the backend server
+     [provides code examples from documentation]
+```
+
+### General Benefits
+
+- **Faster Answers**: Get instant, accurate answers about DQMSidebar configuration, props, and usage patterns
+- **Context-Aware Help**: AI understands the full documentation, not just snippets
+- **Always Up-to-Date**: Pre-built documentation bundle ensures you get the latest information
+
+### For AI Assistants
+
+- **Structured Search**: Semantic search across all documentation files
+- **Code Examples**: Access to real code samples from the repository
+- **Type Information**: Full TypeScript type definitions included
+
+---
+
+## Installation
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dqm-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@crownpeak/dqm-react-component-dev-mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the configuration.
+
+---
+
+### VS Code Copilot
+
+Add to your VS Code MCP configuration (`.vscode/mcp.json` in your project or workspace):
+
+```json
+{
+  "servers": {
+    "dqm-docs": {
+      "command": "npx",
+      "args": ["-y", "@crownpeak/dqm-react-component-dev-mcp@latest"]
+    }
+  }
+}
+```
+
+---
+
+### Cline
+
+Add to your project's `.cline/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dqm-docs": {
+      "command": "npx",
+      "args": ["-y", "@crownpeak/dqm-react-component-dev-mcp@latest"]
+    }
+  }
+}
+```
+
+---
+
+### OpenAI Codex CLI
+
+Add to your project's `codex.toml` or global `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.dqm-docs]
+command = "npx"
+args = ["-y", "@crownpeak/dqm-react-component-dev-mcp@latest"]
+```
+
+Or with environment variables:
+
+```toml
+[mcp_servers.dqm-docs]
+command = "npx"
+args = ["-y", "@crownpeak/dqm-react-component-dev-mcp@latest"]
+
+[mcp_servers.dqm-docs.env]
+NODE_ENV = "production"
+```
+
+---
+
+## Usage
+
+Once configured, you can ask your AI assistant questions about DQM. The AI will automatically use the `search_dqm_docs` tool to find relevant documentation.
+
+### Example Queries
+
+**Configuration Questions:**
+- "How do I configure overlay detection in DQMSidebar?"
+- "What props does DQMSidebar accept?"
+- "How do I set up backend authentication?"
+
+**Integration Questions:**
+- "How do I integrate the widget bundle?"
+- "How do I use DQM with Next.js?"
+- "What's the difference between direct and backend authentication?"
+
+**Troubleshooting:**
+- "What is manualOffset and when should I use it?"
+- "How do I fix z-index issues with the sidebar?"
+- "Why isn't my overlay being detected?"
+
+**Code Examples:**
+- "Show me an example of DQMSidebar with AI translation"
+- "How do I change the language programmatically?"
+
+### Search Keywords
+
+For best results, try these search patterns:
+
+```
+"DQMSidebar overlayConfig"
+"backend authentication setup"
+"widget bundle integration"
+"manualOffset configuration"
+"AI translation config"
+"i18n language switch"
+```
+
+---
+
+## Dynamic Usage
+
+Instead of the pre-built package, you can point directly to the GitHub repository for the most recent documentation:
+
+```json
+{
+  "mcpServers": {
+    "dqm-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@probelabs/docs-mcp@latest",
+        "--gitUrl",
+        "https://github.com/Crownpeak/dqm-react-component",
+        "--toolName",
+        "search_dqm_docs",
+        "--toolDescription",
+        "Search Crownpeak DQM React Component documentation"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Dynamic mode fetches from GitHub on each query, which may be slower than the pre-built package.
+
+---
+
+## Documentation Coverage
+
+The MCP server indexes all documentation including:
+
+| Source | Content |
+|--------|---------|
+| `README.md` | Overview and quick start |
+| `docs/` | Full documentation (QUICKSTART, DEVELOPMENT, SERVER, EXAMPLES, AI-FEATURES, etc.) |
+| `src/` | Source code with JSDoc comments |
+| `.github/copilot-instructions.md` | AI agent integration guide |
+
+### Indexed Topics
+
+- DQMSidebar component and props
+- Authentication (direct and backend modes)
+- AI features (translation, summaries)
+- Internationalization (i18n)
+- Overlay detection and positioning
+- Widget bundle integration
+- Backend server setup
+- Redis session storage
+- TypeScript types and interfaces
+
+---
+
+## Troubleshooting
+
+### MCP Server Not Starting
+
+**Symptoms:** AI assistant doesn't recognize DQM-related questions or `search_dqm_docs` tool is not available.
+
+**Solutions:**
+
+1. **Check Node.js**: Ensure Node.js 18+ is installed
+   ```bash
+   node --version  # Should be v18.0.0 or higher
+   ```
+
+2. **Verify Configuration**: Ensure JSON syntax is correct
+   ```bash
+   # Test the command manually
+   npx -y @crownpeak/dqm-react-component-dev-mcp@latest
+   ```
+
+3. **Restart AI Client**: After configuration changes, restart Claude Desktop/VS Code
+
+4. **Check Logs**: 
+   - Claude Desktop: View → Developer → Open Logs
+   - VS Code: Output panel → MCP
+
+### Search Returns No Results
+
+**Solutions:**
+
+1. **Simplify Query**: Use shorter, more specific terms
+   ```
+   ❌ "How do I configure the overlay detection feature to work with my custom toolbar?"
+   ✅ "overlayConfig toolbar"
+   ```
+
+2. **Use Known Terms**: Reference actual API names
+   ```
+   ✅ "DQMSidebar props"
+   ✅ "manualOffset"
+   ✅ "authBackendUrl"
+   ```
+
+### Outdated Information
+
+If documentation seems outdated:
+
+1. **Update Package**: Force latest version
+   ```bash
+   npx -y @crownpeak/dqm-react-component-dev-mcp@latest
+   ```
+
+2. **Use Dynamic Mode**: Point to GitHub repository directly (see [Dynamic Usage](#dynamic-usage))
+
+---
+
+## Related Links
+
+- [DQM React Component on GitHub](https://github.com/Crownpeak/dqm-react-component)
+- [Probe Search Engine](https://probeai.dev/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [@probelabs/docs-mcp](https://github.com/probelabs/docs-mcp)
+- [MCP Server Package on npm](https://www.npmjs.com/package/@crownpeak/dqm-react-component-dev-mcp)

package/data/docs/MIGRATION-GUIDE.md

@@ -0,0 +1,367 @@
+This guide helps you upgrade between versions of `@crownpeak/dqm-react-component`.
+
+## Table of Contents
+
+- [v1.1.0 → v1.2.0](#v110--v120)
+- [v1.0.x → v1.1.0](#v10x--v110)
+
+---
+
+## v1.1.0 → v1.2.0
+
+**Release Date:** January 7, 2026
+
+**Upgrade Time:** ~5 minutes (no breaking changes)
+
+**Breaking Changes:** None ✅
+
+### Overview*
+
+Version 1.2.0 introduces powerful new features while maintaining full backward compatibility:
+
+- ✨ **AI-Powered Translation** - Translate checkpoint descriptions via OpenAI
+- ✨ **AI Summary Generation** - Generate concise bullet-point summaries
+- 🌍 **Internationalization (i18n)** - UI in English, German, Spanish
+- 🔄 **Redux Store** - Centralized state management (internal)
+- 🔧 **Centralized Logging** - Debug mode for troubleshooting
+
+### Step 1: Update Package
+
+```bash
+npm install @crownpeak/dqm-react-component@1.2.0
+```
+
+Or with Yarn:
+
+```bash
+yarn upgrade @crownpeak/dqm-react-component@1.2.0
+```
+
+### Step 2: Verify (No Changes Required)
+
+Your existing code continues to work without modifications:
+
+```typescript
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+
+// This works exactly as before
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+/>
+```
+
+### New Features (Optional)
+
+#### AI-Powered Translation
+
+Translate checkpoint descriptions into any language:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+    config={{
+        websiteId: '...',
+        apiKey: '...',
+        translation: {
+            enabled: true,
+            apiKey: 'sk-...',       // OpenAI API key
+            model: 'gpt-4o-mini',   // or 'gpt-4o', 'gpt-4.1'
+            targetLanguage: 'de',   // Target language (ISO 639-1)
+            mode: 'fast',           // 'fast' (15s) or 'full' (120s)
+        },
+    }}
+/>
+```
+
+**Key Features:**
+- Automatic IndexedDB + In-Memory caching
+- Fast mode (15s timeout, fails gracefully) or Full mode (120s)
+- ~2-5s for 50 checkpoints
+
+See **[AI Features Guide](./AI-FEATURES.md)** for complete documentation.
+
+#### AI Summary Generation
+
+Generate concise summaries of analysis results:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+    config={{
+        websiteId: '...',
+        apiKey: '...',
+        summary: {
+            enabled: true,
+            apiKey: 'sk-...',
+            model: 'gpt-4o-mini',
+        },
+    }}
+/>
+```
+
+**Key Features:**
+- Automatic chunking based on checkpoint count
+- Persistent IndexedDB cache
+- 3-7 bullet points highlighting key issues
+
+#### Internationalization (i18n)
+
+The UI now supports multiple languages:
+
+- `en` - English (default)
+- `de` - German (Deutsch)
+- `es` - Spanish (Español)
+
+Language preference is saved to `localStorage.getItem('dqm_locale')`.
+
+#### Debug Logging
+
+Enable debug logging for troubleshooting:
+
+```typescript
+// Via localStorage
+localStorage.setItem('dqm_debug', 'true');
+
+// Or programmatically
+import { logger } from '@crownpeak/dqm-react-component';
+logger.setDebugMode(true);
+```
+
+### New TypeScript Types
+
+```typescript
+import type {
+    // Existing types (unchanged)
+    DQMSidebarProps,
+    DQMConfig,
+    OverlayConfig,
+    
+    // NEW in v1.2.0
+    TranslationConfig,
+    SummaryConfig,
+    TranslationProgress,
+    SummaryStats,
+} from '@crownpeak/dqm-react-component';
+```
+
+### New localStorage Keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `dqm_translate_results_enabled` | boolean | false | Toggle translation |
+| `dqm_target_language` | string | 'en' | Target language (ISO 639-1) |
+| `dqm_ai_summary_enabled` | boolean | false | Toggle summary |
+| `dqm_translation_mode` | 'fast'\|'full' | 'fast' | Translation mode |
+| `dqm_openai_apiKey` | string | - | OpenAI API key |
+| `dqm_openai_model` | string | 'gpt-4o-mini' | OpenAI model |
+| `dqm_locale` | 'en'\|'de'\|'es' | 'en' | UI language |
+| `dqm_debug` | boolean | false | Debug logging |
+
+---
+
+## v1.0.x → v1.1.0
+
+**Release Date:** December 17, 2025
+
+**Upgrade Time:** ~5 minutes (no breaking changes)
+
+**Breaking Changes:** None ✅
+
+### Overview
+
+Version 1.1.0 adds new features while maintaining full backward compatibility:
+
+- ✨ **Overlay Configuration** - Customize toolbar/overlay detection
+- ✨ **Standalone Widget Bundle** - IIFE + ESM bundles for embedding
+- ✨ **Enhanced `useDomPresence` Hook** - Better element position detection
+- ✨ **`disableLogout` Config Option** - Hide logout when managed externally
+
+### Step 1: Update Package
+
+```bash
+npm install @crownpeak/dqm-react-component@1.1.0
+```
+
+Or with Yarn:
+
+```bash
+yarn upgrade @crownpeak/dqm-react-component@1.1.0
+```
+
+### Step 2: Verify (No Changes Required)
+
+Your existing code continues to work without modifications:
+
+```typescript
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+
+// This works exactly as before
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+/>
+```
+
+### New Features (Optional)
+
+#### Overlay Configuration
+
+If you have toolbars or overlays that interfere with sidebar positioning:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+    config={{
+        websiteId: '...',
+        apiKey: '...',
+        overlayConfig: {
+            selector: '.my-toolbar',        // CSS selector for overlay
+            validateIframe: true,           // Check iFrame contentWindow
+            pollMs: 1000,                   // Polling interval (ms)
+            manualOffset: {                 // Manual offset override
+                position: 'top',
+                pixels: 50,
+            },
+        },
+    }}
+/>
+```
+
+#### Disable Logout Button
+
+If your app manages authentication externally:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+    config={{
+        websiteId: '...',
+        apiKey: '...',
+        disableLogout: true,  // Hides the logout button
+    }}
+/>
+```
+
+#### Standalone Widget Bundle
+
+For embedding on external sites without React:
+
+```html
+<!-- IIFE Bundle -->
+<script src="https://unpkg.com/@crownpeak/dqm-react-component/dist/dqm-widget.iife.js"></script>
+<script>
+    window.initDQMWidget({
+        websiteId: 'your-website-id',
+        apiKey: 'your-api-key',
+    });
+</script>
+```
+
+See **[Widget Bundle Guide](./WIDGET-GUIDE.md)** for complete documentation.
+
+### New TypeScript Types
+
+```typescript
+import type {
+    // Existing types (unchanged)
+    DQMSidebarProps,
+    DQMConfig,
+    
+    // NEW in v1.1.0
+    OverlayConfig,
+    OverlayOffsetPosition,
+    OverlayInfo,
+    OverlayPosition,
+} from '@crownpeak/dqm-react-component';
+```
+
+### New Hooks
+
+```typescript
+import { useOverlayResistant } from '@crownpeak/dqm-react-component';
+
+// Returns overlay information for custom positioning
+const overlayInfo = useOverlayResistant({
+    selector: '.my-toolbar',
+    validateIframe: true,
+});
+// overlayInfo.present: boolean
+// overlayInfo.height: number
+// overlayInfo.position: 'top' | 'bottom' | 'left' | 'right' | 'center'
+// overlayInfo.contentOffset: { top, bottom, left, right }
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Overlay not detected correctly
+
+**Cause:** Cross-origin iFrame or complex DOM structure.
+
+**Solution:** Use `manualOffset` configuration:
+
+```typescript
+overlayConfig: {
+    selector: '.my-overlay',
+    manualOffset: {
+        position: 'top',
+        pixels: 60,
+    },
+}
+```
+
+### Issue: Translation not working
+
+**Cause:** Missing `translation.enabled` or invalid API key.
+
+**Solution:** Verify configuration:
+
+```typescript
+config={{
+    translation: {
+        enabled: true,          // Must be true
+        apiKey: 'sk-...',       // Valid OpenAI API key
+        model: 'gpt-4o-mini',
+        targetLanguage: 'de',
+    },
+}}
+```
+
+### Issue: TypeScript errors after upgrade
+
+**Cause:** Missing type imports.
+
+**Solution:** Update imports:
+
+```typescript
+import type {
+    DQMSidebarProps,
+    DQMConfig,
+    OverlayConfig,       // v1.1.0+
+    TranslationConfig,   // v1.2.0+
+    SummaryConfig,       // v1.2.0+
+} from '@crownpeak/dqm-react-component';
+```
+
+---
+
+## See Also
+
+- **[AI Features Guide](./AI-FEATURES.md)** - Complete AI documentation (v1.2.0+)
+- **[Widget Bundle Guide](./WIDGET-GUIDE.md)** - Standalone widget documentation (v1.1.0+)
+- **[Quick Start Guide](./QUICKSTART.md)** - Getting started
+- **[API Reference](./API-REFERENCE.md)** - Full TypeScript API
+- **[Examples](./EXAMPLES.md)** - Integration examples
+- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions