zephyr-scale-mcp-server 0.8.0 → 0.9.0

package/README.md

@@ -8,6 +8,7 @@ Model Context Protocol server for Zephyr Scale test management, supporting both
 - ✅ **Official API-Compliant Schemas**: Tools and data structures match the official Zephyr Scale REST API, ensuring compatibility and reliability.
 - ✅ **Unified Test Case Creation**: A single `create_test_case` tool handles all script types (BDD, Step-by-Step, Plain Text) for a simplified workflow.
 - ✅ **Full Test Lifecycle Management**: Comprehensive tools to create, read, delete test cases, and manage test runs, executions, and folders.
+- ✅ **Execution Reporting & Jira Integration** *(Cloud)*: Report execution results (Pass/Fail/Blocked), attach bugs as Jira issue links, and discover the Zephyr test cycle linked to any Jira story or epic — bridging a Jira ticket straight to its executions.
 - ✅ **Live Templating System**: Use real test cases from your Zephyr instance as templates (`zephyr://testcase/KEY`) to ensure consistency and correct project-specific fields.
 - ✅ **Unified Resource System**: Access live Zephyr data, local files (`file://`), and built-in examples through a consistent URI-based system.
 

package/build/index.js

@@ -3,10 +3,16 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import axios from 'axios';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { toolSchemas } from './tool-schemas.js';
 import { ZephyrToolHandlers } from './tool-handlers.js';
 import { resourceList, readResource, setAxiosInstance } from './resources.js';
 import { createJiraConfig } from './utils.js';
+// Read version from package.json (../ relative to build/index.js at runtime) so
+// it always matches the published package rather than drifting on each release.
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
 class ZephyrServer {
     server;
     toolHandlers;
@@ -14,7 +20,7 @@ class ZephyrServer {
         const jiraConfig = createJiraConfig();
         this.server = new Server({
             name: 'zephyr-server',
-            version: '0.3.1',
+            version: pkg.version,
         }, {
             capabilities: {
                 tools: {},

package/build/tool-schemas.js

@@ -577,3 +577,38 @@ export const toolSchemas = [
         },
     },
 ];
+// MCP tool annotations (behavioral hints, protocol revision 2025-03-26+).
+// Advisory only — clients use them for UX and safety, e.g. auto-approving
+// read-only calls or confirming before a destructive delete. Every tool talks
+// to the remote Zephyr/Jira API, so openWorldHint is true across the board.
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+const TOOL_ANNOTATIONS = {
+    // Reads
+    get_test_case: READ_ONLY,
+    get_folders: READ_ONLY,
+    get_test_run_cases: READ_ONLY,
+    get_test_run: READ_ONLY,
+    get_test_execution: READ_ONLY,
+    search_test_cases_by_folder: READ_ONLY,
+    search_test_runs: READ_ONLY,
+    list_executions_by_cycle: READ_ONLY,
+    get_test_cycles_for_issue: READ_ONLY,
+    // Non-destructive writes (create / update / append)
+    create_test_case: WRITE,
+    update_test_case_bdd: WRITE,
+    create_folder: WRITE,
+    create_test_run: WRITE,
+    update_test_run: WRITE,
+    add_test_cases_to_run: WRITE,
+    update_test_execution: WRITE,
+    // Destructive
+    delete_test_case: DESTRUCTIVE,
+    delete_test_run: DESTRUCTIVE,
+};
+for (const tool of toolSchemas) {
+    const annotations = TOOL_ANNOTATIONS[tool.name];
+    if (annotations)
+        tool.annotations = annotations;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Model Context Protocol (MCP) server for Zephyr Scale test case management with comprehensive STEP_BY_STEP, PLAIN_TEXT, and BDD support",
   "type": "module",
   "main": "./build/index.js",
@@ -53,10 +53,10 @@
   },
   "homepage": "https://github.com/Milo0821/Zephyr_mcp_server#readme",
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "0.6.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "axios": "^1.15.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -10,11 +10,20 @@ import {
   ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import axios from 'axios';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { toolSchemas } from './tool-schemas.js';
 import { ZephyrToolHandlers } from './tool-handlers.js';
 import { resourceList, readResource, setAxiosInstance } from './resources.js';
 import { createJiraConfig } from './utils.js';
 
+// Read version from package.json (../ relative to build/index.js at runtime) so
+// it always matches the published package rather than drifting on each release.
+const pkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+);
+
 class ZephyrServer {
   private server: Server;
   private toolHandlers: ZephyrToolHandlers;
@@ -25,7 +34,7 @@ class ZephyrServer {
     this.server = new Server(
       {
         name: 'zephyr-server',
-        version: '0.3.1',
+        version: pkg.version,
       },
       {
         capabilities: {

package/src/tool-schemas.ts

@@ -576,4 +576,41 @@ export const toolSchemas = [
       required: ['test_run_key', 'test_case_keys'],
     },
   },
-];
+];
+
+// MCP tool annotations (behavioral hints, protocol revision 2025-03-26+).
+// Advisory only — clients use them for UX and safety, e.g. auto-approving
+// read-only calls or confirming before a destructive delete. Every tool talks
+// to the remote Zephyr/Jira API, so openWorldHint is true across the board.
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+
+const TOOL_ANNOTATIONS: Record<string, Record<string, boolean>> = {
+  // Reads
+  get_test_case: READ_ONLY,
+  get_folders: READ_ONLY,
+  get_test_run_cases: READ_ONLY,
+  get_test_run: READ_ONLY,
+  get_test_execution: READ_ONLY,
+  search_test_cases_by_folder: READ_ONLY,
+  search_test_runs: READ_ONLY,
+  list_executions_by_cycle: READ_ONLY,
+  get_test_cycles_for_issue: READ_ONLY,
+  // Non-destructive writes (create / update / append)
+  create_test_case: WRITE,
+  update_test_case_bdd: WRITE,
+  create_folder: WRITE,
+  create_test_run: WRITE,
+  update_test_run: WRITE,
+  add_test_cases_to_run: WRITE,
+  update_test_execution: WRITE,
+  // Destructive
+  delete_test_case: DESTRUCTIVE,
+  delete_test_run: DESTRUCTIVE,
+};
+
+for (const tool of toolSchemas) {
+  const annotations = TOOL_ANNOTATIONS[tool.name];
+  if (annotations) (tool as { annotations?: unknown }).annotations = annotations;
+}