zephyr-enterprise-tools 1.2.4 → 1.2.6

package/README.md

@@ -25,6 +25,7 @@ Comprehensive tools for Zephyr Enterprise - Release Readiness, Project Health, T
 | `test-trends` | Test execution trends over time |
 | `search-tests` | Search test cases by query |
 | `user-activity` | User activity and productivity metrics |
+| `user-trend` | Full audit log history for a user — every action across the system |
 | `execution-burndown` | Day-by-day execution burndown (remaining vs ideal) |
 
 ---
@@ -73,6 +74,7 @@ Use zephyr-enterprise-tools as an MCP (Model Context Protocol) server with your
 | `test_trends` | Get execution trends over time |
 | `search_test_cases` | Search test cases by query |
 | `user_activity` | Get user activity metrics |
+| `user_trend` | Full audit log history for a user — filter by date range, entity type, and operation |
 | `execution_burndown` | Day-by-day execution burndown chart data (remaining vs ideal) |
 
 ### Claude Desktop

package/mcp-server.js

@@ -44,12 +44,13 @@ const TOOLS = [
   },
   {
     name: 'test_plan_analysis',
-    description: 'Analyze test planning status. Threshold: <80% = NO GO, 80-90% = CONDITIONAL, ≥90% = GO.',
+    description: 'Analyze test planning status, optionally scoped to testcase IDs returned by a Zephyr ZQL expression. Threshold: <80% = NO GO, 80-90% = CONDITIONAL, ≥90% = GO.',
     inputSchema: {
       type: 'object',
       properties: {
         projectId: { type: 'number', description: 'Zephyr project ID' },
         releaseId: { type: 'number', description: 'Zephyr release ID' },
+        query: { type: 'string', description: 'Optional Zephyr ZQL expression, e.g. priority = "P1"' },
       },
       required: ['projectId', 'releaseId'],
     },
@@ -142,13 +143,13 @@ const TOOLS = [
   },
   {
     name: 'search_test_cases',
-    description: 'Search test cases by query string.',
+    description: 'Search test cases using a Zephyr ZQL expression, such as priority = "P1".',
     inputSchema: {
       type: 'object',
       properties: {
         projectId: { type: 'number', description: 'Zephyr project ID' },
         releaseId: { type: 'number', description: 'Zephyr release ID' },
-        query: { type: 'string', description: 'Search query string' },
+        query: { type: 'string', description: 'Zephyr ZQL expression, e.g. priority = "P1"' },
         limit: { type: 'number', description: 'Maximum results (default: 50)' },
       },
       required: ['projectId', 'releaseId'],
@@ -272,7 +273,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         break;
         
       case 'test_plan_analysis':
-        result = await tools.testPlanAnalysisGate(projectId, releaseId);
+        result = await tools.testPlanAnalysisGate(projectId, releaseId, { query: args.query });
         break;
         
       case 'test_execution':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
   "types": "zephyr-enterprise-tools.d.ts",

package/zephyr-enterprise-tools.d.ts

@@ -38,6 +38,11 @@ export interface TestPlanResult extends GateResult {
   assignedTests: number;
 }
 
+export interface TestPlanOptions {
+  /** Optional Zephyr ZQL expression, e.g. `priority = "P1"`. */
+  query?: string;
+}
+
 export interface TestExecutionResult extends GateResult {
   executionPercentage: number;
   completedTests: number;
@@ -133,6 +138,7 @@ export interface TestTrendsResult {
 }
 
 export interface SearchTestCasesOptions {
+  /** Zephyr ZQL expression, e.g. `priority = "P1"`. */
   query?: string;
   limit?: number;
 }
@@ -176,7 +182,7 @@ export declare class QualityGates {
 
   // Quality Gates (Release Readiness)
   requirementCoverageGate(projectId: number, releaseId: number): Promise<RequirementCoverageResult>;
-  testPlanAnalysisGate(projectId: number, releaseId: number): Promise<TestPlanResult>;
+  testPlanAnalysisGate(projectId: number, releaseId: number, options?: TestPlanOptions): Promise<TestPlanResult>;
   testExecutionGate(projectId: number, releaseId: number): Promise<TestExecutionResult>;
   defectQualityGate(projectId: number, releaseId: number): Promise<DefectQualityResult>;
   runAllGates(projectId: number, releaseId: number): Promise<ReleaseReadinessResult>;

package/zephyr-enterprise-tools.js

@@ -113,6 +113,50 @@ export class QualityGates {
     return res.json();
   }
 
+  async POSTv3(path, body) {
+    const v3BaseUrl = this.baseUrl.replace('/latest', '/v3');
+    const res = await fetch(`${v3BaseUrl}${path}`, {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json", ...this.authHeader() },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Zephyr v3 API ${res.status}: ${text}`);
+    }
+    return res.json();
+  }
+
+  async searchExecutionsByZql(releaseId, query) {
+    const pageSize = 50;
+    let firstResult = 0;
+    const executions = [];
+
+    while (true) {
+      const response = await this.POSTv3("/advancesearch/zql", {
+        firstresult: firstResult,
+        maxresults: pageSize,
+        entitytype: "execution",
+        order: "testcaseId",
+        isascorder: true,
+        is_cfield: false,
+        releaseid: String(releaseId),
+        projectid: "",
+        word: query,
+        zql: true,
+        isOld: false,
+      });
+      const page = response[0]?.results || response.results || [];
+
+      if (!Array.isArray(page) || page.length === 0) break;
+
+      executions.push(...page);
+      firstResult += page.length;
+    }
+
+    return [...new Map(executions.map(execution => [execution.id, execution])).values()];
+  }
+
   async PUT(path, params, body) {
     const url = new URL(`${this.baseUrl}${path}`);
     for (const [k, v] of Object.entries(params)) {
@@ -163,22 +207,36 @@ export class QualityGates {
 
   // ─── Gate 2: Test Plan Analysis ─────────────────────────────────────────────
 
-  async testPlanAnalysisGate(projectId, releaseId) {
-    const summary = await this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false });
-    
-    const totalTestcases = summary.testcase?.totalTestcaseCount || 0;
-    const mappedRequirements = summary.requirement?.mappedRequirementCount || 0;
-    const totalRequirements = summary.requirement?.totalRequirementCount || 0;
-    
-    // Get all executions for the release
-    const executionData = await this.GET("/execution", {
-      releaseid: releaseId,
-      offset: 0,
-      pagesize: 10000,
-      includeanyoneuser: true,
-    });
-    
-    const executions = executionData.results || executionData || [];
+  async testPlanAnalysisGate(projectId, releaseId, options = {}) {
+    const { query } = options;
+    let totalTestcases;
+    let mappedRequirements;
+    let totalRequirements;
+    let executions;
+
+    if (query) {
+      const [matchingTestcases, matchingExecutions] = await Promise.all([
+        this.searchTestCases(projectId, releaseId, {
+          query,
+          limit: Number.MAX_SAFE_INTEGER,
+        }),
+        this.searchExecutionsByZql(releaseId, query),
+      ]);
+      totalTestcases = matchingTestcases.results.length;
+      executions = matchingExecutions;
+    } else {
+      const summary = await this.GET(`/summary/release/${releaseId}`, { isHideCycleEnabled: false });
+      totalTestcases = summary.testcase?.totalTestcaseCount || 0;
+      mappedRequirements = summary.requirement?.mappedRequirementCount || 0;
+      totalRequirements = summary.requirement?.totalRequirementCount || 0;
+      const executionData = await this.GET("/execution", {
+        releaseid: releaseId,
+        offset: 0,
+        pagesize: 10000,
+        includeanyoneuser: true,
+      });
+      executions = executionData.results || executionData || [];
+    }
     const totalExecutions = Array.isArray(executions) ? executions.length : 0;
     
     // Count assigned executions
@@ -223,6 +281,7 @@ export class QualityGates {
       gate: "Test Plan Analysis",
       projectId,
       releaseId,
+      query: query || undefined,
       analysis: {
         testcasePlanning: {
           totalTestcases,
@@ -234,7 +293,7 @@ export class QualityGates {
           assignedExecutions,
           percentage: executionAssignmentPct,
         },
-        requirementCoverage: {
+        requirementCoverage: query ? undefined : {
           totalRequirements,
           mappedRequirements,
           percentage: totalRequirements > 0 ? Math.round((mappedRequirements / totalRequirements) * 100 * 100) / 100 : 0,
@@ -1031,53 +1090,65 @@ export class QualityGates {
   async searchTestCases(projectId, releaseId, options = {}) {
     const { query = '', status, priority, limit = 50 } = options;
     
-    // Get test cases
-    const params = {
-      projectId: projectId,
-      releaseId: releaseId,
-      offset: 0,
-      maxRecords: 500,
-    };
-    
-    if (query) params.word = query;
-    
     let testcases = [];
-    try {
-      const tcData = await this.GET("/testcase/tree", params);
-      testcases = tcData.results || tcData || [];
-      
-      // Flatten tree structure if needed
-      if (!Array.isArray(testcases)) {
-        testcases = this.flattenTestcaseTree(tcData);
+    if (query) {
+      const pageSize = 5000;
+      let firstResult = 0;
+
+      while (true) {
+        const tcData = await this.POSTv3("/advancesearch/zql", {
+          firstresult: firstResult,
+          maxresults: pageSize,
+          entitytype: "testcase",
+          order: "orderId",
+          isascorder: true,
+          is_cfield: false,
+          releaseid: String(releaseId),
+          projectid: String(projectId),
+          word: query,
+          zql: true,
+          isOld: false,
+        });
+        const page = tcData[0]?.results || tcData.results || [];
+
+        if (!Array.isArray(page) || page.length === 0) break;
+
+        testcases.push(...page);
+        firstResult += page.length;
       }
-    } catch (e) {
-      // Try alternative endpoint
+      testcases = [...new Map(testcases.map(testcase => [testcase.testcase?.id || testcase.id, testcase])).values()];
+    } else {
+      const params = {
+        projectId,
+        releaseId,
+        offset: 0,
+        maxRecords: 500,
+      };
       try {
-        const tcData = await this.GET("/testcase", params);
+        const tcData = await this.GET("/testcase/tree", params);
         testcases = tcData.results || tcData || [];
-      } catch (e2) {
-        return {
-          tool: "Search Test Cases",
-          projectId,
-          releaseId,
-          error: "Unable to fetch test cases",
-          results: [],
-        };
+        if (!Array.isArray(testcases)) {
+          testcases = this.flattenTestcaseTree(tcData);
+        }
+      } catch (e) {
+        try {
+          const tcData = await this.GET("/testcase", params);
+          testcases = tcData.results || tcData || [];
+        } catch (e2) {
+          return {
+            tool: "Search Test Cases",
+            projectId,
+            releaseId,
+            error: "Unable to fetch test cases",
+            results: [],
+          };
+        }
       }
     }
     
     // Filter results
     let filtered = testcases;
     
-    if (query) {
-      const q = query.toLowerCase();
-      filtered = filtered.filter(tc => 
-        (tc.name || '').toLowerCase().includes(q) ||
-        (tc.testcaseKey || tc.alternateId || '').toLowerCase().includes(q) ||
-        (tc.description || '').toLowerCase().includes(q)
-      );
-    }
-    
     if (status) {
       filtered = filtered.filter(tc => 
         (tc.status || '').toLowerCase() === status.toLowerCase()
@@ -1091,17 +1162,20 @@ export class QualityGates {
     }
     
     // Map to clean output
-    const results = filtered.slice(0, limit).map(tc => ({
-      id: tc.id,
-      key: tc.testcaseKey || tc.alternateId,
-      name: tc.name,
-      status: tc.status,
-      priority: tc.priority,
-      automated: tc.automated || tc.isAutomated || false,
+    const results = filtered.slice(0, limit).map(tc => {
+      const testcase = tc.testcase || tc;
+      return {
+      id: testcase.id,
+      key: testcase.testcaseKey || testcase.alternateId || testcase.externalId,
+      name: testcase.name,
+      status: testcase.status,
+      priority: testcase.priority,
+      automated: testcase.automated || testcase.isAutomated || false,
       folder: tc.folderPath || tc.tcrCatalogTreeId?.name,
-      estimatedTime: tc.estimatedTime,
-      tags: tc.tags || [],
-    }));
+      estimatedTime: testcase.estimatedTime,
+      tags: testcase.tags || [],
+      };
+    });
     
     return {
       tool: "Search Test Cases",
@@ -1293,9 +1367,10 @@ export class QualityGates {
 
     // Fetch all executions for the release
     const executionData = await this.GET('/execution', {
-      projectId,
-      releaseId,
-      maxResults: 10000,
+      releaseid: releaseId,
+      offset: 0,
+      pagesize: 10000,
+      includeanyoneuser: true,
     });
     const executions = executionData.results || executionData || [];
     const total = executions.length;