zephyr-enterprise-tools 1.0.0 → 1.0.2

package/README.md

@@ -32,10 +32,10 @@ Comprehensive tools for Zephyr Enterprise - Release Readiness, Project Health, T
 
 ```bash
 # Install from npm
-npm install -g zephyr-Enterprise-tools
+npm install -g zephyr-enterprise-tools
 
 # Or install locally
-npm install zephyr-Enterprise-tools
+npm install zephyr-enterprise-tools
 ```
 
 ---
@@ -55,6 +55,113 @@ export ZEPHYR_TOKEN="your-token"
 
 ---
 
+## 🤖 MCP Integration
+
+Use zephyr-enterprise-tools as an MCP (Model Context Protocol) server with your AI assistant.
+
+### VS Code with GitHub Copilot
+
+Create or edit `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "zephyr-enterprise": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "zephyr-enterprise-tools@latest"
+      ],
+      "env": {
+        "ZEPHYR_BASE_URL": "${input:zephyr_base_url}",
+        "ZEPHYR_USERNAME": "${input:zephyr_username}",
+        "ZEPHYR_PASSWORD": "${input:zephyr_password}",
+        "ZEPHYR_TOKEN": "${input:zephyr_token}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "zephyr_base_url",
+      "type": "promptString",
+      "description": "Zephyr Enterprise API Base URL (e.g. https://your-zephyr.com/flex/services/rest/latest)",
+      "password": false
+    },
+    {
+      "id": "zephyr_username",
+      "type": "promptString",
+      "description": "Zephyr Enterprise Username (for Basic Auth)",
+      "password": false
+    },
+    {
+      "id": "zephyr_password",
+      "type": "promptString",
+      "description": "Zephyr Enterprise Password (for Basic Auth)",
+      "password": true
+    },
+    {
+      "id": "zephyr_token",
+      "type": "promptString",
+      "description": "Zephyr Enterprise Bearer Token (alternative to username/password)",
+      "password": true
+    }
+  ]
+}
+```
+
+### Cursor
+
+Add to your `mcp.json` configuration:
+
+```json
+{
+  "mcpServers": {
+    "zephyr-enterprise": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "zephyr-enterprise-tools@latest"
+      ],
+      "env": {
+        "ZEPHYR_BASE_URL": "https://your-zephyr.com/flex/services/rest/latest",
+        "ZEPHYR_USERNAME": "your-username",
+        "ZEPHYR_PASSWORD": "your-password",
+        "ZEPHYR_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit your `claude_desktop_config.json` file:
+
+```json
+{
+  "mcpServers": {
+    "zephyr-enterprise": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "zephyr-enterprise-tools@latest"
+      ],
+      "env": {
+        "ZEPHYR_BASE_URL": "https://your-zephyr.com/flex/services/rest/latest",
+        "ZEPHYR_USERNAME": "your-username",
+        "ZEPHYR_PASSWORD": "your-password",
+        "ZEPHYR_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Use either `ZEPHYR_USERNAME` + `ZEPHYR_PASSWORD` for Basic Auth, or `ZEPHYR_TOKEN` for Bearer token authentication.
+
+---
+
 ## 🖥️ CLI Usage
 
 ```bash

package/cli.js

@@ -251,6 +251,23 @@ function formatGenericResult(result) {
     console.log(`\nHealth Score: ${icon} ${result.healthScore}/100 (${result.healthStatus})`);
   }
   
+  // Project Summary from v3 API (new section)
+  if (result.projectSummary) {
+    const ps = result.projectSummary;
+    console.log('\n📊 PROJECT SUMMARY (from v3 API):');
+    console.log(`   ┌─────────────────────────────┬──────────────┐`);
+    console.log(`   │ Total Releases              │ ${String(ps.totalReleaseCount).padStart(12)} │`);
+    console.log(`   │ Visible Releases            │ ${String(ps.visibleReleaseCount).padStart(12)} │`);
+    console.log(`   │ Total Test Cases            │ ${String(ps.testcaseCount).padStart(12)} │`);
+    console.log(`   │ Total Executions            │ ${String(ps.executionCount).padStart(12)} │`);
+    console.log(`   │ Team Members                │ ${String(ps.teamCount).padStart(12)} │`);
+    console.log(`   ├─────────────────────────────┼──────────────┤`);
+    console.log(`   │ Automated Test Cases        │ ${String(ps.automatedTestCaseCount).padStart(12)} │`);
+    console.log(`   │ Manual Test Cases           │ ${String(ps.manualTestCaseCount).padStart(12)} │`);
+    console.log(`   │ Automation Percentage       │ ${String(ps.automationPercentage + '%').padStart(12)} │`);
+    console.log(`   └─────────────────────────────┴──────────────┘`);
+  }
+  
   // Summary section
   if (result.summary) {
     console.log('\n📊 SUMMARY:');
@@ -271,6 +288,40 @@ function formatGenericResult(result) {
     }
   }
   
+  // Project info section
+  if (result.project) {
+    const p = result.project;
+    console.log(`\n🏢 PROJECT INFO:`);
+    console.log(`   Name: ${p.name}`);
+    if (p.description) console.log(`   Description: ${p.description}`);
+    if (p.startDate) console.log(`   Start Date: ${p.startDate}`);
+    if (p.endDate) console.log(`   End Date: ${p.endDate}`);
+    if (p.teamCount) console.log(`   Team Count: ${p.teamCount}`);
+    
+    // Members
+    console.log(`\n👥 PROJECT MEMBERS (${p.totalMembers}):`);
+    if (p.members && p.members.length > 0) {
+      for (const member of p.members.slice(0, 10)) {
+        console.log(`   • ${member.name} (${member.role})`);
+      }
+      if (p.totalMembers > 10) console.log(`   ... and ${p.totalMembers - 10} more`);
+    } else {
+      console.log(`   No members assigned to this project`);
+    }
+    
+    // Releases
+    console.log(`\n📦 RELEASES (${p.totalReleases}${p.visibleReleases ? `, ${p.visibleReleases} visible` : ''}):`);
+    if (p.releases && p.releases.length > 0) {
+      for (const rel of p.releases) {
+        const current = rel.isCurrent ? ' ⬅ CURRENT' : '';
+        const dates = rel.startDate && rel.endDate ? ` (${rel.startDate} - ${rel.endDate})` : '';
+        console.log(`   • ${rel.name} [ID: ${rel.id}]${dates}${current}`);
+      }
+    } else {
+      console.log(`   No releases found`);
+    }
+  }
+  
   // Team summary
   if (result.teamSummary) {
     console.log('\n👥 TEAM SUMMARY:');
@@ -279,7 +330,35 @@ function formatGenericResult(result) {
     }
   }
   
-  // Users list
+  // Assigned To list (for User Activity)
+  if (result.assignedTo && result.assignedTo.length > 0) {
+    console.log('\n📋 ASSIGNED TO:');
+    console.log('   ┌─────────────────────────┬────────┬────────┬────────┬────────┐');
+    console.log('   │ User                    │ Assign │ Exec   │ Pass%  │ Comp%  │');
+    console.log('   ├─────────────────────────┼────────┼────────┼────────┼────────┤');
+    for (const user of result.assignedTo.slice(0, 10)) {
+      const name = (user.name || 'Unknown').substring(0, 21).padEnd(23);
+      console.log(`   │ ${name} │ ${String(user.assigned).padEnd(6)} │ ${String(user.executed).padEnd(6)} │ ${String(user.passRate + '%').padEnd(6)} │ ${String(user.completionRate + '%').padEnd(6)} │`);
+    }
+    console.log('   └─────────────────────────┴────────┴────────┴────────┴────────┘');
+    if (result.assignedTo.length > 10) console.log(`   ... and ${result.assignedTo.length - 10} more`);
+  }
+  
+  // Executed By list (for User Activity)
+  if (result.executedBy && result.executedBy.length > 0) {
+    console.log('\n🏃 EXECUTED BY:');
+    console.log('   ┌─────────────────────────┬────────┬────────┬────────┬─────────┐');
+    console.log('   │ User                    │ Exec   │ Passed │ Failed │ Pass%   │');
+    console.log('   ├─────────────────────────┼────────┼────────┼────────┼─────────┤');
+    for (const user of result.executedBy.slice(0, 10)) {
+      const name = (user.name || 'Unknown').substring(0, 21).padEnd(23);
+      console.log(`   │ ${name} │ ${String(user.executed).padEnd(6)} │ ${String(user.passed).padEnd(6)} │ ${String(user.failed).padEnd(6)} │ ${String(user.passRate + '%').padEnd(7)} │`);
+    }
+    console.log('   └─────────────────────────┴────────┴────────┴────────┴─────────┘');
+    if (result.executedBy.length > 10) console.log(`   ... and ${result.executedBy.length - 10} more`);
+  }
+  
+  // Users list (legacy/other tools)
   if (result.users && result.users.length > 0) {
     console.log('\n👤 USERS:');
     console.log('   ┌─────────────────────────┬────────┬────────┬────────┬────────┐');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
   "exports": {

package/zephyr-enterprise-tools.js

@@ -95,6 +95,24 @@ export class QualityGates {
     return this.request("GET", path, params);
   }
 
+  async GETv3(path, params = {}) {
+    // Build v3 URL by replacing /latest with /v3 in baseUrl
+    const v3BaseUrl = this.baseUrl.replace('/latest', '/v3');
+    const url = new URL(`${v3BaseUrl}${path}`);
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url.toString(), {
+      method: "GET",
+      headers: { Accept: "application/json", "Content-Type": "application/json", ...this.authHeader() },
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Zephyr v3 API ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+
   async PUT(path, params, body) {
     const url = new URL(`${this.baseUrl}${path}`);
     for (const [k, v] of Object.entries(params)) {
@@ -545,44 +563,78 @@ export class QualityGates {
   // ═══════════════════════════════════════════════════════════════════════════
 
   async getProjectHealth(projectId, releaseId) {
-    const summary = await this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false });
+    // Fetch project details using v3 summary API, project info, and releases in parallel
+    const [projectSummary, project, allReleases, releaseSummary] = await Promise.all([
+      this.GETv3(`/summary/project/${projectId}`, { isLite: false }),
+      this.GET(`/project/${projectId}`),
+      this.GET('/release', { projectid: projectId, isaliasallowed: false }).catch(() => []),
+      this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false }),
+    ]);
     
-    // Requirements metrics
-    const reqData = summary.requirement || {};
+    // Filter releases for this project (exclude "Project Test Repository")
+    const projectReleases = (Array.isArray(allReleases) ? allReleases : [])
+      .filter(r => r.projectId === projectId && !r.projectRelease);
+    
+    // Get project members and fetch their details
+    const projectMembers = project.members || [];
+    const memberDetails = await Promise.all(
+      projectMembers.slice(0, 20).map(async (m) => {
+        try {
+          const user = await this.GET(`/user/${m.userId}`);
+          return {
+            userId: m.userId,
+            name: user.fullName || `${user.firstName} ${user.lastName}`.trim(),
+            username: user.username,
+            role: m.role?.name || 'Unknown',
+          };
+        } catch (e) {
+          return {
+            userId: m.userId,
+            name: `User ${m.userId}`,
+            role: m.role?.name || 'Unknown',
+          };
+        }
+      })
+    );
+    
+    // Project-level metrics from v3 API
+    const totalTestcases = projectSummary.testcaseCount || 0;
+    const totalExecutions = projectSummary.executionCount || 0;
+    const automatedTestCases = projectSummary.automatedTestCaseCount || 0;
+    const manualTestCases = projectSummary.manualTestCaseCount || 0;
+    const automationPercentage = projectSummary.automationPercentage || 0;
+    const teamCount = projectSummary.teamCount || 0;
+    const totalReleaseCount = projectSummary.totalReleaseCount || 0;
+    const visibleReleaseCount = projectSummary.visibleReleaseCount || 0;
+    
+    // Requirements metrics from release summary
+    const reqData = releaseSummary.requirement || {};
     const totalReqs = reqData.totalRequirementCount || 0;
     const mappedReqs = reqData.mappedRequirementCount || 0;
     const reqCoverage = totalReqs > 0 ? Math.round((mappedReqs / totalReqs) * 100 * 100) / 100 : 0;
     
-    // Test case metrics
-    const tcData = summary.testcase || {};
-    const totalTestcases = tcData.totalTestcaseCount || 0;
-    
-    // Execution metrics
-    const execData = summary.execution || {};
-    const totalExecutions = execData.totalExecutionCount || 0;
-    const passedCount = execData.passedExecutionCount || 0;
-    const failedCount = execData.failedExecutionCount || 0;
-    const blockedCount = execData.blockedExecutionCount || 0;
-    const wipCount = execData.wipExecutionCount || 0;
-    const notExecutedCount = execData.unexecutedCount || 0;
-    
-    const completedExecutions = passedCount + failedCount;
-    const executionRate = totalExecutions > 0 ? Math.round((completedExecutions / totalExecutions) * 100 * 100) / 100 : 0;
-    const passRate = completedExecutions > 0 ? Math.round((passedCount / completedExecutions) * 100 * 100) / 100 : 0;
-    
-    // Defect metrics
-    const defectData = summary.defect || {};
+    // Defect metrics from release summary
+    const defectData = releaseSummary.defect || {};
     const totalDefects = defectData.totalDefectCount || 0;
-    const openDefects = defectData.openDefectCount || totalDefects;
+    let openDefects = 0;
+    if (defectData.statuses) {
+      for (const s of defectData.statuses) {
+        const statusName = (s.status || '').toLowerCase();
+        if (!statusName.includes('done') && !statusName.includes('closed') && !statusName.includes('resolved')) {
+          openDefects += s.defectCount || 0;
+        }
+      }
+    } else {
+      openDefects = totalDefects;
+    }
     
     // Calculate health score (0-100)
+    const automationScore = automationPercentage;
     const reqScore = reqCoverage;
-    const execScore = executionRate;
-    const passScore = passRate;
-    const defectPenalty = Math.min(30, openDefects * 3); // Penalty for open defects
+    const defectPenalty = Math.min(20, openDefects * 2);
     
     const healthScore = Math.max(0, Math.round(
-      (reqScore * 0.25 + execScore * 0.35 + passScore * 0.40) - defectPenalty
+      (automationScore * 0.35 + reqScore * 0.35 + (100 - defectPenalty * 2) * 0.30)
     ));
     
     let healthStatus;
@@ -598,6 +650,16 @@ export class QualityGates {
       timestamp: new Date().toISOString(),
       healthScore,
       healthStatus,
+      projectSummary: {
+        totalReleaseCount,
+        visibleReleaseCount,
+        testcaseCount: totalTestcases,
+        executionCount: totalExecutions,
+        teamCount,
+        automatedTestCaseCount: automatedTestCases,
+        manualTestCaseCount: manualTestCases,
+        automationPercentage,
+      },
       metrics: {
         requirements: {
           total: totalReqs,
@@ -607,23 +669,38 @@ export class QualityGates {
         },
         testCases: {
           total: totalTestcases,
+          automated: automatedTestCases,
+          manual: manualTestCases,
+          automationPercentage,
         },
         executions: {
           total: totalExecutions,
-          passed: passedCount,
-          failed: failedCount,
-          blocked: blockedCount,
-          wip: wipCount,
-          notExecuted: notExecutedCount,
-          executionRate,
-          passRate,
         },
         defects: {
           total: totalDefects,
           open: openDefects,
         },
       },
-      recommendations: this.getHealthRecommendations(healthScore, reqCoverage, executionRate, passRate, openDefects),
+      project: {
+        id: projectId,
+        name: project.name || 'Unknown',
+        description: project.description || '',
+        startDate: project.projectStartDate,
+        endDate: project.projectEndDate,
+        totalMembers: projectMembers.length,
+        members: memberDetails,
+        teamCount,
+        totalReleases: totalReleaseCount,
+        visibleReleases: visibleReleaseCount,
+        releases: projectReleases.map(r => ({
+          id: r.id,
+          name: r.name,
+          startDate: r.releaseStartDate,
+          endDate: r.releaseEndDate,
+          isCurrent: r.id === releaseId,
+        })),
+      },
+      recommendations: this.getHealthRecommendations(healthScore, reqCoverage, automationPercentage, 0, openDefects),
     };
   }
 
@@ -1041,19 +1118,56 @@ export class QualityGates {
     
     const executions = executionData.results || executionData || [];
     
-    // Aggregate by user
-    const userStats = {};
+    // Cache for user names (to avoid multiple API calls)
+    const userCache = {};
+    
+    // Helper to get user name by ID
+    const getUserName = async (userId) => {
+      if (!userId || userId < 0) return null;
+      if (userCache[userId]) return userCache[userId];
+      try {
+        const user = await this.GET(`/user/${userId}`);
+        userCache[userId] = user.fullName || `${user.firstName} ${user.lastName}`.trim() || user.username;
+        return userCache[userId];
+      } catch (e) {
+        return null;
+      }
+    };
+    
+    // Aggregate by assigned user and executor
+    const assignedStats = {};
+    const executorStats = {};
     const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
     
+    // Collect unique executor IDs first
+    const executorIds = new Set();
     for (const exec of executions) {
-      const testerName = exec.lastTestResult?.testerName || exec.testerName || "Unassigned";
-      const testerId = exec.testerId || exec.lastTestResult?.testerId;
+      if (exec.executedBy && exec.executedBy > 0) executorIds.add(exec.executedBy);
+      if (exec.lastTestResult?.testerId && exec.lastTestResult.testerId > 0) {
+        executorIds.add(exec.lastTestResult.testerId);
+      }
+    }
+    
+    // Fetch all executor names in parallel
+    await Promise.all([...executorIds].map(id => getUserName(id)));
+    
+    for (const exec of executions) {
+      // Assigned user
+      const assignedName = exec.testerIdName?.trim() || "Unassigned";
+      const assignedId = exec.testerId;
+      
+      // Executor (who actually ran the test)
+      const executorId = exec.lastTestResult?.testerId || exec.executedBy;
+      const executorName = userCache[executorId] || "Unknown";
+      
       const executedOn = exec.lastTestResult?.executedOn || exec.executedOn;
+      const status = exec.lastTestResult?.executionStatus || exec.status || 0;
       
-      if (!userStats[testerName]) {
-        userStats[testerName] = {
-          userId: testerId,
-          name: testerName,
+      // Track assigned stats
+      if (!assignedStats[assignedName]) {
+        assignedStats[assignedName] = {
+          userId: assignedId,
+          name: assignedName,
           assigned: 0,
           executed: 0,
           passed: 0,
@@ -1062,44 +1176,69 @@ export class QualityGates {
           lastActivity: null,
         };
       }
+      assignedStats[assignedName].assigned++;
       
-      userStats[testerName].assigned++;
-      
-      const status = exec.lastTestResult?.executionStatus || exec.status || 0;
       if (Number(status) > 0) {
-        userStats[testerName].executed++;
+        assignedStats[assignedName].executed++;
+        switch (Number(status)) {
+          case 1: assignedStats[assignedName].passed++; break;
+          case 2: assignedStats[assignedName].failed++; break;
+          case 4: assignedStats[assignedName].blocked++; break;
+        }
+      }
+      
+      // Track executor stats (who actually ran tests)
+      if (Number(status) > 0 && executorId && executorId > 0) {
+        if (!executorStats[executorName]) {
+          executorStats[executorName] = {
+            userId: executorId,
+            name: executorName,
+            executed: 0,
+            passed: 0,
+            failed: 0,
+            blocked: 0,
+            lastActivity: null,
+          };
+        }
         
+        executorStats[executorName].executed++;
         switch (Number(status)) {
-          case 1: userStats[testerName].passed++; break;
-          case 2: userStats[testerName].failed++; break;
-          case 4: userStats[testerName].blocked++; break;
+          case 1: executorStats[executorName].passed++; break;
+          case 2: executorStats[executorName].failed++; break;
+          case 4: executorStats[executorName].blocked++; break;
         }
         
         if (executedOn) {
           const execDate = new Date(executedOn);
-          if (!userStats[testerName].lastActivity || execDate > new Date(userStats[testerName].lastActivity)) {
-            userStats[testerName].lastActivity = executedOn;
+          if (!executorStats[executorName].lastActivity || execDate > new Date(executorStats[executorName].lastActivity)) {
+            executorStats[executorName].lastActivity = executedOn;
           }
         }
       }
     }
     
-    // Convert to array and calculate metrics
-    const users = Object.values(userStats)
+    // Convert to arrays and calculate metrics
+    const assignedUsers = Object.values(assignedStats)
       .map(user => ({
         ...user,
         completionRate: user.assigned > 0 ? Math.round((user.executed / user.assigned) * 100) : 0,
         passRate: user.executed > 0 ? Math.round((user.passed / user.executed) * 100) : 0,
       }))
+      .sort((a, b) => b.assigned - a.assigned);
+    
+    const executors = Object.values(executorStats)
+      .map(user => ({
+        ...user,
+        passRate: user.executed > 0 ? Math.round((user.passed / user.executed) * 100) : 0,
+      }))
       .sort((a, b) => b.executed - a.executed);
     
     // Team summary
-    const teamSummary = users.reduce((acc, user) => ({
-      totalAssigned: acc.totalAssigned + user.assigned,
+    const teamSummary = executors.reduce((acc, user) => ({
       totalExecuted: acc.totalExecuted + user.executed,
       totalPassed: acc.totalPassed + user.passed,
       totalFailed: acc.totalFailed + user.failed,
-    }), { totalAssigned: 0, totalExecuted: 0, totalPassed: 0, totalFailed: 0 });
+    }), { totalExecuted: 0, totalPassed: 0, totalFailed: 0 });
     
     return {
       tool: "User Activity",
@@ -1108,18 +1247,17 @@ export class QualityGates {
       timestamp: new Date().toISOString(),
       period: { days },
       teamSummary: {
+        totalAssigned: executions.length,
         ...teamSummary,
-        activeUsers: users.filter(u => u.executed > 0).length,
-        totalUsers: users.length,
-        teamCompletionRate: teamSummary.totalAssigned > 0 
-          ? Math.round((teamSummary.totalExecuted / teamSummary.totalAssigned) * 100) 
-          : 0,
+        activeExecutors: executors.length,
+        totalAssignees: assignedUsers.length,
         teamPassRate: teamSummary.totalExecuted > 0 
           ? Math.round((teamSummary.totalPassed / teamSummary.totalExecuted) * 100) 
           : 0,
       },
-      users,
-      topPerformers: users.filter(u => u.executed > 0).slice(0, 5),
+      assignedTo: assignedUsers,
+      executedBy: executors,
+      topExecutors: executors.slice(0, 5),
     };
   }
 }