@vizzly-testing/cli 0.13.1 → 0.13.3

package/claude-plugin/.claude-plugin/README.md

@@ -130,6 +130,10 @@ The plugin provides an MCP server with direct access to Vizzly data:
 ### Local TDD Tools
 - `detect_context` - Detect if using local TDD or cloud mode
 - `get_tdd_status` - Get current TDD comparison results
+  - Parameters:
+    - `statusFilter` (optional): Filter by status - `'failed'`, `'new'`, `'passed'`, `'all'`, or `'summary'` (default)
+    - `limit` (optional): Maximum number of comparisons to return
+  - Default behavior (summary mode): Returns counts only without full comparison details for efficiency
 - `read_comparison_details` - Detailed info for specific screenshot
 - `accept_baseline` - Accept a screenshot as new baseline
 - `reject_baseline` - Reject a baseline with reason

package/claude-plugin/.mcp.json

@@ -3,6 +3,10 @@
     "vizzly": {
       "command": "node",
       "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/vizzly-server/index.js"]
+    },
+    "vizzly-docs": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/vizzly-docs-server/index.js"]
     }
   }
 }

package/claude-plugin/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to the Vizzly Claude Code plugin will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- 📚 **New MCP Server:** `vizzly-docs` - Easy access to Vizzly documentation
+  - `list_docs` - Browse all docs with optional category filtering
+  - `get_doc` - Retrieve full markdown content for any doc page
+  - `search_docs` - Keyword search across titles, descriptions, and categories
+  - `get_sidebar` - View complete documentation navigation structure
+  - Fetches from live docs.vizzly.dev site with intelligent caching
+- ⚡️ **Performance:** `get_tdd_status` now supports filtering and pagination
+  - New `statusFilter` parameter: `'failed'`, `'new'`, `'passed'`, `'all'`, or `'summary'` (default)
+  - New `limit` parameter for capping number of comparisons returned
+  - Default behavior (summary mode) returns only counts for better token efficiency
+- 🔧 **API Enhancement:** Cloud API provider now includes approval status and flaky screenshot detection
+  - Added approval status breakdown (pending/approved/rejected/auto_approved)
+  - Added flaky screenshot count
+  - Added hot spot coverage metadata for quick triage
+
+### Changed
+- 🔧 **Internal:** `acceptBaseline()` in TDD service now accepts both comparison ID (string) or full comparison object
+  - Enables accepting baselines from report-data.json without in-memory lookup
+  - Fixes issue where accepting from dashboard wasn't working properly
+
+### Fixed
+- 🐛 Fixed path bug in local TDD provider: `screenshots/` → `current/` directory
+- 🐛 Fixed API field mapping in cloud provider: API returns `result` not `status`
+
 ## [0.1.0] - 2025-10-18
 
 ### Added

package/claude-plugin/mcp/vizzly-docs-server/README.md

@@ -0,0 +1,95 @@
+# Vizzly Docs MCP Server
+
+MCP server that provides Claude Code with easy access to Vizzly documentation.
+
+## How It Works
+
+This server fetches documentation from the deployed `docs.vizzly.dev` site, making it easy for LLMs to:
+- Browse all available docs
+- Search documentation by keyword
+- Retrieve full markdown content
+- Understand the documentation structure
+
+## Tools
+
+### `list_docs`
+List all available documentation pages with optional category filtering.
+
+**Arguments:**
+- `category` (optional): Filter by category (e.g., "Integration > CLI", "Features")
+
+**Example:**
+```javascript
+list_docs({ category: "CLI" })
+```
+
+### `get_doc`
+Get the full markdown content of a specific documentation page.
+
+**Arguments:**
+- `path` (required): The document path (e.g., "integration/cli/overview.mdx") or slug (e.g., "integration/cli/overview")
+
+**Example:**
+```javascript
+get_doc({ path: "integration/cli/tdd-mode" })
+```
+
+### `search_docs`
+Search documentation by keyword. Searches in titles, descriptions, and categories.
+
+**Arguments:**
+- `query` (required): Search query
+- `limit` (optional): Maximum number of results (default: 10)
+
+**Example:**
+```javascript
+search_docs({ query: "parallel builds", limit: 5 })
+```
+
+### `get_sidebar`
+Get the complete sidebar navigation structure.
+
+**Example:**
+```javascript
+get_sidebar()
+```
+
+## Architecture
+
+The server works in a hybrid model:
+1. **Index** - Fetches a pre-built JSON index from `docs.vizzly.dev/api/mcp-index.json`
+2. **Content** - Fetches individual doc content on-demand from `docs.vizzly.dev/api/content/{path}`
+3. **Caching** - Index is cached for 5 minutes to minimize network requests
+
+This approach ensures:
+- Fast browsing/searching (uses cached index)
+- Always up-to-date content (fetched from live site)
+- Minimal network overhead
+- No local file dependencies
+
+## Data Flow
+
+```
+Claude Code
+    ↓
+MCP Server (this)
+    ↓
+docs.vizzly.dev API
+    ↓
+Statically generated at build time (Astro)
+```
+
+## Development
+
+To test the server locally:
+
+```bash
+# The server is automatically loaded by Claude Code when the plugin is active
+# Check .mcp.json for configuration
+```
+
+## Files
+
+- `index.js` - Main MCP server implementation
+- `docs-fetcher.js` - Utilities for fetching and searching docs
+- `README.md` - This file

package/claude-plugin/mcp/vizzly-docs-server/docs-fetcher.js

@@ -0,0 +1,110 @@
+/**
+ * Fetches documentation from docs.vizzly.dev
+ */
+
+let BASE_URL = 'https://docs.vizzly.dev';
+let INDEX_URL = `${BASE_URL}/api/mcp-index.json`;
+
+/**
+ * Fetch the documentation index
+ */
+export async function fetchDocsIndex() {
+  try {
+    let response = await fetch(INDEX_URL);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch docs index: ${response.status} ${response.statusText}`);
+    }
+
+    let index = await response.json();
+    return index;
+  } catch (error) {
+    throw new Error(`Failed to load documentation index: ${error.message}`);
+  }
+}
+
+/**
+ * Fetch the content of a specific document
+ */
+export async function fetchDocContent(path) {
+  // Normalize path (remove leading slash, ensure it doesn't end with .md/.mdx)
+  let cleanPath = path.replace(/^\//, '').replace(/\.(mdx?|md)$/, '');
+
+  let contentUrl = `${BASE_URL}/api/content/${cleanPath}`;
+
+  try {
+    let response = await fetch(contentUrl);
+
+    if (!response.ok) {
+      // Try with .mdx extension if not found
+      if (response.status === 404 && !path.endsWith('.mdx')) {
+        contentUrl = `${BASE_URL}/api/content/${cleanPath}.mdx`;
+        response = await fetch(contentUrl);
+      }
+
+      if (!response.ok) {
+        throw new Error(`Document not found: ${path} (${response.status})`);
+      }
+    }
+
+    let content = await response.text();
+    return content;
+  } catch (error) {
+    throw new Error(`Failed to fetch document content: ${error.message}`);
+  }
+}
+
+/**
+ * Search documents by query
+ * Simple client-side search through titles and descriptions
+ */
+export function searchDocs(docs, query, limit = 10) {
+  let lowerQuery = query.toLowerCase();
+  let terms = lowerQuery.split(/\s+/);
+
+  let results = docs
+    .map(doc => {
+      let titleLower = doc.title.toLowerCase();
+      let descLower = (doc.description || '').toLowerCase();
+      let categoryLower = doc.category.toLowerCase();
+
+      let score = 0;
+
+      // Exact phrase match in title (highest score)
+      if (titleLower.includes(lowerQuery)) {
+        score += 10;
+      }
+
+      // Exact phrase match in description
+      if (descLower.includes(lowerQuery)) {
+        score += 5;
+      }
+
+      // Exact phrase match in category
+      if (categoryLower.includes(lowerQuery)) {
+        score += 3;
+      }
+
+      // Individual term matches
+      for (let term of terms) {
+        if (titleLower.includes(term)) score += 3;
+        if (descLower.includes(term)) score += 1;
+        if (categoryLower.includes(term)) score += 0.5;
+      }
+
+      return { doc, score };
+    })
+    .filter(result => result.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+
+  // Normalize scores to 0-1 range
+  if (results.length > 0) {
+    let maxScore = results[0].score;
+    for (let result of results) {
+      result.score = result.score / maxScore;
+    }
+  }
+
+  return results;
+}

package/claude-plugin/mcp/vizzly-docs-server/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+/**
+ * Vizzly Docs MCP Server
+ * Provides Claude Code with easy access to Vizzly documentation
+ *
+ * This server fetches docs from the deployed docs.vizzly.dev site,
+ * making it easy for LLMs to navigate and retrieve documentation content.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { fetchDocsIndex, fetchDocContent, searchDocs } from './docs-fetcher.js';
+
+class VizzlyDocsMCPServer {
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'vizzly-docs',
+        version: '1.0.0'
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+
+    // Cache the index for the session
+    this.indexCache = null;
+    this.indexFetchTime = null;
+    this.CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+    this.setupHandlers();
+  }
+
+  /**
+   * Get the docs index (with caching)
+   */
+  async getIndex() {
+    let now = Date.now();
+
+    if (!this.indexCache || !this.indexFetchTime || now - this.indexFetchTime > this.CACHE_TTL) {
+      this.indexCache = await fetchDocsIndex();
+      this.indexFetchTime = now;
+    }
+
+    return this.indexCache;
+  }
+
+  setupHandlers() {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'list_docs',
+          description:
+            'List all available Vizzly documentation pages. Returns title, description, category, and URL for each doc. Optionally filter by category.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              category: {
+                type: 'string',
+                description:
+                  'Optional category filter (e.g., "Integration > CLI", "Features"). Case-insensitive partial match.'
+              }
+            }
+          }
+        },
+        {
+          name: 'get_doc',
+          description:
+            'Get the full markdown content of a specific documentation page. Returns the raw MDX/markdown with frontmatter. Use the path or slug from list_docs.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              path: {
+                type: 'string',
+                description:
+                  'The document path (e.g., "integration/cli/overview.mdx") or slug (e.g., "integration/cli/overview"). Get this from list_docs or search_docs.'
+              }
+            },
+            required: ['path']
+          }
+        },
+        {
+          name: 'search_docs',
+          description:
+            'Search documentation by keyword. Searches in titles and descriptions. Returns matching docs with relevance scores.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              query: {
+                type: 'string',
+                description: 'Search query (e.g., "TDD mode", "authentication", "parallel builds")'
+              },
+              limit: {
+                type: 'number',
+                description: 'Maximum number of results to return (default: 10)',
+                default: 10
+              }
+            },
+            required: ['query']
+          }
+        },
+        {
+          name: 'get_sidebar',
+          description:
+            'Get the complete sidebar navigation structure. Useful for understanding how docs are organized and finding related pages.',
+          inputSchema: {
+            type: 'object',
+            properties: {}
+          }
+        }
+      ]
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async request => {
+      try {
+        switch (request.params.name) {
+          case 'list_docs':
+            return await this.handleListDocs(request.params.arguments);
+
+          case 'get_doc':
+            return await this.handleGetDoc(request.params.arguments);
+
+          case 'search_docs':
+            return await this.handleSearchDocs(request.params.arguments);
+
+          case 'get_sidebar':
+            return await this.handleGetSidebar();
+
+          default:
+            throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    });
+  }
+
+  async handleListDocs(args) {
+    let index = await this.getIndex();
+    let { category } = args || {};
+
+    let docs = index.docs;
+
+    // Filter by category if provided
+    if (category) {
+      let lowerCategory = category.toLowerCase();
+      docs = docs.filter(doc => doc.category.toLowerCase().includes(lowerCategory));
+    }
+
+    // Format response
+    let response = `# Vizzly Documentation (${docs.length} docs)\n\n`;
+
+    if (category) {
+      response += `Filtered by category: "${category}"\n\n`;
+    }
+
+    // Group by category
+    let byCategory = {};
+    for (let doc of docs) {
+      if (!byCategory[doc.category]) {
+        byCategory[doc.category] = [];
+      }
+      byCategory[doc.category].push(doc);
+    }
+
+    for (let [cat, catDocs] of Object.entries(byCategory)) {
+      response += `## ${cat}\n\n`;
+      for (let doc of catDocs) {
+        response += `- **${doc.title}**\n`;
+        response += `  - Path: \`${doc.path}\`\n`;
+        response += `  - Slug: \`${doc.slug}\`\n`;
+        if (doc.description) {
+          response += `  - ${doc.description}\n`;
+        }
+        response += `  - URL: ${doc.url}\n\n`;
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: response
+        }
+      ]
+    };
+  }
+
+  async handleGetDoc(args) {
+    let { path } = args;
+
+    if (!path) {
+      throw new Error('path parameter is required');
+    }
+
+    let content = await fetchDocContent(path);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: content
+        }
+      ]
+    };
+  }
+
+  async handleSearchDocs(args) {
+    let { query, limit = 10 } = args;
+
+    if (!query) {
+      throw new Error('query parameter is required');
+    }
+
+    let index = await this.getIndex();
+    let results = searchDocs(index.docs, query, limit);
+
+    let response = `# Search Results for "${query}"\n\n`;
+    response += `Found ${results.length} matching docs:\n\n`;
+
+    for (let result of results) {
+      response += `## ${result.doc.title}\n`;
+      response += `- **Category:** ${result.doc.category}\n`;
+      response += `- **Path:** \`${result.doc.path}\`\n`;
+      response += `- **Relevance:** ${Math.round(result.score * 100)}%\n`;
+      if (result.doc.description) {
+        response += `- **Description:** ${result.doc.description}\n`;
+      }
+      response += `- **URL:** ${result.doc.url}\n\n`;
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: response
+        }
+      ]
+    };
+  }
+
+  async handleGetSidebar() {
+    let index = await this.getIndex();
+
+    let response = `# Vizzly Documentation Structure\n\n`;
+    response += JSON.stringify(index.sidebar, null, 2);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: response
+        }
+      ]
+    };
+  }
+
+  async run() {
+    let transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+}
+
+// Start the server
+let server = new VizzlyDocsMCPServer();
+server.run().catch(error => {
+  console.error('Server error:', error);
+  process.exit(1);
+});

package/claude-plugin/mcp/vizzly-server/cloud-api-provider.js

@@ -49,27 +49,43 @@ export class CloudAPIProvider {
     let { build } = data;
 
     // Calculate comparison summary
+    // Note: API returns 'result' field (not 'status'), and doesn't have 'has_diff'
+    // result can be: 'identical', 'changed', 'new', 'removed', 'error', 'missing', 'returning'
     let comparisons = build.comparisons || [];
+
+    // Calculate basic comparison summary
+    let changedComparisons = comparisons.filter((c) => c.result === 'changed' || (c.diff_percentage && c.diff_percentage > 0));
+
     let summary = {
       total: comparisons.length,
-      new: comparisons.filter((c) => c.status === 'new').length,
-      changed: comparisons.filter((c) => c.has_diff).length,
-      identical: comparisons.filter((c) => !c.has_diff && c.status !== 'new').length
+      new: comparisons.filter((c) => c.result === 'new').length,
+      changed: changedComparisons.length,
+      identical: comparisons.filter((c) => c.result === 'identical' || (c.result !== 'new' && c.result !== 'changed' && (!c.diff_percentage || c.diff_percentage === 0))).length,
+      // Approval status breakdown
+      approval: {
+        pending: comparisons.filter((c) => c.approval_status === 'pending').length,
+        approved: comparisons.filter((c) => c.approval_status === 'approved').length,
+        rejected: comparisons.filter((c) => c.approval_status === 'rejected').length,
+        autoApproved: comparisons.filter((c) => c.approval_status === 'auto_approved').length
+      },
+      // Flaky screenshot count
+      flaky: comparisons.filter((c) => c.is_flaky).length
     };
 
-    // Group comparisons by status
+    // Keep minimal for token efficiency - use read_comparison_details for full metadata
     let failedComparisons = comparisons
-      .filter((c) => c.has_diff)
+      .filter((c) => c.result === 'changed' || (c.diff_percentage && c.diff_percentage > 0))
       .map((c) => ({
-        name: c.name,
+        id: c.id,
+        name: c.current_name || c.name,
         diffPercentage: c.diff_percentage,
-        currentUrl: c.current_screenshot?.original_url,
-        baselineUrl: c.baseline_screenshot?.original_url,
-        diffUrl: c.diff_image?.url
+        approvalStatus: c.approval_status,
+        // Include hot spot coverage % for quick triage (single number)
+        hotSpotCoverage: c.analysis_metadata?.hot_spot_coverage || null
       }));
 
     let newComparisons = comparisons
-      .filter((c) => c.status === 'new')
+      .filter((c) => c.result === 'new')
       .map((c) => ({
         name: c.name,
         currentUrl: c.current_screenshot?.original_url

package/claude-plugin/mcp/vizzly-server/index.js

@@ -131,6 +131,15 @@ class VizzlyMCPServer {
               workingDirectory: {
                 type: 'string',
                 description: 'Path to project directory (optional, defaults to current directory)'
+              },
+              statusFilter: {
+                type: 'string',
+                description: 'Filter comparisons by status: "failed", "new", "passed", or "all". Defaults to "summary" (no comparisons, just counts)',
+                enum: ['failed', 'new', 'passed', 'all', 'summary']
+              },
+              limit: {
+                type: 'number',
+                description: 'Maximum number of comparisons to return (default: unlimited when statusFilter is set)'
               }
             }
           }
@@ -556,7 +565,11 @@ class VizzlyMCPServer {
           }
 
           case 'get_tdd_status': {
-            let status = await this.localProvider.getTDDStatus(args.workingDirectory);
+            let status = await this.localProvider.getTDDStatus(
+              args.workingDirectory,
+              args.statusFilter,
+              args.limit
+            );
             return {
               content: [
                 {