zephyr-enterprise-tools 1.0.6 → 1.2.1

package/README.md

@@ -53,7 +53,25 @@ export ZEPHYR_TOKEN="your-api-token"
 
 ## 🤖 MCP Integration
 
-Use zephyr-enterprise-tools as an MCP (Model Context Protocol) server with your AI assistant.
+Use zephyr-enterprise-tools as an MCP (Model Context Protocol) server with your AI assistant. The server only requires `ZEPHYR_BASE_URL` and `ZEPHYR_TOKEN` at startup - **Project ID and Release ID are passed as parameters when calling each tool**.
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all Zephyr projects (no parameters needed) |
+| `list_releases` | List releases for a project (requires projectId) |
+| `release_readiness` | Run all 4 quality gates |
+| `requirement_coverage` | Check requirement coverage |
+| `test_plan_analysis` | Analyze test planning status |
+| `test_execution` | Check test execution progress |
+| `defect_quality` | Analyze defect status |
+| `project_health` | Get project health score |
+| `test_coverage` | Get test coverage details |
+| `failed_tests` | List failed tests |
+| `test_trends` | Get execution trends over time |
+| `search_test_cases` | Search test cases by query |
+| `user_activity` | Get user activity metrics |
 
 ### VS Code with GitHub Copilot
 
@@ -65,10 +83,7 @@ Create or edit `.vscode/mcp.json` in your workspace:
     "zephyr-enterprise": {
       "type": "stdio",
       "command": "npx",
-      "args": [
-        "-y",
-        "zephyr-enterprise-tools@latest"
-      ],
+      "args": ["-y", "zephyr-enterprise-tools@latest", "mcp"],
       "env": {
         "ZEPHYR_BASE_URL": "${input:zephyr_base_url}",
         "ZEPHYR_TOKEN": "${input:zephyr_token}"
@@ -101,10 +116,7 @@ Add to your `mcp.json` configuration:
   "mcpServers": {
     "zephyr-enterprise": {
       "command": "npx",
-      "args": [
-        "-y",
-        "zephyr-enterprise-tools@latest"
-      ],
+      "args": ["-y", "zephyr-enterprise-tools@latest", "mcp"],
       "env": {
         "ZEPHYR_BASE_URL": "https://your-zephyr.com/flex/services/rest/latest",
         "ZEPHYR_TOKEN": "your-api-token"
@@ -123,10 +135,7 @@ Edit your `claude_desktop_config.json` file:
   "mcpServers": {
     "zephyr-enterprise": {
       "command": "npx",
-      "args": [
-        "-y",
-        "zephyr-enterprise-tools@latest"
-      ],
+      "args": ["-y", "zephyr-enterprise-tools@latest", "mcp"],
       "env": {
         "ZEPHYR_BASE_URL": "https://your-zephyr.com/flex/services/rest/latest",
         "ZEPHYR_TOKEN": "your-api-token"

package/cli.js

@@ -12,10 +12,22 @@
  *   zephyr-tools --project 364 --release 4312
  *   zephyr-tools -p 364 -r 4312 -t project-health
  *   zephyr-tools -p 364 -r 4312 -t search-tests -q "login"
+ *   zephyr-tools mcp   # Start MCP server
  */
 
 import QualityGates from './zephyr-enterprise-tools.js';
 
+// Check if MCP server mode
+if (process.argv[2] === 'mcp') {
+  import('./mcp-server.js');
+} else {
+  main().catch(err => {
+    console.error(`Error: ${err.message}`);
+    if (process.env.DEBUG) console.error(err.stack);
+    process.exit(1);
+  });
+}
+
 // ─── Parse Arguments ──────────────────────────────────────────────────────────
 
 function parseArgs() {
@@ -535,5 +547,3 @@ async function main() {
     process.exit(1);
   }
 }
-
-main();

package/mcp-server.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+
+/**
+ * Zephyr Enterprise MCP Server
+ * 
+ * Model Context Protocol server for Zephyr Enterprise Tools.
+ * Exposes all tools with projectId and releaseId as runtime parameters.
+ */
+
+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 QualityGates from './zephyr-enterprise-tools.js';
+
+// ─── Tool Definitions ─────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'release_readiness',
+    description: 'Run all 4 quality gates to assess release readiness. Returns GO, CONDITIONAL GO, or NO GO status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'requirement_coverage',
+    description: 'Check if requirements are covered by test cases. Threshold: ≥70% = GO.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'test_plan_analysis',
+    description: 'Analyze test planning status. 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' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'test_execution',
+    description: 'Check test execution progress. Threshold: <90% = NO GO, 90-97% = CONDITIONAL, ≥97% = GO.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'defect_quality',
+    description: 'Analyze defect status. Threshold: Blocker >0 = NO GO, High-risk >10 = NO GO.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'project_health',
+    description: 'Get overall project health score (0-100) with metrics, team info, releases, and recommendations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'test_coverage',
+    description: 'Get detailed test coverage analysis including requirements and test case coverage.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'failed_tests',
+    description: 'List and analyze failed test cases with details.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+        limit: { type: 'number', description: 'Maximum number of failed tests to return (default: 50)' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'requirement_coverage_details',
+    description: 'Get requirements with and without test coverage.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'test_trends',
+    description: 'Get test execution trends over time (daily breakdown).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+        days: { type: 'number', description: 'Number of days to analyze (default: 30)' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'search_test_cases',
+    description: 'Search test cases by query string.',
+    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' },
+        limit: { type: 'number', description: 'Maximum results (default: 50)' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'user_activity',
+    description: 'Get user activity and productivity metrics showing who is assigned and who executed tests.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+        releaseId: { type: 'number', description: 'Zephyr release ID' },
+        days: { type: 'number', description: 'Number of days to analyze (default: 30)' },
+      },
+      required: ['projectId', 'releaseId'],
+    },
+  },
+  {
+    name: 'list_projects',
+    description: 'List all available Zephyr projects.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'list_releases',
+    description: 'List all releases for a project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'number', description: 'Zephyr project ID' },
+      },
+      required: ['projectId'],
+    },
+  },
+];
+
+// ─── MCP Server ───────────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: 'zephyr-enterprise-tools',
+    version: '1.0.6',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Create QualityGates instance
+let tools;
+try {
+  tools = new QualityGates({
+    baseUrl: process.env.ZEPHYR_BASE_URL,
+    token: process.env.ZEPHYR_TOKEN,
+  });
+} catch (err) {
+  console.error(`Configuration error: ${err.message}`);
+  process.exit(1);
+}
+
+// ─── List Tools Handler ───────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+// ─── Call Tool Handler ────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  try {
+    let result;
+    const projectId = args.projectId;
+    const releaseId = args.releaseId;
+    
+    switch (name) {
+      case 'release_readiness':
+        result = await tools.runAllGates(projectId, releaseId);
+        break;
+        
+      case 'requirement_coverage':
+        result = await tools.requirementCoverageGate(projectId, releaseId);
+        break;
+        
+      case 'test_plan_analysis':
+        result = await tools.testPlanAnalysisGate(projectId, releaseId);
+        break;
+        
+      case 'test_execution':
+        result = await tools.testExecutionGate(projectId, releaseId);
+        break;
+        
+      case 'defect_quality':
+        result = await tools.defectQualityGate(projectId, releaseId);
+        break;
+        
+      case 'project_health':
+        result = await tools.getProjectHealth(projectId, releaseId);
+        break;
+        
+      case 'test_coverage':
+        result = await tools.getTestCoverage(projectId, releaseId);
+        break;
+        
+      case 'failed_tests':
+        result = await tools.getFailedTests(projectId, releaseId, { limit: args.limit || 50 });
+        break;
+        
+      case 'requirement_coverage_details':
+        result = await tools.getRequirementCoverage(projectId, releaseId);
+        break;
+        
+      case 'test_trends':
+        result = await tools.getTestCaseTrends(projectId, releaseId, { days: args.days || 30 });
+        break;
+        
+      case 'search_test_cases':
+        result = await tools.searchTestCases(projectId, releaseId, { 
+          query: args.query || '', 
+          limit: args.limit || 50 
+        });
+        break;
+        
+      case 'user_activity':
+        result = await tools.getUserActivity(projectId, releaseId, { days: args.days || 30 });
+        break;
+        
+      case 'list_projects':
+        const projects = await tools.GET('/project');
+        result = {
+          total: projects.length,
+          projects: projects.map(p => ({
+            id: p.id,
+            name: p.name,
+            description: p.description,
+            startDate: p.projectStartDate,
+            endDate: p.projectEndDate,
+          })),
+        };
+        break;
+        
+      case 'list_releases':
+        const releases = await tools.GET('/release', { projectid: projectId, isaliasallowed: false });
+        const filtered = releases.filter(r => !r.projectRelease);
+        result = {
+          projectId,
+          total: filtered.length,
+          releases: filtered.map(r => ({
+            id: r.id,
+            name: r.name,
+            startDate: r.releaseStartDate,
+            endDate: r.releaseEndDate,
+          })),
+        };
+        break;
+        
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+    
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+    
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ─── Start Server ─────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Zephyr Enterprise MCP Server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/package.json

@@ -1,21 +1,31 @@
 {
   "name": "zephyr-enterprise-tools",
-  "version": "1.0.6",
+  "version": "1.2.1",
   "description": "Comprehensive Zephyr Enterprise Tools - Release Readiness, Project Health, Test Analytics & More",
   "main": "zephyr-enterprise-tools.js",
+  "types": "zephyr-enterprise-tools.d.ts",
   "exports": {
-    ".": "./zephyr-enterprise-tools.js",
-    "./cli": "./cli.js"
+    ".": {
+      "import": "./zephyr-enterprise-tools.js",
+      "types": "./zephyr-enterprise-tools.d.ts"
+    },
+    "./cli": "./cli.js",
+    "./mcp": "./mcp-server.js"
   },
   "bin": {
     "zephyr-gates": "cli.js",
-    "zephyr-tools": "cli.js"
+    "zephyr-tools": "cli.js",
+    "zephyr-mcp": "mcp-server.js"
   },
   "type": "module",
   "scripts": {
     "start": "node cli.js",
+    "mcp": "node mcp-server.js",
     "test": "node cli.js --help"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
   "keywords": [
     "zephyr",
     "zephyr-enterprise",
@@ -46,7 +56,9 @@
   },
   "files": [
     "zephyr-enterprise-tools.js",
+    "zephyr-enterprise-tools.d.ts",
     "cli.js",
+    "mcp-server.js",
     "README.md",
     "LICENSE"
   ]

package/zephyr-enterprise-tools.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Zephyr Enterprise Tools - TypeScript Declarations
+ */
+
+export interface ZephyrConfig {
+  baseUrl?: string;
+  token?: string;
+}
+
+export interface ThresholdConfig {
+  requirementCoverage: { go: number; description: string };
+  testPlanAnalysis: { noGo: number; conditionalGo: number; description: string };
+  testExecution: { noGo: number; conditionalGo: number; description: string };
+  defectQuality: { blockerLimit: number; highRiskLimit: number; description: string };
+}
+
+export type GateStatus = "GO" | "CONDITIONAL GO" | "NO GO";
+export type HealthStatus = "HEALTHY" | "MODERATE" | "AT RISK" | "CRITICAL";
+
+export interface GateResult {
+  gate: string;
+  status: GateStatus;
+  statusMessage: string;
+  [key: string]: unknown;
+}
+
+export interface RequirementCoverageResult extends GateResult {
+  coveragePercentage: number;
+  coveredRequirements: number;
+  notCoveredRequirements: number;
+  totalRequirements: number;
+}
+
+export interface TestPlanResult extends GateResult {
+  overallPlanningPercentage: number;
+  totalTests: number;
+  plannedTests: number;
+  assignedTests: number;
+}
+
+export interface TestExecutionResult extends GateResult {
+  executionPercentage: number;
+  completedTests: number;
+  totalPlannedTests: number;
+  breakdown: {
+    passed: number;
+    failed: number;
+    blocked: number;
+    wip: number;
+    notExecuted: number;
+  };
+}
+
+export interface DefectQualityResult extends GateResult {
+  totalDefects: number;
+  breakdown: {
+    blocker: { count: number; defects: unknown[] };
+    highRisk: { count: number; defects: unknown[] };
+    lowRisk: { count: number; defects: unknown[] };
+    resolved: { count: number };
+  };
+}
+
+export interface ReleaseReadinessResult {
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  overallStatus: GateStatus;
+  summary: { passed: number; failed: number; conditional: number };
+  recommendation: string;
+  gates: {
+    requirementCoverage: RequirementCoverageResult;
+    testPlanAnalysis: TestPlanResult;
+    testExecution: TestExecutionResult;
+    defectQuality: DefectQualityResult;
+  };
+}
+
+export interface ProjectHealthResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  healthScore: number;
+  healthStatus: HealthStatus;
+  summary: Record<string, unknown>;
+  metrics: Record<string, Record<string, unknown>>;
+  recommendations: string[];
+}
+
+export interface TestCoverageResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  summary: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface FailedTest {
+  testcaseId: number;
+  testcaseKey: string;
+  testcaseName: string;
+  executedBy?: string;
+  [key: string]: unknown;
+}
+
+export interface FailedTestsResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  failedTests: FailedTest[];
+  total: number;
+}
+
+export interface RequirementCoverageDetailResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  results: unknown[];
+  [key: string]: unknown;
+}
+
+export interface TestTrendsResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  dailyTrends: Array<{ date: string; total: number; passed: number; failed: number; blocked: number }>;
+  [key: string]: unknown;
+}
+
+export interface SearchTestCasesOptions {
+  query?: string;
+  limit?: number;
+}
+
+export interface SearchTestCasesResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  results: Array<{ id: number; key: string; name: string; status?: string }>;
+  totalMatches: number;
+  returned: number;
+}
+
+export interface UserActivityOptions {
+  days?: number;
+}
+
+export interface UserActivityResult {
+  tool: string;
+  projectId: number;
+  releaseId: number;
+  timestamp: string;
+  period: { days: number };
+  teamSummary: Record<string, unknown>;
+  assignedTo: unknown[];
+  executedBy: unknown[];
+  topExecutors: unknown[];
+}
+
+export interface FailedTestsOptions {
+  limit?: number;
+}
+
+export interface TrendsOptions {
+  days?: number;
+}
+
+export declare class QualityGates {
+  constructor(config: ZephyrConfig);
+
+  // Quality Gates (Release Readiness)
+  requirementCoverageGate(projectId: number, releaseId: number): Promise<RequirementCoverageResult>;
+  testPlanAnalysisGate(projectId: number, releaseId: number): Promise<TestPlanResult>;
+  testExecutionGate(projectId: number, releaseId: number): Promise<TestExecutionResult>;
+  defectQualityGate(projectId: number, releaseId: number): Promise<DefectQualityResult>;
+  runAllGates(projectId: number, releaseId: number): Promise<ReleaseReadinessResult>;
+
+  // Analytics & Insights
+  getProjectHealth(projectId: number, releaseId: number): Promise<ProjectHealthResult>;
+  getTestCoverage(projectId: number, releaseId: number): Promise<TestCoverageResult>;
+  getFailedTests(projectId: number, releaseId: number, options?: FailedTestsOptions): Promise<FailedTestsResult>;
+  getRequirementCoverage(projectId: number, releaseId: number): Promise<RequirementCoverageDetailResult>;
+  getTestCaseTrends(projectId: number, releaseId: number, options?: TrendsOptions): Promise<TestTrendsResult>;
+  searchTestCases(projectId: number, releaseId: number, options?: SearchTestCasesOptions): Promise<SearchTestCasesResult>;
+  getUserActivity(projectId: number, releaseId: number, options?: UserActivityOptions): Promise<UserActivityResult>;
+}
+
+export declare const THRESHOLDS: ThresholdConfig;
+export declare const RESOLVED_STATUSES: string[];
+export declare const BLOCKER_PRIORITIES: string[];
+export declare const HIGH_RISK_PRIORITIES: string[];
+export declare const LOW_RISK_PRIORITIES: string[];
+
+/** Alias for QualityGates — kept for backward compatibility */
+export { QualityGates as ZephyrTools };
+export default QualityGates;