imperial-mcp-qase 1.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "imperial-mcp-qase",
+  "version": "1.0.0",
+  "description": "MCP server for Qase.io test management - Built by Imperial Healthtech",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "imperial-mcp-qase": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "qase",
+    "test-management",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Imperial Healthtech",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,331 @@
+import type {
+  QaseResponse,
+  QaseListResponse,
+  TestCase,
+  CreateTestCaseInput,
+  UpdateTestCaseInput,
+  ListCasesFilters,
+  Defect,
+  CreateDefectInput,
+  UpdateDefectInput,
+  ListDefectsFilters,
+  TestRun,
+  CreateTestRunInput,
+  ListRunsFilters,
+  TestResult,
+  CreateTestResultInput,
+  Project,
+  ListProjectsFilters,
+} from "./types/qase.js";
+
+const QASE_API_BASE = "https://api.qase.io/v1";
+
+export class QaseApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public errorFields?: Record<string, string[]>
+  ) {
+    super(message);
+    this.name = "QaseApiError";
+  }
+}
+
+export class QaseClient {
+  private apiToken: string;
+
+  constructor(apiToken?: string) {
+    const token = apiToken ?? process.env.QASE_API_TOKEN;
+    if (!token) {
+      throw new Error(
+        "QASE_API_TOKEN is required. Set it via environment variable or pass it to the constructor."
+      );
+    }
+    this.apiToken = token;
+  }
+
+  private async request<T>(
+    method: string,
+    endpoint: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${QASE_API_BASE}${endpoint}`;
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Token": this.apiToken,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const data = await response.json();
+
+    if (!response.ok || data.status === false) {
+      throw new QaseApiError(
+        data.errorMessage ?? `API request failed with status ${response.status}`,
+        response.status,
+        data.errorFields
+      );
+    }
+
+    return data as T;
+  }
+
+  // Project Methods
+  async listProjects(
+    filters?: ListProjectsFilters
+  ): Promise<QaseListResponse<Project>> {
+    const query = this.buildQueryString(filters ?? {});
+    return this.request<QaseListResponse<Project>>("GET", `/project${query}`);
+  }
+
+  private buildQueryString(params: Record<string, unknown>): string {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) {
+        if (Array.isArray(value)) {
+          value.forEach((v) => searchParams.append(`${key}[]`, String(v)));
+        } else {
+          searchParams.append(key, String(value));
+        }
+      }
+    }
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : "";
+  }
+
+  // Test Case Methods
+  async listCases(
+    projectCode: string,
+    filters?: ListCasesFilters
+  ): Promise<QaseListResponse<TestCase>> {
+    const query = this.buildQueryString(filters ?? {});
+    return this.request<QaseListResponse<TestCase>>(
+      "GET",
+      `/case/${projectCode}${query}`
+    );
+  }
+
+  async getCase(
+    projectCode: string,
+    caseId: number
+  ): Promise<QaseResponse<TestCase>> {
+    return this.request<QaseResponse<TestCase>>(
+      "GET",
+      `/case/${projectCode}/${caseId}`
+    );
+  }
+
+  async createCase(
+    projectCode: string,
+    data: CreateTestCaseInput
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "POST",
+      `/case/${projectCode}`,
+      data
+    );
+  }
+
+  async updateCase(
+    projectCode: string,
+    caseId: number,
+    data: UpdateTestCaseInput
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "PATCH",
+      `/case/${projectCode}/${caseId}`,
+      data
+    );
+  }
+
+  async deleteCase(
+    projectCode: string,
+    caseId: number
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "DELETE",
+      `/case/${projectCode}/${caseId}`
+    );
+  }
+
+  // Defect Methods
+  async listDefects(
+    projectCode: string,
+    filters?: ListDefectsFilters
+  ): Promise<QaseListResponse<Defect>> {
+    const query = this.buildQueryString(filters ?? {});
+    return this.request<QaseListResponse<Defect>>(
+      "GET",
+      `/defect/${projectCode}${query}`
+    );
+  }
+
+  async getDefect(
+    projectCode: string,
+    defectId: number
+  ): Promise<QaseResponse<Defect>> {
+    return this.request<QaseResponse<Defect>>(
+      "GET",
+      `/defect/${projectCode}/${defectId}`
+    );
+  }
+
+  async createDefect(
+    projectCode: string,
+    data: CreateDefectInput
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "POST",
+      `/defect/${projectCode}`,
+      data
+    );
+  }
+
+  async updateDefect(
+    projectCode: string,
+    defectId: number,
+    data: UpdateDefectInput
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "PATCH",
+      `/defect/${projectCode}/${defectId}`,
+      data
+    );
+  }
+
+  async resolveDefect(
+    projectCode: string,
+    defectId: number
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "PATCH",
+      `/defect/${projectCode}/resolve/${defectId}`,
+      {}
+    );
+  }
+
+  async deleteDefect(
+    projectCode: string,
+    defectId: number
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "DELETE",
+      `/defect/${projectCode}/${defectId}`
+    );
+  }
+
+  // Test Run Methods
+  async listRuns(
+    projectCode: string,
+    filters?: ListRunsFilters
+  ): Promise<QaseListResponse<TestRun>> {
+    const query = this.buildQueryString(filters ?? {});
+    return this.request<QaseListResponse<TestRun>>(
+      "GET",
+      `/run/${projectCode}${query}`
+    );
+  }
+
+  async getRun(
+    projectCode: string,
+    runId: number
+  ): Promise<QaseResponse<TestRun>> {
+    return this.request<QaseResponse<TestRun>>(
+      "GET",
+      `/run/${projectCode}/${runId}`
+    );
+  }
+
+  async createRun(
+    projectCode: string,
+    data: CreateTestRunInput
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "POST",
+      `/run/${projectCode}`,
+      data
+    );
+  }
+
+  async completeRun(
+    projectCode: string,
+    runId: number
+  ): Promise<QaseResponse<boolean>> {
+    return this.request<QaseResponse<boolean>>(
+      "POST",
+      `/run/${projectCode}/${runId}/complete`,
+      {}
+    );
+  }
+
+  async deleteRun(
+    projectCode: string,
+    runId: number
+  ): Promise<QaseResponse<{ id: number }>> {
+    return this.request<QaseResponse<{ id: number }>>(
+      "DELETE",
+      `/run/${projectCode}/${runId}`
+    );
+  }
+
+  // Test Result Methods
+  async listResults(
+    projectCode: string,
+    runId: number
+  ): Promise<QaseListResponse<TestResult>> {
+    return this.request<QaseListResponse<TestResult>>(
+      "GET",
+      `/result/${projectCode}/${runId}`
+    );
+  }
+
+  async getResult(
+    projectCode: string,
+    runId: number,
+    hash: string
+  ): Promise<QaseResponse<TestResult>> {
+    return this.request<QaseResponse<TestResult>>(
+      "GET",
+      `/result/${projectCode}/${runId}/${hash}`
+    );
+  }
+
+  async createResult(
+    projectCode: string,
+    runId: number,
+    data: CreateTestResultInput
+  ): Promise<QaseResponse<{ hash: string }>> {
+    return this.request<QaseResponse<{ hash: string }>>(
+      "POST",
+      `/result/${projectCode}/${runId}`,
+      data
+    );
+  }
+
+  async createResultBulk(
+    projectCode: string,
+    runId: number,
+    results: CreateTestResultInput[]
+  ): Promise<QaseResponse<{ hash: string }[]>> {
+    return this.request<QaseResponse<{ hash: string }[]>>(
+      "POST",
+      `/result/${projectCode}/${runId}/bulk`,
+      { results }
+    );
+  }
+
+  async deleteResult(
+    projectCode: string,
+    runId: number,
+    hash: string
+  ): Promise<QaseResponse<{ hash: string }>> {
+    return this.request<QaseResponse<{ hash: string }>>(
+      "DELETE",
+      `/result/${projectCode}/${runId}/${hash}`
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { QaseClient } from "./client.js";
+import { registerCaseTools } from "./tools/cases.js";
+import { registerDefectTools } from "./tools/defects.js";
+import { registerRunTools } from "./tools/runs.js";
+import { registerResultTools } from "./tools/results.js";
+import { registerProjectTools } from "./tools/projects.js";
+
+async function main(): Promise<void> {
+  // Initialize the MCP server
+  const server = new McpServer({
+    name: "imperial-mcp-qase",
+    version: "1.0.0",
+  });
+
+  // Initialize Qase client (will use QASE_API_TOKEN from environment)
+  let client: QaseClient;
+  try {
+    client = new QaseClient();
+  } catch (error) {
+    console.error(
+      "Failed to initialize Qase client. Ensure QASE_API_TOKEN environment variable is set."
+    );
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+
+  // Register all tool categories
+  registerProjectTools(server, client);
+  registerCaseTools(server, client);
+  registerDefectTools(server, client);
+  registerRunTools(server, client);
+  registerResultTools(server, client);
+
+  // Connect to stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Handle graceful shutdown
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/tools/cases.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { QaseClient, QaseApiError } from "../client.js";
+
+// Zod schemas for validation
+const ListCasesSchema = {
+  project_code: z.string().describe("Qase project code (e.g., 'DEMO', 'BPJS')"),
+  limit: z.number().optional().describe("Maximum number of results (default: 100)"),
+  offset: z.number().optional().describe("Offset for pagination"),
+  search: z.string().optional().describe("Search query to filter cases by title"),
+  suite_id: z.number().optional().describe("Filter by test suite ID"),
+  milestone_id: z.number().optional().describe("Filter by milestone ID"),
+  severity: z.array(z.number()).optional().describe("Filter by severity (0=not set, 1=blocker, 2=critical, 3=major, 4=normal, 5=minor, 6=trivial)"),
+  priority: z.array(z.number()).optional().describe("Filter by priority (0=not set, 1=high, 2=medium, 3=low)"),
+  type: z.array(z.number()).optional().describe("Filter by type (0=other, 1=functional, 2=smoke, 3=regression, etc.)"),
+  automation: z.array(z.number()).optional().describe("Filter by automation status (0=not automated, 1=to be automated, 2=automated)"),
+};
+
+const GetCaseSchema = {
+  project_code: z.string().describe("Qase project code (e.g., 'DEMO', 'BPJS')"),
+  case_id: z.number().describe("Test case ID"),
+};
+
+const TestStepSchema = z.object({
+  action: z.string().describe("Step action/description"),
+  expected_result: z.string().optional().describe("Expected result for the step"),
+  data: z.string().optional().describe("Test data for the step"),
+  position: z.number().optional().describe("Step position (order)"),
+});
+
+const CreateCaseSchema = {
+  project_code: z.string().describe("Qase project code (e.g., 'DEMO', 'BPJS')"),
+  title: z.string().describe("Test case title"),
+  description: z.string().optional().describe("Test case description"),
+  preconditions: z.string().optional().describe("Test preconditions"),
+  postconditions: z.string().optional().describe("Test postconditions"),
+  severity: z.number().optional().describe("Severity (0=not set, 1=blocker, 2=critical, 3=major, 4=normal, 5=minor, 6=trivial)"),
+  priority: z.number().optional().describe("Priority (0=not set, 1=high, 2=medium, 3=low)"),
+  type: z.number().optional().describe("Type (0=other, 1=functional, 2=smoke, 3=regression, etc.)"),
+  layer: z.number().optional().describe("Layer (0=unknown, 1=e2e, 2=api, 3=unit)"),
+  is_flaky: z.number().optional().describe("Is flaky (0=no, 1=yes)"),
+  behavior: z.number().optional().describe("Behavior (0=not set, 1=positive, 2=negative, 3=destructive)"),
+  automation: z.number().optional().describe("Automation status (0=not automated, 1=to be automated, 2=automated)"),
+  status: z.number().optional().describe("Status (0=actual, 1=draft, 2=deprecated)"),
+  suite_id: z.number().optional().describe("Parent test suite ID"),
+  milestone_id: z.number().optional().describe("Associated milestone ID"),
+  steps: z.array(TestStepSchema).optional().describe("Test steps"),
+  tags: z.array(z.string()).optional().describe("Tags for the test case"),
+};
+
+const UpdateCaseSchema = {
+  project_code: z.string().describe("Qase project code (e.g., 'DEMO', 'BPJS')"),
+  case_id: z.number().describe("Test case ID to update"),
+  title: z.string().optional().describe("Updated test case title"),
+  description: z.string().optional().describe("Updated description"),
+  preconditions: z.string().optional().describe("Updated preconditions"),
+  postconditions: z.string().optional().describe("Updated postconditions"),
+  severity: z.number().optional().describe("Updated severity"),
+  priority: z.number().optional().describe("Updated priority"),
+  type: z.number().optional().describe("Updated type"),
+  layer: z.number().optional().describe("Updated layer"),
+  is_flaky: z.number().optional().describe("Updated flaky status"),
+  behavior: z.number().optional().describe("Updated behavior"),
+  automation: z.number().optional().describe("Updated automation status"),
+  status: z.number().optional().describe("Updated status"),
+  suite_id: z.number().optional().describe("Updated suite ID"),
+  milestone_id: z.number().optional().describe("Updated milestone ID"),
+  steps: z.array(TestStepSchema).optional().describe("Updated test steps"),
+  tags: z.array(z.string()).optional().describe("Updated tags"),
+};
+
+const DeleteCaseSchema = {
+  project_code: z.string().describe("Qase project code (e.g., 'DEMO', 'BPJS')"),
+  case_id: z.number().describe("Test case ID to delete"),
+};
+
+function formatError(error: unknown): string {
+  if (error instanceof QaseApiError) {
+    let message = `Qase API Error (${error.statusCode}): ${error.message}`;
+    if (error.errorFields) {
+      message += `\nField errors: ${JSON.stringify(error.errorFields, null, 2)}`;
+    }
+    return message;
+  }
+  if (error instanceof Error) {
+    return `Error: ${error.message}`;
+  }
+  return `Unknown error: ${String(error)}`;
+}
+
+export function registerCaseTools(server: McpServer, client: QaseClient): void {
+  // List test cases
+  server.tool(
+    "qase_list_cases",
+    "List test cases in a Qase project with optional filtering",
+    ListCasesSchema,
+    async (args) => {
+      try {
+        const { project_code, ...filters } = args;
+        const response = await client.listCases(project_code, filters);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Get single test case
+  server.tool(
+    "qase_get_case",
+    "Get a single test case by ID from a Qase project",
+    GetCaseSchema,
+    async (args) => {
+      try {
+        const response = await client.getCase(args.project_code, args.case_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Create test case
+  server.tool(
+    "qase_create_case",
+    "Create a new test case in a Qase project",
+    CreateCaseSchema,
+    async (args) => {
+      try {
+        const { project_code, ...caseData } = args;
+        const response = await client.createCase(project_code, caseData);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Update test case
+  server.tool(
+    "qase_update_case",
+    "Update an existing test case in a Qase project",
+    UpdateCaseSchema,
+    async (args) => {
+      try {
+        const { project_code, case_id, ...updateData } = args;
+        const response = await client.updateCase(project_code, case_id, updateData);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Delete test case
+  server.tool(
+    "qase_delete_case",
+    "Delete a test case from a Qase project",
+    DeleteCaseSchema,
+    async (args) => {
+      try {
+        const response = await client.deleteCase(args.project_code, args.case_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error) }],
+          isError: true,
+        };
+      }
+    }
+  );
+}